API references
Search documentation... ⌘K
Open merchant dashboard
Terminal API
All our references

Connect a device to a terminal

Connect a device to a terminal instance. If the terminal has no device bound, this will bind the provided device_id and generate a fresh API key token (prefixed with reservepay_). If the terminal is already bound to the same device_id, the previous key is revoked and a new one is issued.

If the terminal is bound to a different device, an ALREADY_CONNECTED error is returned.

If the terminal is disabled, NOT_ENABLED is returned.

If the terminal has no installation linked, NOT_CONFIGURED is returned.

Endpoint signature
POST https://api.reservepay.com/terminals/connect-device HTTP/1.1
Content-Type: application/json
Accept: application/json
{
merchant_id: string,
terminal_id: string,
device_id: string,
challenge: string?,
}
Returns: string
New to Reservepay? Read our guide on how to call endpoints to get started.
Request arguments
merchant_id string

Required. The merchant ID this terminal belongs to.

terminal_id string

Required. Terminal ID the device is connected to.

device_id string

Required. Device UUID generated on device.

challenge string

Optional. One-time challenge from the terminal QR code. Validated if provided; required when server enforces challenge mode.

Errors specific to this endpoint
ALREADY_CONNECTED

The terminal is connected to another device.

INVALID_CHALLENGE

The challenge is missing or does not match the terminal's current challenge.

NOT_FOUND

Merchant or terminal could not be found.

NOT_ENABLED

The terminal exists but is disabled; enable it before connecting a device.

NOT_CONFIGURED

The terminal has no installation linked; assign an installation first.

Errors common to all endpoints
UNHANDLED_ERROR

Raised when the server encounters an unexpected internal error.

INVALID_ARGUMENTS

Raised when the request contains invalid or missing parameters.

BAD_VERSION

Raised when requesting an unsupported or deprecated API version.

Open in Markdown
CODE SAMPLES
curl
curl "https://api.reservepay.com/terminals/connect-device" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "merchant_id": "123456789012",
        "terminal_id": "trm_U4vfjCFwwK",
        "device_id": "b3a98022-59cf-4f87-99ed-51a0f1cb135e"      
      }'
Learn how to run these code samples in your terminal by reading our guide.