KIF User Guide to the Management APIs
A guide for Key Injection Facilities (KIFs), the first point of interaction on the P2PE chain of custody.
On the P2PE Manager, KIFs are responsible for creating terminals and associating those terminals with the correct partner, client and P2PE key. KIFs are also responsible for logging shipments to merchants (P2PE Manager clients). Our Management APIs help KIFs automate these process by allowing them to integrate P2PE Manager functionality with their own software systems. Typically, a KIF will perform the following actions on the Decryptx Management APIs:
- List information required to create a device, including: partners, clients, device types, and locations.
- Create a device on the P2PEManager.
- Log the shipment of devices to the clients.
- Manage KIF user accounts.
How to Authenticate API Calls
Our Management APIs support basic authentication constructed from the usernames and passwords from the P2PEManager. Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the authorization header that contains the word
Basic, followed by a space and a base64-encoded string username:password. For example, if the username and password are user and password the authentication header is as follows://Authorization: Basic base64(user:pasword)
Authorization: Basic dXNlcjpwYXNzd29yZA==
Listing Information for Device Creation
Several pieces of information are associated with each device on the P2PE Manager. Some of this data, for example, the serial number, firmware version, and firmware updated date, is specific to the device and can be specified directly in the resource. However, some of the information is linked to other resources on the P2PE Manager; this means that the Create a Device API calls must contain references to existing resources. In general, these references are JSON objects with either the resource name of the ID, e.g., { "id": "23"} or { "name": "IDtech SecuRED"}. A reference to the following resources are required when creating a device:
- A KIF
- A partner
- A client
- A device type
- An inject key
The following sample API calls will list the resources required to create a device. These sample API calls are for demonstration purposes only; in a real system you would not want to limit the response arrays to just two entries. Furthermore, there are a number of filters that can be applied to some endpoints, e.g., when retrieving a list of partners, the parent partner can be specified as a filter and only that partner's sub-accounts will be returned.
Development vs Production.
The examples below use the Management APIs certification environment. To evaluate your requests against the production environment, replace the host
cert-apis.p2pemanager.comwithapis.p2pemanager.com.
List all Partner Endpoints:
GET https://cert-apis.p2pemanager.com/api/v1/partners?partner=&take=2&skip=0
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Response:
{
"total": 100,
"data": [
{
"id": "6580",
"name": "ASM Software",
"reference": "asms",
"billingId": "001J000001ngZle",
"verificationPhrase": "The quick brown fox jumps over the lazy dog",
"clientCanOrderEquipment": true,
"parent": {
"id": "73",
"name": "ASM Global"
},
"version": 0,
"location": {
"id": "33644",
"name": "ASM Software Headquarters"
},
"contact": {
"id": "91724"
},
"isActive": true
},
{
"id": "73",
"name": "ASM Global",
"reference": "ASM_GLOBAL",
"billingId": "2",
"verificationPhrase": "donotpassgo",
"clientCanOrderEquipment": true,
"version": 10,
"location": {
"id": "25329",
"name": "ASM Global Headquarters"
},
"contact": {
"id": "71265"
},
"isActive": true
}
]
}
List all of ASM Software's Clients:
GET https://cert-apis.p2pemanager.com/api/v1/clients?partner=6580&take=2&skip=0
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
"total": 1,
"data": [
{
"id": "4684",
"name": "The Tired Window",
"billingId": "001J000001oiXle",
"mid": "220614971581",
"isActive": true,
"version": 0,
"partner": {
"id": "73",
"name": "ASM Global"
},
"directPartner": {
"id": "6580",
"name": "ASM Software"
},
"location": {
"id": "33668",
"name": "The Tired Window Headquarters"
},
"contact": {
"id": "91740"
}
}
]
}
List all Device Types:
GET https://cert-apis.p2pemanager.com/api/v1/deviceTypes
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
"total": 13,
"data": [
{
"id": "23",
"name": "IDtech SecuRED",
"isActive": true
},
{
"id": "9",
"name": "Ingenico iCMP122",
"isActive": true
},
{
"id": "6",
"name": "Ingenico IPP350",
"isActive": true
},
{
"id": "17",
"name": "Ingenico On-Guard",
"isActive": true
},
{
"id": "45",
"name": "LEGACY",
"isActive": true
},
{
"id": "87",
"name": "NOMAD",
"isActive": true
},
{
"id": "43",
"name": "PAX D210",
"isActive": true
},
{
"id": "22",
"name": "PAX S300",
"isActive": true
},
{
"id": "23",
"name": "PAX S500",
"isActive": true
},
{
"id": "25",
"name": "PED2000",
"isActive": false
},
{
"id": "1",
"name": "SecuRED",
"isActive": false
},
{
"id": "4",
"name": "SREDKey",
"isActive": true
},
{
"id": "43",
"name": "WisePad",
"isActive": true
}
]
}
List all Injection Keys:
GET https://cert-apis.p2pemanager.com/api/v1/injectKeys
Authorization: Basic dXNlcjpwYXNzd29yZA==
The ANSI Test Key is listed in the following example; all others have been redacted:
{
"total": 15,
"data": [
{
"id": "1",
"name": "ANSI TEST KEY (3)",
"isActive": true,
"isP2PE": true
}
]
}
List all Device Builds:
GET https://cert-apis.p2pemanager.com/api/v1/deviceBuilds
Authorization: Basic dXNlcjpwYXNzd29yZA==
The SREDKey 2 build is listed in the following example:
{
"total": 150,
"data": [
{
"id": 130,
"name": "SREDKey 2 - PTS 5.X",
"isActive": true,
"deviceType": "SREDKey 2",
"buildNumber": "IDTECH-007",
"appVersion": "N/A",
"hardwareVersion": "80172001(With MSR), 80172002(Without MSR)",
"firmwareVersion": "SREDKEY2 FW v1.00.xxx.xxxx.S",
"whiteListingUsed": true,
"whiteListingBinRanges": "410000",
"configFileName": "4.234.72"
}
]
}
Creating a Device
The following example creates a device with a set of referenced resources. It is important that a unique serial number is specified; however, the name is completely optional and is something that the client might choose to set.
POST https://cert-apis.p2pemanager.com/api/v1/devices
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
"serialNumber": "123123123",
"deviceType": {
"id": "23"
},
"deviceBuild": {
"id": "130"
},
"kif": {
"id": "4"
},
"partner": {
"id": "6580"
},
"client": {
"id": "4684"
},
"injectKey": {
"id": "1"
},
"auditNextDate": "2021-01-19T12:07:13.324Z",
"notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
}
The response object will contain the the new device's ID:
{
"id": "175108"
}
If you retrieve the newly created device, you will see more details:
GET https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
In the response object you can see that the device state was automatically set to Injected. You will also see that a specific KIF user was logged as the creator.
{
"id": "175108",
"serialNumber": "123123123",
"alternateKey": null,
"name": null,
"deviceType": {
"id": "23",
"name": "IDtech SecuRED"
},
"deviceState": {
"id": "2",
"name": "Injected"
},
"kif": {
"id": "4",
"name": "Kriptithe Technologies"
},
"location": {
"id": "4",
"name": "Spencer Tech"
},
"partner": {
"id": "6580",
"name": "ASM Software"
},
"client": {
"id": "4684",
"name": "The Tired Window"
},
"injectKey": {
"id": "1",
"name": "ANSI TEST KEY (3)",
"index": 3
},
"deviceBuild": {
"id" : 130,
"name" : "SREDKey 2 - PTS 5.X",
"buildNumber" : "IDTECH-007"
},
"initializedDate": null,
"activationDate": null,
"auditNextDate": "2021-01-19T12:07:13.324Z",
"auditNotificationDate": null,
"errorCounter": null,
"errorLastDate": null,
"initializedBy": null,
"activatedBy": null,
"createdBy": {
"id": "56",
"userName": "kifuser_1"
},
"modifiedBy": {
"id": "56",
"userName": "kifuser_1"
},
"created": "2017-12-15T14:19:11.000Z",
"modified": "2017-12-15T14:19:11.000Z",
"version": 0,
"notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
}
The response object will contain the new device's ID:
{
"id": "175108"
}
Logging a Shipment
When creating a shipment entry via the POST shipments you must specify the following:
- The client that is going to receive the devices.
- The client's partner.
- A location associated with the client.
- A list of device serial numbers and tamper number pairs.
For example:
POST https://cert-apis.p2pemanager.com/api/v1/shipments
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
"partner": {
"id": "6580"
},
"client": {
"id": "4684"
},
"location": {
"id": "33668"
},
"kif": {
"id": "4"
},
"carrier": "UPS",
"tracking": "1Z999AA10123456784",
"dateShipped": "2017-12-15 15:45:34",
"items": [
{
"tamperLabel": "650WHF6849",
"serialNumber": "123123123"
}
]
}
Response:
{
"id": "323"
}
Once the device is shipped, its state is automatically set to inTransit.
List all shipments, filtered by KIF:
GET https://cert-apis.p2pemanager.com/api/v1/shipments?kif=4&take=2&skip=0
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
"total": 1,
"data": [
{
"id": "c3adfd6c73a25498a6f2b81a6768ed9f",
"carrier": "UPS",
"tracking": "1Z999AA10123456784",
"dateShipped": "2017-12-15T21:45:34.000Z",
"dateReceived": null,
"partner": {
"id": "6580",
"name": "ASM Software"
},
"client": {
"id": "4684",
"name": "The Tired Window"
},
"kif": {
"id": "4",
"name": "Kriptithe Technologies"
},
"shipmentType": "KIF Shipment",
"version": 0
}
]
}
Updated almost 2 years ago