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
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 '{"terminal_type":"standalone","name":"Testing","settings":{"share_device":true},"terminal_config":{"enable_emv":true,"enable_contactless":true}}' \
  https://EBizCharge.com/api/v2/paymentengine/devices

Request with Settings and Terminal Config (json)

{
    "terminal_type":"standalone",
    "name":"Testing",
    "settings":{
        "share_device":true
    },
    "terminal_config":{
        "enable_emv":true,
        "enable_contactless":true
    }
}

Response

The response is the standard GET device response.

Example Response

Example Response

{
    "type": "device",
    "key": "sa_WKwzyQawBG0RMy0XpDGFXb6pXA23r",
    "apikeyid": "tvYTIxIhm83SlTO4zU",
    "terminal_type": "standalone",
    "status": "waiting for device pairing",
    "name": "Register 1",
    "settings": {
        "timeout": 30,
        "enable_standalone": false,
        "share_device": false
    },
    "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).