Partner User Guide to Management APIs

The Management APIs are designed so that Partners can integrate Client P2PE Manager, functionality to their own platform/service. As Partners are altering resources on behalf of their clients, they have increased access to P2PE resources through the Management APIs when compared to the GUI. For example, a Partner cannot alter a device's state on the P2PE Manager GUI, whereas they can with the Management APIs.

Typically, a Partner will perform the following actions on the Decryptx Management APIs:

  • Manage Sub-Partner accounts.
  • Manage Client Accounts.
  • Manage Client Locations.
  • Manage Devices on behalf of Clients.
  • Manage Attestations on behalf of Clients.
  • In special cases some Partners will manage transactions through the Management APIs. See the separate Transactions API

Listing Existing Resources

When creating resources through the Management APIs, you will have to include references to other resources on the P2PE Manager. In general, these references are JSON objects with either the resource name of id e.g { "id": "23"} or { "name": "IDtech SecuRED"}.

For example, a reference to a Parent resource is required when creating a Sub Partner or a Client. A Client reference is required when creating a Location or Attestation. The following API call samples list the Device and Clients resources:

📘

Development vs Production

These examples use the Management APIs certification environment. To evaluate your requests against the production environment replace the host cert-bluefin.p2pemanager.com with bluefin.p2pemanager.com.

List all Partner Endpoints

GET https://cert-apis.p2pemanager.com/api/v1/partners?take=2&skip=0
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
    "total": 100,
    "data": [
        {
            "id"          : "6580",
            "name"        : "ASM Software",
            "reference"   : "asms",
            "billingId"   : "001J000001ngZle",
            "partnerId"   : "45",
            "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",
            "partnerId"   : "54",
            "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",
            "mid"         : "563423567",
            "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"
            }
        }
    ]
}

At this point, we have our primary reference objects that can be used when creating Sub Partners, Client, Location, and Attestations.

  • { "id" : "73" } - ASM Software Partner
  • { "id" : "4684" } - The Tired Window Client

Creating a Client

The following example outlines how a Partner can create a Client resource. When creating the resource they must include a reference to the Client's direct Partner. The mid is an open field that allows Partner to associate a Client with a Merchant Identifier from their own Software Service. A Location and User resource must also be specified; the values specified in the API call are broken out to standalone Location and User resources. The CardConex ID is a Bluefin specific field.

POST https://cert-apis.p2pemanager.com/api/v1/clients
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "name"        : "The Tired Window",
    "billingId"   : "001J000001oiXle",
    "mid"         : "220614971581",
    "isActive"    : true,
    "directPartner": {
        "id": "6580"
    },
    "location": {
        "name"           : "The Tired Window Headquarters",
        "nameOfBusiness" : "The Tired Window",
        "locationType"   : "Merchant retail location",
        "uniqueId"       : "ce65d83b-2a2c-48c8-b909-d8960e6a1c9b",
        "country" : {
            "code" : "US"
        },
        "address1"          : "123 Main St",
        "address2"          : "Suite 100",
        "city"              : "Atlanta",
        "stateProvince"     : "Georgia",
        "postalCode"        : "30350",
        "mailAddress1"      : "123 Main St",
        "mailAddress2"      : "Suite 100",
        "mailCity"          : "Atlanta",
        "mailStateProvince" : "Georgia",
        "mailPostalCode"    : "30350"
    },
    "contact": {
        "userName"         : "dbackler3",
        "firstName"        : "Dora",
        "lastName"         : "Backler",
        "email"            : "[email protected]",
        "phone"            : "687-251-0960",
        "userRole"         : "Client Admin",
        "isActive"         : true,
        "sendWelcomeEmail" : true
    }
}

The ID of the newly created resource is returned in the response:

{
    "id": "4684"
}

Creating a Location

A Client can have more than one Location associated with their account. The following example creates a second location for our sample The Tired Window Client.

POST https://cert-apis.p2pemanager.com/api/v1/locations
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "client": {
        "id": "4684"
    },
    "name": "The Tired Window Tulsa",
    "nameOfBusiness" : "The Tired Window Tulsa",
    "locationType"   : "Regional Office",
    "uniqueId"       : "ce65d83b-2a2c-48c8-b909-e5460e6a1c9b",
    "country" : {
        "code" : "US"
    },
    "address1" : "123 Main St",
    "address2" : "Suite 100",
    "city"     : "Tulsa",
    "stateProvince" : "Oklahoma",
    "postalCode"   : "30350",
    "mailCountry"  : "United States",
    "mailAddress1" : "123 Main St",
    "mailAddress2" : "Suite 100",
    "mailCity"     : "Tulsa",
    "mailStateProvince" : "Oklahoma",
    "mailPostalCode"    : "30350",
    "notes": ""
}

Creating an Attestation

PCI Compliance Regulations for Point-to-Point Encryption mandate that devices are inspected annually. The following example creates an Attestation record. A reference to the Client must be included in the API call; a list of Device reference objects containing the Devices' Serial Numbers must also be specified. An optional note can also be included.

POST https://cert-apis.p2pemanager.com/api/v1/attestations
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "name"         : "Annual check 2017",
    "completeDate" : "2017-12-25 15:45:34",
    "client": {
        "id": "4684"
    },
    "devices": [
        {
            "serialNumber" : "123123123"
        }
    ],
    "notes" : "This terminal was inspected by Dora."
}

The API call response contains a the device serial number:

[
    {
        "id": "3453455",
        "device": {
            "id": "175108",
            "serialNumber": "123123123"
        }
    }
]

Did this page help you?