Device Estate Management

When you need information on a specific POI device, or all devices associated with your gateway account, you can 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.Endpoint https://secure.networkmerchants.com/api/v2/devices/list

Headers Every API request must be authenticated using HTTP Bearer Authentication header and include a Content-Type header.

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

Single POI device request

Send the GET request with the POI Device ID and the data for that specific ID will be returned.

Request:

GET /api/v2/devices/list/:poiDeviceId

Parameter	Type	Required	Description
poiDeviceId	string	yes	The device id returned back as poiDeviceId in the register response.

Example request:

curl --request GET \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.networkmerchants.com/api/v2/devices/list/d352da6e-8772-4433-92f6-a77c4926fd80"

Example response:

{
    "poiDevices": [
        {
            "deviceId": "fc572cda-ae8e-4f21-aa53-d2905c30d696",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "3375191PT103342",
            "connectionStatus": "connected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered"
        }
    ]
}

Additional POI Device information

Send a GET request to the endpoint with a currentStatus parameter set to true to receive extra information about a device. For supported devices it will return information about the device's Wi-Fi connection or its battery charge status.

Wi-Fi information is only returned for Miura devices. Battery information is returned for Ingenico Link 2500 devices and Miura devices. Note: when connected to a power source, Miura devices will return one of three percentage values: 30%, 70% and 100%.

These Wi-FI and battery values are cached for a short period of time, so subsequent queries may result in the same value returned. Data will not be available if a device is performing a transaction.

GET /api/v2/devices/list/:poiDeviceId?currentStatus=true

Example request:

curl --request GET \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.networkmerchants.com/api/v2/devices/list/d352da6e-8772-4433-92f6-a77c4926fd80?currentStatus=true"

Example response:

{
    "poiDevices": [
        {
            "deviceId": "d352da6e-8772-4433-92f6-a77c4926fd80",
            "make": "miura",
            "model": "M021",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "3375191PT103342",
            "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"
            }
        }
    ]
}

All POI Devices associated with an account

Send a GET request to the endpoint without a POI Device ID indicated.

GET /api/v2/devices/list

Example request:

curl --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.networkmerchants.com/api/v2/devices/list"

Example response:

{
    "poiDevices": [
        {
            "deviceId": "fc572cda-ae8e-4f21-aa53-d2905c30d696",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "3629940PT696190",
            "connectionStatus": "connected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered"
        },
        {
            "deviceId": "73c3791a-e619-4d9d-a687-913ceb9721fa",
            "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": "3375191PT103344",
            "connectionStatus": "disconnected",
            "lastConnectedDate": "2020-01-10 15:52:42",
            "lastDisconnectedDate": "2020-01-11 15:52:42",
            "deviceNickname": "My POI Device",
            "registrationStatus": "deregistered"
        },
        ...
    ]
}

POI Devices list associated with an account

Send a GET request to the endpoint without a POI Device ID indicated including disableConnectionInfo paramter with a value of true. This will allow for a faster response when the account has multiple devices while connection details will be omitted.

GET /api/v2/devices/list?disableConnectionInfo=true

Example request:

curl --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.networkmerchants.com/api/v2/devices/list?disableConnectionInfo=true"

Example response:

{
    "poiDevices": [
        {
            "deviceId": "fc572cda-ae8e-4f21-aa53-d2905c30d696",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": null,
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": null,
            "serialNumber": "3629940PT696190",
            "connectionStatus": null,
            "lastConnectedDate": null,
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "registered"
        },
        {
            "deviceId": "73c3791a-e619-4d9d-a687-913ceb9721fa",
            "make": "ingenico",
            "model": "IPP320",
            "lastTransactionDate": "2019-11-22 05:52:08",
            "dateRegistered": "2019-11-21 20:50:08",
            "dateDeregistered": "2020-01-11 15:52:42",
            "serialNumber": "3375191PT103344",
            "connectionStatus": null,
            "lastConnectedDate": null,
            "lastDisconnectedDate": null,
            "deviceNickname": "My POI Device",
            "registrationStatus": "deregistered"
        },
        ...
    ]
}

Error Handling

If successful, the response HTTP status code is 200 OK.

The following HTTP status codes will be returned in the event of various errors:

400 - No Platform ID or no API Key was sent in the request.401 - An invalid API Key was sent in the request.

Response Details

errors arrayAn array of error objects describing what went wrong

errors[0].codeThe gateway response codes .

errors[0].refidA specific error id that can be used for troubleshooting with technical support if necessary.

errors[0].messageA specific message associated with this error. Use the error recovery tips to move past these errors or contact support if necessary.

Example error:

{
    "errors": [
        {
            "code": 300,
            "refid": 12345,
            "message": "Message describing the error"
        },
        ...
    ]
}