Device Management

Overview

In order to process CP transactions through the PayConex™ Gateway and payment gateway, the respective device must be registered to your PayConex™ account with the corresponding serial number and device profile metadata. In other words, it is required to activate the device for your account.

The device metadata, the serial number and device model (deviceProfile) most of all, must match the ones extracted from the P2PE payload with the device field. If no device is found under that serial number for the account, the CP transaction is rejected - failing to decrypt device payload.

Before reading this section, please revisit Getting Device Profiles for the full list of device profiles to find the corresponding device model.

🚧

Device Serial

In most cases, the serial number can be found on the back of the device.

🚧

BluePOS

Device registration is also required for the BluePOS application, and merchants may complete this process themselves if they prefer.

For smaller ISVs or similar, the Bluefin operations team takes care of the whole integration for BluePOS.

API Endpoint Overview

Here is the set of API endpoints that V4 API supports for device management.

Also check out API Reference | Devices.

📘

Did you know?

Some of the device profiles have the input/entry mode in their name.

For example, IDTECH_KEYED_ONLY and IDTECH_SWIPED_ONLY.

Also see, Decryptx Parser | API Reference.

Device Registration Rules

The two essential rules for registering a device for your account are:

• Serial Number: The serial number must be unique per PayConex™ account. For example, you cannot register a device under the same serial number for the same account.
• Unique Alias: Same as with the serial number, the device alias must be unique per PayConex™ account.

Device Registration

By applying the Device Registration Rules above, we can register our device with the following request.

📘

Note

We can use this request to register a device for BluePOS as it can be seen from the deviceProfile. The request is the same for other device models with the specific serial and device profile name.

Request

POST /api/v4/accounts/{accountId}/devices

{
  "label": "PAX Store Device 1",
  "serial": "1760039186",
  "alias": "MyStoreDeviceAlias",
  "deviceProfile": "PAX_A80",
  "enabled": true
}

*Required Scopes: pcx:devices:*, pcx:devices:create

Response

In response, we receive the metadata of the newly registered device.

{
  "id": "dvc_1a0e49ec6e0e43d391971c08f3c335bd",
  "label": "PAX Store Device 1",
  "serial": "1760039186",
  "alias": "MyStoreDeviceAlias",
  "deviceProfile": "PAX_A80",
  "enabled": true
}

Request Parameters

Getting a Device

To retrieve the metadata of an individual device, we specify its id in the path.

GET /api/v4/accounts/{accountId}/devices/dvc_1a0e49ec6e0e43d391971c08f3c335bd

*Required Scopes: pcx:devices:*, pcx:devices:read

Response

{
  "id": "dvc_1a0e49ec6e0e43d391971c08f3c335bd",
  "label": "PAX Store Device 1",
  "serial": "1760039186",
  "alias": "MyStoreDeviceAlias",
  "deviceProfile": "PAX_A80",
  "enabled": true
}

Updating a Device

Some of the most common use cases for updating a device is when we need to change its label, alias. We can also update the device profile or serial number if we have used the wrong one during the device registration or similar.

Request Parameters

PATCH /api/v4/accounts/{accountId}/devices/dvc_1a0e49ec6e0e43d391971c08f3c335bd

{
  "label": "MyNewDeviceLabel",
  "alias": "MyNewDeviceAlias",
  "enabled": false
}

*Required Scopes: pcx:devices:*, pcx:devices:update

Response

In response, we receive the newly updated device entry.

{
  "id": "dvc_1a0e49ec6e0e43d391971c08f3c335bd",
  "label": "MyNewDeviceLabel",
  "serial": "1760039186",
  "alias": "MyNewDeviceAlias",
  "deviceProfile": "PAX_A80",
  "enabled": false
}

Getting a List Of Devices

Query Parameters

To get a list of devices associated with your PayConex™ account, use the following API endpoint.

GET /api/v4/accounts/{accountId}/devices

*Required Scopes: pcx:devices:*, pcx:devices:read

Response

[
  {
    "id": "dvc_1a0e49ec6e0e43d391971c08f3c335bd",
    "label": "PAX Store Device 1",
    "serial": "1760039186",
    "alias": "MyStoreDeviceAlias",
    "deviceProfile": "PAX_A80",
    "enabled": true
  },
  {
    "id": "dvc_215d9f86b65b4817b4d73e7ba9b463c9",
    "label": "MyNewDeviceLabel",
    "serial": "1240325860",
    "alias": "MyNewDeviceAlias",
    "deviceProfile": "PAX_A77",
    "enabled": false
  },
  {
    "id": "dvc_066b2c7ea5ad4ed8a88ef25af0c39bd8",
    "label": "My Device label",
    "serial": "1350013033",
    "alias": "MyDeviceAlias2",
    "deviceProfile": "PAX_A35",
    "enabled": true
  }
]

Deleting a Device

In case you switch to a different device or similar, it is optimal to remove the previous/unused one via DELETE HTTP method.

DELETE /api/v4/accounts/{accountId}/devices/dvc_1a0e49ec6e0e43d391971c08f3c335bd

*Required Scopes: pcx:devices:*, pcx:devices:delete

Upon successful deletion, the request returns the 204 status in the response headers.