KIF User Guide to the Management APIs

Key-Injection-Facilities (KIFs) are 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 shippments 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:

  1. List information required to create a Device, including: Partners, Clients, Device Types, and Locations.
  2. Create a device on the P2PEManager.
  3. Log the shipment of Devices to the Clients.
  4. 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

A lot of information is associated with a Device on the P2PE Manager. Some of this data like the serial number, firmware version, 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 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. The API calls are for demonstration purposes, 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.

These examples use the Management APIs certification environment. To evaluate your requests against the production environment replace the host cert-apis.p2pemanager.com with apis.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 this 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 this 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 is specified, however the name is completely optional and is something that the Client might want 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 new Device's ID:

{
    "id": "175108"
}

If we retrieve the newly created Device we 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 1) the Client that is going to receive the Devices, 2) the Client's Partner, 3) a location associated with the Client, and 4) a list of Device serial number 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
        }
    ]
}

Did this page help you?