> ## Documentation Index
> Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Overview
> Overview of the SmartRetry Terminal API - endpoints, authentication, and request format.
The SmartRetry Terminal API is a REST API that lets you initiate payments, manage recurring billing, and monitor transaction health. All requests are scoped to a merchant terminal and authenticated with an API key.
## Base URL
```
https://terminal.smartretry.com
```
All endpoints are versioned under `/v1/`.
## Authentication
Every request must include your API key in the `x-api-key` header.
```bash theme={null}
x-api-key: YOUR_API_KEY
```
Keep your API key secret. Never expose it in client-side code, browser requests, or public repositories. If a key is compromised, contact support to rotate it immediately.
To obtain an API key, contact [SmartRetry](https://www.smartretry.com/contact). Each key is scoped to one or more terminals - requests to terminals your key cannot access return `403 Forbidden`.
## Request format
Send all request bodies as JSON with the `Content-Type: application/json` header.
```bash theme={null}
Content-Type: application/json
```
```bash cURL theme={null}
curl --request POST \
--url https://terminal.smartretry.com/v1/payments/sale/ABC123 \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Idempotency-Key: sale-order-001' \
--data '{
"merchant_transaction_id": "txn_001",
"amount": 19.99,
"currency": "USD"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://terminal.smartretry.com/v1/payments/sale/ABC123",
headers={
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
"Idempotency-Key": "sale-order-001",
},
json={
"merchant_transaction_id": "txn_001",
"amount": 19.99,
"currency": "USD",
},
)
```
```javascript Node.js theme={null}
const response = await fetch(
"https://terminal.smartretry.com/v1/payments/sale/ABC123",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
"Idempotency-Key": "sale-order-001",
},
body: JSON.stringify({
merchant_transaction_id: "txn_001",
amount: 19.99,
currency: "USD",
}),
}
);
```
## Terminal ID
All payment and recurring endpoints include `{terminal_friendly_id}` as a path parameter. This 6-character alphanumeric string identifies your merchant terminal and scopes every operation to your account configuration.
```
POST /v1/payments/sale/{terminal_friendly_id}
^^^^^^^^^^^^^^^^
e.g., ABC123
```
You receive your `terminal_friendly_id` when SmartRetry provisions your account. A single API key may have access to multiple terminals.
## Amount format
The `amount` field uses **major currency units** in standard decimal notation (e.g., `10.00` for \$10.00). Always send a number - never an integer representing cents.
| Currency | Decimal places | Example amount value | Represents |
| -------- | -------------- | -------------------- | ---------- |
| USD | 2 | `10.00` | \$10.00 |
| GBP | 2 | `10.00` | £10.00 |
| EUR | 2 | `25.50` | €25.50 |
| JPY | 0 | `1000` | ¥1,000 |
| KWD | 3 | `1.000` | KD 1.000 |
Zero-decimal currencies (e.g., JPY, KRW, UGX) have no fractional units - send the whole amount as a number with no decimals (e.g., `1000` = ¥1,000). Three-decimal currencies like KWD use three decimal places (e.g., `1.000` = KD 1.000).
Supported currencies: USD, EUR, GBP, JPY, KWD, CNY, AUD, CAD, CHF, SEK, NOK, DKK, RUB, ILS, INR, BRL, MXN, ZAR, SGD, HKD, NZD, AED, SAR, TRY, PLN, CZK, HUF, THB, PHP, MYR, BGN, RON, IDR, KRW, COP, UAH, VND, QAR, BHD, EGP, MAD, KES, UGX, NGN, OMR, ARS, CLP, JOD, PYG, RWF.
## Transaction reference
`merchant_transaction_id` is your own unique identifier for each transaction. Include it on every request.
* **Reconciliation** - use this ID to match SmartRetry transactions back to orders in your system.
* **Correlation** - log it in your application so you can trace a SmartRetry transaction back to the originating cart, invoice, or subscription event.
Generate a UUID or a stable, order-scoped ID for each transaction so your internal records remain easy to reconcile.
## Idempotency
Use the `Idempotency-Key` header on `POST /v1/payments/*` requests when you need safe retries. If you resend the same POST request with the same key and the same body, SmartRetry replays the original non-`5xx` response for 24 hours instead of creating a second operation.
If you reuse the same key with a different request body, SmartRetry returns `409 Conflict` with reason code `ROUTING/IDEMPOTENCY_CONFLICT`.
See [Idempotency](/docs/api-reference/idempotency) for the full behavior, supported methods, response headers, and retry guidance.
## Response format
Successful payment responses include an `accepted` boolean at the top level. Use this field - not only the HTTP status code - to determine whether the transaction was approved.
```json theme={null}
{
"transaction_id": "TX8A3F2C",
"order_id": "OR7B9E1D",
"merchant_transaction_id": "txn_001",
"accepted": true
}
```
A `200 OK` response with `"accepted": false` means the request was valid but the transaction was declined. Handle both cases in your integration.
Errors follow a separate structure - see [Errors](/docs/api-reference/errors).
## Endpoint groups
One-time charges, pre-authorizations, captures, refunds, voids, and transaction status lookups.
Initialize and manage subscription billing - init, charge, update, cancel, and status.
View, update, charge, or cancel scheduled future payments within a recurring plan.
Monitor API uptime and incidents at [status.smartretry.com](https://status.smartretry.com).