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:
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.
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.
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. |
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.