> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runpayments.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server. # Endpoints & Errors ## Service endpoints For full request and response schemas, see the [Terminal API reference](/reference/terminal-api/overview). | Endpoint | Method & path | Description | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | [WebSocket auth token](/reference/terminal-api/authentication-web-socket/generate-ws-token) | `POST /api/ws-token` | Issues a single-use, 60-second token for opening a WebSocket connection to receive interaction status updates. | | [Connect](/reference/terminal-api/terminals/connect-terminal) | `POST /api/terminal/{device_id}/connect` | Establishes a session with the terminal. Optional — all endpoints auto-connect. Use `force: true` to reconnect. | | [Disconnect](/reference/terminal-api/terminals/disconnect-terminal) | `DELETE /api/terminal/{device_id}/disconnect` | Closes the active session, releasing the device. | | [List terminals](/reference/terminal-api/terminals/list-terminals) | `GET /api/terminal` | Returns each terminal's `name`, `device_id`, and `capabilities`. | | [Ping](/reference/terminal-api/terminals/ping-terminal) | `POST /api/terminal/{device_id}/ping` | Confirms the terminal is connected and responsive. Recommended health check before a transaction. | | [Read card](/reference/terminal-api/card-read/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](/reference/terminal-api/card-read/get-read-card-status) | `GET /api/terminal/{device_id}/read-card/{interaction_id}` | Polls the result of a read-card interaction. | | [Charge card](/reference/terminal-api/charge-card/initiate-charge) | `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](/reference/terminal-api/charge-card/get-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](/reference/terminal-api/card-read/cancel-read-card) | `DELETE /api/terminal/{device_id}/cancel/{interaction_id}` | Cancels a pending `read-card` interaction on the terminal. Not supported for `charge-card`. | | [Print receipt](/reference/terminal-api/receipt/print-receipt) | `POST /api/terminal/{device_id}/print-receipt` | Prints or reprints a receipt for the latest transaction in an order. | | [Send receipt](/reference/terminal-api/receipt/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](/docs/guides/payments/card-present/getting-started#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](mailto:integrations@runpayments.io) for provisioning support, UAT device requests, or to confirm endpoint availability for your integration phase.