Skip to main content

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.

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://api.smartretry.com
All endpoints are versioned under /v1/.

​
Authentication

Every request must include your API key in the x-api-key header. 
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. 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. 
Content-Type: application/json

curl --request POST \
  --url https://api.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"
  }'

​
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.
CurrencyDecimal placesExample amount valueRepresents
USD210.00$10.00
GBP210.00£10.00
EUR225.50€25.50
JPY01000¥1,000
KWD31.000KD 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 IDEMPOTENCY_CONFLICT. See 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. 
{
  "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.

​
Health endpoints

Use the health endpoints to monitor API availability and readiness in your infrastructure checks or dashboards.
EndpointDescription
GET /health/General health check. Returns 200 when the API is operational.
GET /health/readyReadiness check. Returns 200 when the API is ready to serve traffic.
GET /health/liveLiveness check. Returns 200 when the API process is alive.
These endpoints do not require authentication.

​
Endpoint groups

Payments

One-time charges, pre-authorizations, captures, refunds, voids, and transaction status lookups.

Recurring

Initialize and manage subscription billing - init, charge, update, cancel, and status.

Future Transactions

View, update, charge, or cancel scheduled future payments within a recurring plan.
Monitor API uptime and incidents at status.smartretry.com.