1. Retrieve available terminals
Be sure to check out the API recipe for a simple, step-by-step code example that walks you through the process and helps you get started with this API quickly
1.1 API reference
The Terminals:Browse API reference, including the option to execute real-time requests, can be found at: https://developer.pay.nl/reference/get_terminals
1.2 Authentication
Authentication is conducted via Basic Authentication using:
- Token code (AT-….) as the username and the API token (hash of 40 characters) as the password
You can find the Token code and the API token under the "Merchant" -> "Company information" tab in the PAY. Admin Panel.
1.3 Request
A request via the Terminals:Browse API looks something like this:
curl --request GET \
--url 'https://rest.pay.nl/v2/terminals?limit=100&page=1' \
--header 'accept: application/json'1.3.1 Pagination
The API Terminals:Browse supports pagination. When calling the API, you can use the page and limit fields to retrieve subsequent results.
In the API response, lines 2 (total), 3 (count), and 4 (pages) show how many results and pages are available. The _links object contains the API URLs for the first, previous, next, and last pages.
1.3.2 Filtering
For partners, it's possible to retrieve terminals for submerchants by using the merchant object.
1.4 Response
A response via the Terminals:Browse API looks something like this:
{
"total": 1,
"count": 1,
"terminals": [
{
"code": "TH-1234-1234",
"name": "Terminal Shop",
"attribution": "PAY.nl* CompanyName",
"status": "ACTIVE",
"connectionStatus": "ONLINE",
"merchant": {
"code": "M-3421-2120",
"status": "ACTIVE",
"name": "CompanyName",
"incorporationCountry": "NL"
},
"service": {
"code": "SL-1234-1234",
"status": "ACTIVE",
"name": "Shop",
"mcc": 5992,
"contactPhone": "061111111",
"contactEmail": "[email protected]"
},
"tradeName": {
"code": "TM-1234-1234",
"name": "My trade name"
},
"description": "POI: 5028314",
"hardwareCode": "TL-1234-1234",
"serialNumber": "BHV3603",
"terminalType": "YOMANI Base UNIT NFC",
"supplier": {
"id": 4,
"name": "AtosWorldline",
"terminalId": "123456789"
},
"ecrProtocol": "WEB",
"contractStartDate": "2022-07-11",
"contractEndDate": "2025-07-11",
"paymentTypes": [
"SALE",
"REFUND"
],
"terminalBrands": [
{
"id": 1003,
"name": "V PAY",
"image": "/terminal_brands/1003.svg",
"acquirer": "AWL Europe",
"acquirerTid": "123456",
"acquirerMid": "123456",
"acquirerChecksum": "123",
"paymentTypes": [
"SALE",
"REFUND"
],
"createdAt": "2022-03-18T14:35:21+02:00",
"createdBy": "AT-1233-1322",
"modifiedAt": "2022-03-18T15:24:52+02:00",
"modifiedBy": "AT-1233-1322",
"deletedAt": null,
"deletedBy": null
},
{
"id": 1009,
"name": "MAESTRO",
"image": "/terminal_brands/1009.svg",
"acquirerTid": "123456",
"acquirerChecksum": "123",
"paymentTypes": [
"SALE",
"REFUND"
],
"createdAt": "2022-03-18T14:35:21+02:00",
"createdBy": "AT-1233-1322",
"modifiedAt": "2022-03-18T15:24:52+02:00",
"modifiedBy": "AT-1233-1322",
"deletedAt": null,
"deletedBy": null
}
],
"location": {
"code": "AS-0113-4000",
"streetName": "Deliverylane",
"streetNumber": "70",
"zipCode": "5678CD",
"city": "Amsterdam",
"regionCode": null,
"countryCode": "NL"
},
"settings": {
"refund": {
"allowed": true,
"policyId": "D",
"policyData": {
"refundTrxLimit": 50,
"refundTrxAmount": 1000,
"refundDayLimit": 2000
}
},
"ticketFooter": {
"text": "Thank you",
"translations": {
"text": {
"nl_NL": "Dank u",
"de_DE": "Danke"
}
}
},
"ticketHeader": {
"text": "Hello",
"translations": {
"text": {
"nl_NL": "Hallo",
"de_DE": "Gutentag"
}
}
}
},
"createdAt": "2022-03-18T14:35:21+02:00",
"createdBy": "AT-1233-1322",
"modifiedAt": "2022-03-18T15:24:52+02:00",
"modifiedBy": "AT-1233-1322",
"deletedAt": null,
"deletedBy": null,
"_links": [
{
"href": "/terminals/TH-1234-1234",
"rel": "terminal",
"type": "GET"
}
]
}
],
"_links": {
"self": {
"href": "/terminals?limit=1&page=1",
"rel": "self",
"type": "GET"
},
"first": {
"href": "/terminals?limit=1&page=1"
},
"previous": {
"href": "/terminals?limit=1&page=1"
},
"next": {
"href": "/terminals?limit=1&page=2"
},
"last": {
"href": "/terminals?limit=1&page=4"
}
}
}The response from the Terminals.Browser API contains a large number of variables. The most important ones are listed below:
| Variable | Description |
|---|---|
terminals.code | Unique reference of the card terminal, starting with TH-… |
terminals.connectionStatus | Connection status of the terminal. (only for Wordline terminals) |
terminals.merchant | Merchant to which the terminal is linked (in the case of an Alliance, these can be different sub-merchants). |
terminals.service | Default sales location to which the terminal is linked, starting with SL-… |
terminals.paymentTypes | Types of transactions that can be performed. SALE: Enabled for card transactions. REFUND: Enabled for card transaction refunds |
terminals.terminalBrands | Types of cards that can be processed on the terminal. For example: VISA Debit, VISA Credit, MasterCard Debit, MasterCard Credit, VPAY, Maestro, etc. |
1.5 Recipe
This recipe gives you a quick, step-by-step walkthrough to start using the Terminals:Browse API with ease.
Terminals:GetThe Terminals:Browse API displays all terminals of a merchant. However, if you want to retrieve
information from a single terminal, you can use the Terminals:Get API, specifying the TH-code of the terminal as a parameter.