Getting Started | Run Developers

The Run Developer Terminal API is a RESTful web service that uses JSON to encode data for transmission over HTTPS. Requests and responses are exchanged as JSON payloads over standard HTTPS methods (GET, POST, DELETE).

Before you begin

Work with Integration Delivery (integrations@runpayments.io) to order and provision a UAT device before attempting to authenticate or connect. Please submit all UAT requests to the same address.

Environment

Variable	Value	Notes
`terminal_url`	`https://javelin.runpayments.io`	Base URL for all Terminal API endpoints.
`device_id`	Hardware Serial Number (HSN)	Provided by your Integration Delivery lead. Used as the `{device_id}` path parameter on every terminal endpoint.

Note the base paths

Terminal operations live under /api/terminal/…. The WebSocket token lives at /api/ws-token, and the email-receipt endpoint lives under the Payments API path /api/v1/send_receipt.

Authentication

Once your device is provisioned, use your access token — generated via the self-service credential generator or the key refresh endpoint (/api_keys/refresh) — to authenticate requests and connect with the device.

All Terminal API endpoints require a Bearer token, unless otherwise noted:

Authorization: Bearer <access_token>

Key rotation required

Authentication keys are rotational. The access token expires every hour, and the refresh token expires every 30 days. The recommended path is to create a scheduled job that rotates these keys automatically, so your integration does not fail a request due to an expired token.

Credential	Lifetime	Renewal method
Access token	1 hour	Self-service credential generator, or the key refresh endpoint
Refresh token	30 days	Self-service credential generator (re-authentication required after expiry)
WebSocket token	60 seconds, single use	`POST /api/ws-token` — see Real-time updates (WebSocket)

ISV tokens

If your bearer token is an ISV token acting on behalf of a specific merchant, pass that merchant’s mid as a query parameter. Merchant-level tokens don’t need to pass mid.

If mid can’t be resolved to an authorized account, the request returns 400.

Rate limiting

All Terminal API endpoints share a per-credential rate limit. Exceeding it returns 429 Too Many Requests. This applies uniformly across every terminal endpoint.

Terminal capabilities

GET /api/terminal returns every terminal on the account with a capabilities object describing what that hardware supports. Check these flags before presenting signature capture or printing in your UI.

Flag	What it gates
`signature`	Whether `include_signature` will actually capture a signature.
`printer`	Whether `print-receipt` and `print_receipt` will work. Only Clover Flex and Clover Mini have printers; all other devices are permanently `false`.
`msr`	Magnetic stripe (swipe).
`emv`	Chip (dip).
`nfc`	Contactless (tap).
`pin_pad`	PIN entry.

{
  "device_id": "HSN123456",
  "name": "Front Counter Clover Flex",
  "capabilities": {
    "signature": true,
    "printer": true,
    "msr": true,
    "emv": true,
    "nfc": true,
    "pin_pad": false
  }
}

Capabilities are set when a terminal is created and don’t change, so you can cache them per terminal. Re-fetch the list periodically only to pick up newly added terminals.