> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/docs/guides/payments/card-present/getting-started/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Getting Started

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](mailto: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](/reference/authentication/refresh-api-keys) (`/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)](/docs/guides/payments/card-present/interactions-and-status#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`](/reference/terminal-api/terminals/list-terminals) 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.                                                                                                                                        |

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

> **Tip**
>
> 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.

> Set up your environment, authenticate, and discover what each terminal supports.