API Overview - SmartRetry Documentation

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.

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://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",
    "order": {
      "payment_instrument": {
        "card_number": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2030,
        "payment_method": "cards"
      }
    }
  }'

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",
        "order": {
            "payment_instrument": {
                "card_number": "4111111111111111",
                "expiry_month": 12,
                "expiry_year": 2030,
                "payment_method": "cards",
            },
        },
    },
)

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",
      order: {
        payment_instrument: {
          card_number: "4111111111111111",
          expiry_month: 12,
          expiry_year: 2030,
          payment_method: "cards",
        },
      },
    }),
  }
);

Terminal ID

All documented payment and recurring endpoints include {terminal_friendly_id} as a path parameter. This 6-character string identifies the Terminal used for the operation.

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 and currency

Send amount as a number in major currency units. Send currency as one of the ISO 4217 values shown by the bound operation schema. Amount and currency availability is operation-specific.

Transaction reference

merchant_transaction_id is your own transaction identifier. It is required for Sale and Pre-authorization requests and optional on some other operations. Follow the requiredness shown on the individual endpoint page.

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 for the full behavior, supported methods, response headers, and retry guidance.

Response format

Submission responses include an accepted boolean at the top level. accepted: true means the operation was accepted for asynchronous processing; it does not confirm issuer approval. Retrieve the transaction status using the returned transaction_id to get the current outcome.

{
  "transaction_id": "TX8A3F2C",
  "merchant_transaction_id": "txn_001",
  "accepted": true
}

Errors follow a separate structure - see Errors.

Discovery links

Every response includes a Link header that points back to this documentation, following the RFC 8631 link relations. Use it to find the docs from any response you are holding, including errors.

Relation	Target
`service-doc`	`https://www.smartretry.com/docs` - this documentation site.
`service-desc`	`https://www.smartretry.com/docs/api-reference/openapi.json` - the OpenAPI description of the API.

Read the header with any client:

curl -sI https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C \
  --header 'x-api-key: YOUR_API_KEY' | grep -i '^link:'

The service-desc target is the same OpenAPI description that powers this API reference. Point Postman, an SDK generator, or your own tooling at it directly.

Endpoint groups

Payments

Sale, pre-authorization, capture, their retry request variants, refunds, voids, and transaction status.

Recurring

Initialize and charge recurring series, submit retry attempts through those same endpoints, and retrieve, update, or cancel a series.

Future Transactions

View, update, charge, or cancel scheduled future payments within a recurring plan.

Monitor API uptime and incidents at status.smartretry.com.

​Base URL

​Authentication

​Request format

​Terminal ID

​Amount and currency

​Transaction reference

​Idempotency

​Response format

​Discovery links

​Endpoint groups

Payments

Recurring

Future Transactions

Base URL

Authentication

Request format

Terminal ID

Amount and currency

Transaction reference

Idempotency

Response format

Discovery links

Endpoint groups