Assign a payment device

Each payment device must be linked to one of your accounts before it can take payments on that account's behalf. This guide walks through assigning an account to a new device and moving a device between accounts.

How assignments work

Payment devices are provisioned by Rootline — you don't create them through the API. A new device cannot take payments until you assign one of your accounts to it. A device is assigned to a single account at a time; to move it elsewhere, unassign the current account first.

Find a device by serial number

The serial number is printed on the back of every payment device, so it's the most convenient way to look up the matching device_id when you have a terminal in front of you. Pass it as the serial_number query parameter on the list endpoint:

Request

curl 'https://config-api.staging.rootline.com/v1/payment-devices?serial_number=1490123456' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23'

Response

{
    "data":
    [
        {
            "id": "device_3JfCXH5GthP5K14p7iL70o",
            "object": "payment_device",
            "created_at": "2026-04-10T09:00:00.000Z",
            "display_name": "PAX A920 — Front counter",
            "description": "Main checkout terminal",
            "serial_number": "1490123456",
            "assigned_account_ids": ["acc_3VfPsTP2kqnjR6LHnOdpVe"]
        }
    ]
}

Serial numbers are unique per device, so the response contains at most one entry. An empty data array means no device with that serial is visible to you yet — double-check the serial, or reach out to your Rootline point of contact if it should already be provisioned.

Assign an account

Call POST /v1/payment-devices/{id}/assigned-accounts with the account_id you want to authorize. The response is the full updated payment device.

Request

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_3JfCXH5GthP5K14p7iL70o/assigned-accounts' \
  --request POST \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "account_id": "acc_3VfPsTP2kqnjR6LHnOdpVe"
  }'

Response

{
    "id": "device_3JfCXH5GthP5K14p7iL70o",
    "object": "payment_device",
    "created_at": "2026-04-10T09:00:00.000Z",
    "display_name": "PAX A920 — Front counter",
    "description": "Main checkout terminal",
    "serial_number": "1490123456",
    "assigned_account_ids": ["acc_3VfPsTP2kqnjR6LHnOdpVe"]
}

The device is ready to transact for the assigned account immediately. You can now reference it as payment_rails.payment_device_id when starting a payment.

Errors

Status	error_code	When
404	payment_device_not_found	Device does not exist or is not visible to you.
404	account_not_found	Account does not exist or is not visible to you.
422	already_assigned	The account is already in assigned_account_ids.
422	max_assignments_reached	The device is already assigned to another account. Unassign first.
422	invalid_parameters	Body is missing account_id or malformed.

Unassign an account

Call DELETE /v1/payment-devices/{id}/assigned-accounts/{account_id} to remove an account from a device. The response is the full updated payment device with an empty assigned_account_ids.

Request

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_3JfCXH5GthP5K14p7iL70o/assigned-accounts/acc_3VfPsTP2kqnjR6LHnOdpVe' \
  --request DELETE \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23'

Response

{
    "id": "device_3JfCXH5GthP5K14p7iL70o",
    "object": "payment_device",
    "created_at": "2026-04-10T09:00:00.000Z",
    "display_name": "PAX A920 — Front counter",
    "description": "Main checkout terminal",
    "serial_number": "1490123456",
    "assigned_account_ids": []
}

Errors

Status	error_code	When
404	payment_device_not_found	Device does not exist or is not visible to you.
422	not_assigned	The account was not in assigned_account_ids.

Moving a device between accounts

To move a device from one account to another, unassign the current account and then assign the new one. A device cannot be assigned to two accounts at once.