Endpoints & Errors | Run Developers

Service endpoints

For full request and response schemas, see the Terminal API reference.

Endpoint	Method & path	Description
WebSocket auth token	`POST /api/ws-token`	Issues a single-use, 60-second token for opening a WebSocket connection to receive interaction status updates.
Connect	`POST /api/terminal/{device_id}/connect`	Establishes a session with the terminal. Optional — all endpoints auto-connect. Use `force: true` to reconnect.
Disconnect	`DELETE /api/terminal/{device_id}/disconnect`	Closes the active session, releasing the device.
List terminals	`GET /api/terminal`	Returns each terminal’s `name`, `device_id`, and `capabilities`.
Ping	`POST /api/terminal/{device_id}/ping`	Confirms the terminal is connected and responsive. Recommended health check before a transaction.
Read card	`POST /api/terminal/{device_id}/read-card`	Starts a card read (tap, dip, or swipe). Returns an `interaction_id`; result contains the card token for a subsequent Charge request.
Read card status	`GET /api/terminal/{device_id}/read-card/{interaction_id}`	Polls the result of a read-card interaction.
Charge card	`POST /api/terminal/{device_id}/charge-card`	Read, optional signature, charge, and optional print/email in one interaction. Returns an `interaction_id`.
Charge card status	`GET /api/terminal/{device_id}/charge-card/{interaction_id}`	Polls the result of a charge-card interaction, including `stage_errors`.
Cancel interaction	`DELETE /api/terminal/{device_id}/cancel/{interaction_id}`	Cancels a pending `read-card` interaction on the terminal. Not supported for `charge-card`.
Print receipt	`POST /api/terminal/{device_id}/print-receipt`	Prints or reprints a receipt for the latest transaction in an order.
Send receipt	`POST /api/v1/send_receipt`	Emails a receipt from stored transaction data. No device or session required.

HTTP response codes

Code	Status	Description
`200`	OK	Request succeeded.
`202`	Accepted	Interaction accepted (`read-card`, `charge-card`). Retrieve the outcome by polling or WebSocket using the returned `interaction_id`.
`400`	Bad Request	Malformed request or invalid/missing parameters (e.g., `Field amount is invalid`).
`401`	Unauthorized	Access token missing, invalid, or expired — refresh and retry. On `print-receipt`, `{"error":"Failed CardPointe terminal authentication"}` indicates an upstream terminal auth failure instead.
`403`	Forbidden	The credential is valid but the `device_id` isn’t associated with the calling MID.
`404`	Not Found	The terminal, session, or interaction doesn’t exist — including interactions past their 3-minute TTL.
`409`	Conflict	The terminal already has an active session. Resend `connect` with `force: true`.
`422`	Unprocessable Entity	Well-formed but can’t be processed — e.g., cancelling an interaction that isn’t pending, or an invalid receipt email.
`429`	Too Many Requests	The per-credential rate limit was exceeded. Applies to every terminal endpoint — see Rate limiting.
`500`	Internal Server Error	Upstream timeout or processor error. Retry; contact support if it persists.
`503`	Service Unavailable	Service temporarily unavailable. For `read-card` / `charge-card`, the interaction was never queued and is safe to retry.

Print receipt error messages

print-receipt returns 400 with one of these messages, which you can match on:

Message	Cause
`Field trans_id is required`	Missing or invalid parameter.
`Not supported`	Device has no printer.
`No transaction found for the given trans_id`	No match for this merchant.
`No order_id found for the given transaction`	Transaction has no order.
`trans_id is not for the most recent transaction within this order`	Stale reprint attempt.
`Terminal is unavailable.`	Device offline or busy.
`Terminal in merchant mode. Launch customer mode and try again.`	Device in the wrong mode.
`Interaction was cancelled.`	Cancelled at the device.

Upstream vendor errors may also surface as a 400 carrying the vendor’s own message — treat this list as the set you can match on, not an exhaustive set.

Questions?

Contact integrations@runpayments.io for provisioning support, UAT device requests, or to confirm endpoint availability for your integration phase.