Skip to main content

Querying Device Information

Updated

Overview

As a requirement to utilize Customer-Present Cloud, payment devices must be registered within the Merchant Gateway Account in order to process Cloud transactions. Utilizing the Device Management API you may query information on a specific POI device, or all devices associated with your gateway account.

You may run a basic query against your entire estate or target a POI Device ID to get information such as the POI Device ID value, the current nickname, dates registered and deregistered, last date used, and more. 

To run these requests, the API request must be authenticated using HTTP Bearer Authentication header and include a Content-Type header.

Authorization: Bearer {SECURITY_KEY}
Content-Type: application/json

 

Query a Single Cloud Device

With the Device Management API you may submit a GET request in order to gather data for a specific device that has been registered within an estate. Using the poiDeviceId variable and security_key, the API will return data for the specific device id.

In order to do so you will need to submit a GET request with the Device Management API Endpoint. This Endpoint may be found within the integration portal under Customer-Present Cloud's Device Estate Management Section.

Here is an example request, which would return the data of a specified device id:

curl --request GET \ --header "Authorization: Bearer {SECURITY_KEY}" \ 
"[EndPoint]/api/v2/devices/list/'poiDeviceId Here'"

The above request will return a response such as:

{
    "poiDevices": [
        {
            "deviceId": "00000000-0000-0000-0000-000000000000",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "000000000000",
            "connectionStatus": "connected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered"
        }
    ]
}

Query Additional Device Information

For certain supported device you may also extra additional data from these requests, such as the device's Wi-Fi connection or its battery charge status. These devices vary and you may confirm if your device is supported for this additional information via the Device Estate Management Documentation found within the Integration portal.

In order to have these additional data points returned within your GET request you will need to include an additional parameter within your API request. You will need to include the currentStatus parameter and set this parameters value to true. Including this parameter and value will then check for any additional data points the device can return and return the supported information within its response.

Here is an example request which utilizes currentStatus on a registered Miura 2021:

curl --request GET \ --header "Authorization: Bearer {SECURITY_KEY}" \ 
"[ENDPOINT]/api/v2/devices/list/'poiDeviceId Here'?currentStatus=true"

The above request will return a response such as:

{
    "poiDevices": [
        {
            "deviceId": "00000000-0000-0000-0000-000000000000",
            "make": "miura",
            "model": "M021",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "00000000000",
            "connectionStatus": "connected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered",
            "batteryInfo": {
                "percent": 100,
                "chargingStatus": true
            },
            "wifiInfo": {
                "status": "Connected",
                "ssid": "MYSSID",
                "internalIp": "192.168.1.100",
                "strength": 100,
                "responseStatus": "ok"
            }
        }
    ]
}

Query All registered Devices

Along with the ability to query specific devices, the API also allows for you to query a list of all the devices that have ever been registered within your estate. Performing this GET request will return similar data to the individual specified device request.

The request for this action will be similar to obtaining an indivdual device's data, with the caveat that a poiDeviceId is not passed within the request. Instead you will need to replace the poiDeviceId with list. Utilizing list will list all of the devices associated with the provided Gateway account.

Here is an example request which will return all device associated with the estate:

curl --header "Authorization: Bearer {SECURITY_KEY}" 
"[ENDPOINT]/api/v2/devices/list"

The above request will return a response such as:

{
    "poiDevices": [
        {
            "deviceId": "00000000-0000-0000-0000-000000000000",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "00000000000000",
            "connectionStatus": "connected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered"
        },
        {
            "deviceId": "00000000-0000-0000-0000-000000000000",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": "2019-11-22 20:50:08",
            "serialNumber": "000000000000",
            "connectionStatus": "disconnected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": "2020-01-11 15:52:42",
            "deviceNickname": "My POI Device",
            "registrationStatus": "deregistered"
        },
        ...
    ]
}

Note: The more devices that are associated within the estate the longer this request may take.