PayConexDecryptxShieldConex
Request SandboxContact Us

Distribution Channel API Guide

A guide to the API calls required to move a P2PE device from a Key Injection Facility (KIF) to a client via a distribution channel.

Suggest Edits

This guide includes instructions for moving a P2PE device from a KIF to a client. For instructions on how to create a device follow the KIF User Guide to the Management APIs

📘

API vs P2PE Manager UI

The following guide describes an API integration for the distribution of a device from the perspective of the KIF, the distribution channel and the client. Not all parts of this guide have to be integrated via APIs. All actions can be completed on the P2PE Manager UI as well as the APIs. It may be the case that a distribution channel integrates to the APIs and the client uses the P2PE Manager UI.

KIF Actions

When creating a shipment entry via the POST shipments endpoint the KIF must specify the following:

  1. The distribution channel that is going to receive the device.
  2. The distribution channel's partner.
  3. A location associated with the distribution channel.
  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==

{
    "location": {
        "id": 33668
    },
    "kif": {
        "id": 4
    },
    "dcKif": {
        "id": 8 //Where 8 is Distribution Channel’s id
    },
    "carrier": "UPS",
    "tracking": "1Z999AA10123456784",
    "dateShipped": "2017-12-15 15:45:34",
    "items": [
        {
            "tamperLabel": "650WHF6849",
            "serialNumber": "123123123"
        }
    ]
}

The response object will contain the new shipping entry's ID. At this point the device state has been set to inTransit.

{
    "id": 323
}

Distribution Channel Actions

The distribution channel can list all inbound shipments:

GET https://cert-apis.p2pemanager.com/api/v1/shipments?kif=8&direction=incoming&take=2&skip=0
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "total": 1,
    "data": [

        {
            "id": "73",
            "carrier": "UPS",
            "tracking": "1Z999AA10123456784",
            "dateShipped": "2017-12-15T21:45:34.000Z",
            "dateReceived": null,
            "partner": {
                "id": 6580,
                "name": "ASM Software"
            },
            "kif": {
                "id": 4,
                "name": "Kriptithe Technologies"
            },
            "kif": {
                "id": 8,
                "name": "Acme DC"
            },
            "shipmentType": "KIF Shipment",
            "version": 0
        }
    ]
}

When the distribution channel receives the shipment they can register the event by making an API call to the /api/v1/devices/receive endpoint.

POST https://cert-apis.p2pemanager.com/api/v1/devices/receive
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "tamperLabel": "650WHF6849",
    "serialNumber": "123123123"
}

Response:

{
    "id": 4532
}

If the distribution channel is not shipping the device to a client right away, they can set its state to stored.

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "deviceState": {
        "name": "stored"
    }
}

Ship Device to Client

When the distribution channel is ready to allocate a device to a client, they can update the client record on the device with the following API call:

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "client": {
        "id": "4684",
        "name": "The Tired Window"
    }
}

Response:

{
    "id": 175108
}

When creating a shipment entry via the POST shipments endpoint the distribution channel must specify:

  1. The client that is going to receive the device.
  2. The client's partner.
  3. The client's location.
  4. A list of device serial number and tamper number pairs.
POST https://cert-apis.p2pemanager.com/api/v1/shipments
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "partner": {
        "id": "6580"
    },
    "client": {
        "id": "4684"
    },
    "location": {
        "id": 33778
    },
    "carrier": "UPS",
    "tracking": "1Z999AA10123456784",
    "dateShipped": "2017-12-15 15:45:34",
    "items": [
        {
            "tamperLabel": "500WHF7070",
            "serialNumber": "123123123"
        }
    ]
}

Response:

{
    "id": 547345
}

Client Actions

When the client receives the shipment they can register the event by making an API call to the /api/v1/devices/receive endpoint:

POST https://cert-apis.p2pemanager.com/api/v1/devices/receive
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "tamperLabel": "500WHF7070",
    "serialNumber": "123123123"
}

Response:

{
    "id": 3452
}

After the device is received an API call should be made to the /api/v1/devices/receive endpoint that sets the device state to activating. Note: this action is automatically completed when a client receives a device shipment on the P2PE Manager UI.

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "deviceState": {
        "name": "activaing"
    }
}

Response:

{
   "id": 175108
}

To complete the setup, the client must complete a decryption on the terminal.

Updated almost 2 years ago