GET devices/:devicekey:
GET /api/v2/paymentengine/devices/:devicekey:
Retrieve information about a device by its device key.
Response Variables
| Variable |
Description |
| type |
"device" |
| key |
Device key |
| apikeyid |
The id of API key (source key) associated with the device. |
| terminal_type |
Terminal type: "standalone" for payment engine cloud based terminal. |
| status |
Current device status |
| name |
Developer assigned device name. Device name can contain letters, numbers, spaces, and dashes. All other characters will be filtered out. |
| settings |
Device settings |
| terminal_info |
Details of terminal |
| terminal_config |
Terminal configuration |
| pairing_code |
If terminal type is 'standalone', this is the pairing code required to pair the payment device with the payment engine. |
| expiration |
If terminal type is 'standalone', the expiration is the date/time that the pairing code is no longer valid. |
Device Settings
| Variable |
Description |
| timeout |
Transaction timeout, how long to wait for transaction authorization to complete. |
| enable_standalone |
Allows transactions to be initiated from terminal (if supported). |
| share_device |
If true, this allows the payment device to be used by other merchants. If false, only the merchant associated with the apikeyid may send transactions to device. |
| notify_update |
If true, device will be notified on all future updates |
| notify_update_next |
If true, device will be notified only on the next update. After notification, this is automatically set back to false. |
| sleep_battery_device |
This is the amount of inactive time (in minutes) before the device enters full sleep if it is running on battery. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep. |
| sleep_battery_display |
This is the amount of inactive time (in minutes) before the device enters display sleep if it is running on battery. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep. |
| sleep_powered_device |
This is the amount of inactive time (in minutes) before the device enters full sleep if it is plugged into power. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep. |
| sleep_powered_display |
This is the amount of inactive time (in minutes) before the device enters display sleep if it is plugged into power. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep. |
Terminal Info
| Variable |
Description |
| make |
Manufacturer |
| model |
Device model |
| revision |
Hardware version number |
| serial |
Device serial number |
| key_pin |
Device PIN encryption key. Only necessary if merchant will be processing transactions with a PIN. |
| key_pan |
Device PAN encryption key. |
Terminal configuration
| Variable |
Description |
| enable_emv |
Enables EMV processing. |
| enable_debit_msr |
Enables PIN debit for swiped transactions. |
| enable_tip_adjust |
Allows EMV transaction amounts to be adjusted after authorization (to add tip). Disables PIN authentication. |
| enable_contactless |
Enables NFC reader. |
Example Request
curl --basic --user APIKEY:PINHASH \
https://EBizCharge.com/api/v2/paymentengine/devices/sa_CCpRfLbkYXNV9rVLdRGvPjwf6ytgN
Example Responses
Device Pending Registration
{
"type": "device",
"key": "sa_WKwzyQawBG0RMy0XpDGFXb6pXA23r",
"apikeyid": "ntC8nP31Moh0wtvYT",
"terminal_type": "standalone",
"status": "waiting for device pairing",
"name": "Register 1",
"pairing_code": 690520,
"expiration": "2019-10-29 11:59:28",
"settings": {
"timeout": 30,
"share_device": false,
"enable_standalone": false,
"sleep_battery_device": 5,
"sleep_battery_display": 1,
"sleep_powered_device": 0,
"sleep_powered_display": 0
},
"terminal_info": {
"make": "Castles",
"model": "VEGA3000",
"revision": "18043001-0055.00",
"serial": "011118170300198",
"key_pin": "FFFF5B04",
"key_pan": "FF908A"
},
"terminal_config": {
"enable_emv": true,
"enable_debit_msr": true,
"enable_tip_adjust": true,
"enable_contactless": true
}
}
Registered Device
{
"type": "device",
"key": "sa_WKwzyQawBG0RMy0XpDGFXb6pXA23r",
"apikeyid": "ntC8nP31Moh0wtvYT",
"terminal_type": "standalone",
"status": "connected",
"name": "Register 1",
"settings": {
"timeout": 30,
"share_device": false,
"enable_standalone": false,
"sleep_battery_device": 5,
"sleep_battery_display": 1,
"sleep_powered_device": 0,
"sleep_powered_display": 0
},
"terminal_info": {
"make": "Castles",
"model": "VEGA3000",
"revision": "18043001-0055.00",
"serial": "011118170300198",
"key_pin": "FFFF5B04",
"key_pan": "FF908A"
},
"terminal_config": {
"enable_emv": true,
"enable_debit_msr": true,
"enable_tip_adjust": true,
"enable_contactless": true
}
}
Errors
| Errorcode |
Message |
Troubleshooting |
| 21121 |
Unknown devicekey xxxxxxx |
Double check that the device key is valid. If the device status was still "waiting for device pairing," the request may have expired. |
GET /devices
GET /v2/paymentengine/devices
Retrieves a list of devices registered to merchant.
Request Parameters
| Variable |
Description |
Default |
| limit |
Max number of results to return |
20 |
| offset |
Number offset to start response |
0 |
Response
The response is in the standard list format.
| Variable |
Description |
| type |
"list" |
| limit |
The max number of items returned in each result set (see limit request param). |
| offset |
The starting point for result set (see offset request param). |
| total |
Total number of records found (useful for calculating how many result sets are available). |
| data |
Array of matched devices, see above for format of each device. |
Example Request
curl --basic --user APIKEY:PINHASH \
https://EBizCharge.com/api/v2/paymentengine/devices
Example Responses
No Devices Found
{
"type": "list",
"limit": 20,
"offset": 0,
"data": [],
"total": 0
}
Single Device
{
"type": "list",
"limit": 20,
"offset": 0,
"data": [
{
"type": "device",
"key": "sa_WKwzyQawBG0RMy0XpDGFXb6pXA23r",
"apikeyid": "ntC8nP31Moh0wtvYT",
"terminal_type": "standalone",
"status": "connected",
"name": "Example",
"settings": {
"timeout": 30,
"enable_standalone": false,
"share_device": false
},
"terminal_info": {
"make": "Castles",
"model": "MP200",
"revision": null,
"serial": "000313162200473"
},
"terminal_config": {
"enable_emv": false,
"enable_debit_msr": false,
"enable_tip_adjust": false,
"enable_contactless": true
}
}
],
"total": 1
}