POST devices

POST /api/v2/paymentengine/devices

Registers a payment terminal device. The device registration process associates a terminal with a merchant. Depending on the terminal_type, the process may require two steps.

For terminals running the payment engine standalone middleware such as the Castles MP200 a device pairing code is used. When a new terminal is first turned on, it will display a screen prompting for a pairing code. The point of sale software should use API resource to obtain a code. The pairing code is then entered into the terminal. If successful, the terminal should display a welcome idle screen and the API will show a status of "online" in GET /api/v2/paymentengine/devices/:devicekey:.

For security reasons, pairing codes are only valid for a few minutes. If the time limit has expired without the pairing code being entered on the terminal, the pairing code and associated device key are automatically removed.

Once a terminal is successfully paired, it will remain registered until deleted: there is no need to re-register a terminal when it reboots.

Request Parameters

Variable	Description	Required
terminal_type	Type of terminal being registered, currently the only option is 'standalone'.	X
name	A name associated with the terminal. Device name can contain letters, numbers, spaces, and dashes. All other characters will be filtered out.
settings	Device settings
terminal_config	Terminal configuration

Example Requests

Basic Request (curl)

curl --basic --user APIKEY:PINHASH \
  -H "Content-Type: application/json" -X POST \
  https://EBizCharge.com/api/v2/paymentengine/devices \
  -d '{"name":"Register 1","terminal_type":"standalone"}'

Basic Request (json)

{
  "terminal_type": "standalone",
  "name": "Register 1"
}

Request with Settings and Terminal Config (curl)

curl --basic --user APIKEY:PINHASH \
  -H "Content-Type: application/json" -X POST \
    -d '{"name":"Register 1","terminal_type":"standalone","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_config":{"enable_emv":true,"enable_debit_msr":true,"enable_tip_adjust":true,"enable_contactless":true}}' \
  https://EBizCharge.com/api/v2/paymentengine/devices

Request with Settings and Terminal Config (json)

{
  "name": "Register 1",
  "terminal_type": "standalone",
  "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_config": {
    "enable_emv": true,
    "enable_debit_msr": true,
    "enable_tip_adjust": true,
    "enable_contactless": true
  }
}

Response

The response is the standard GET device response.

Example Response

{
    "type": "device",
    "key": "sa_WKwzyQawBG0RMy0XpDGFXb6pXA23r",
    "apikeyid": "tvYTIxIhm83SlTO4zU",
    "terminal_type": "standalone",
    "status": "waiting for device pairing",
    "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
    },
    "pairing_code": 628215,
    "expiration": "2016-10-29 13:20:47",
    "terminal_config": {
        "enable_emv": false,
        "enable_debit_msr": false,
        "enable_tip_adjust": false,
        "enable_contactless": true
    }
}

Errors

Errorcode	Message	Troubleshooting
21113	Required parameter terminal_type was not provided	Make sure to include the terminal_type parameter in your post body.
21114	Unsupported terminal type xxxxxxx	Make sure the terminal type is in the list of supported terminals (see above).