REST API

The SmartRetry REST API accepts JSON over HTTPS. All requests are scoped to a terminal - a 6-character alphanumeric ID that identifies your merchant configuration.

Base URL

https://terminal.smartretry.com

Authentication

Every request must be signed with your API Secret using HMAC-SHA256. Send the signature and a Unix timestamp in headers:

x-timestamp: UNIX_TIMESTAMP
x-signature: SIGNATURE

Keep your API Secret private. Never expose it in client-side code or public repositories.

See Authentication for how to compute the signature, code examples, and test values. The UNIX_TIMESTAMP and SIGNATURE values in the examples below are placeholders.

Request format

Set Content-Type: application/json on all requests and send a JSON body.

Content-Type: application/json

Amount format

Pass amount in major currency units using standard decimal notation.

Amount value	Currency	Represents
`49.99`	`USD`	$49.99
`10.00`	`EUR`	€10.00
`500`	`JPY`	¥500

merchant_transaction_id

merchant_transaction_id is your unique identifier for each transaction. Use it for reconciliation and tracing in your own system.

Idempotency

If you need safe retries for a POST request, send an Idempotency-Key header. Reusing the same key with the same POST body replays the original non-5xx response for 24 hours. Reusing the same key with a different body returns 409 Conflict. Idempotency currently applies only to POST /v1/payments/*. GET and PUT requests ignore the header. See Idempotency for the full contract and response headers.

Token-based payments

SmartRetry generates an 88-character token that represents a stored payment instrument. No submission response returns it directly - retrieve it from order.payment_instrument.token on a transaction status response after the transaction completes. On future charges for the same payer, you can pass this token instead of sending raw card data again. This simplifies repeat billing and reduces PCI scope.

Payer fingerprint

SmartRetry generates a payer_fingerprint - an 88-character identifier that represents a card profile or payer address. You can store this and include it in future requests for the same customer to help SmartRetry recognize repeat payers and apply optimized retry logic more quickly.

Making a sale

All payment endpoints include the terminal_friendly_id as a path parameter at the end of the URL. See Terminals for details.

Example request

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/sale/TERM01 \
  --header 'Content-Type: application/json' \
  --header 'x-timestamp: UNIX_TIMESTAMP' \
  --header 'x-signature: SIGNATURE' \
  --header 'Idempotency-Key: sale-order-a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --data '{
    "merchant_transaction_id": "txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 49.99,
    "currency": "USD",
    "order": {
      "payment_instrument": {
        "card_number": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2027,
        "payment_method": "cards"
      },
      "payer": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com"
      }
    }
  }'

const response = await fetch('https://terminal.smartretry.com/v1/payments/sale/TERM01', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-timestamp': 'UNIX_TIMESTAMP',
    'x-signature': 'SIGNATURE',
    'Idempotency-Key': 'sale-order-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  },
  body: JSON.stringify({
    merchant_transaction_id: 'txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    amount: 49.99,
    currency: 'USD',
    order: {
      payment_instrument: {
        card_number: '4111111111111111',
        expiry_month: 12,
        expiry_year: 2027,
        payment_method: 'cards',
      },
      payer: {
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane.smith@example.com',
      },
    },
  }),
});

const data = await response.json();

import requests

response = requests.post(
    'https://terminal.smartretry.com/v1/payments/sale/TERM01',
    headers={
        'Content-Type': 'application/json',
        'x-timestamp': 'UNIX_TIMESTAMP',
        'x-signature': 'SIGNATURE',
        'Idempotency-Key': 'sale-order-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    },
    json={
        'merchant_transaction_id': 'txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        'amount': 49.99,
        'currency': 'USD',
        'order': {
            'payment_instrument': {
                'card_number': '4111111111111111',
                'expiry_month': 12,
                'expiry_year': 2027,
                'payment_method': 'cards',
            },
            'payer': {
                'first_name': 'Jane',
                'last_name': 'Smith',
                'email': 'jane.smith@example.com',
            },
        },
    },
)

data = response.json()

Example response

{
  "transaction_id": "TX8A3F2C",
  "order_id": "OR7B9E1D",
  "merchant_transaction_id": "txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accepted": true
}

Response format

All responses return JSON. A submission response’s accepted: true means SmartRetry accepted the transaction for processing - it does not mean the issuer approved it. order_id, when returned, and your original merchant_transaction_id are included for reconciliation. Use the status endpoint to get the actual transaction outcome, including APPROVED or DECLINED.

Error format

When a request fails, SmartRetry returns a JSON error object using the RFC 9457 Problem Details format.

{
  "type": "https://terminal.smartretry.com/errors/VALIDATION/INVALID_AMOUNT",
  "title": "Validation Error",
  "status": 400,
  "detail": "The field 'amount' must be a positive number in major currency units.",
  "instance": "/v1/payments/sale/TERM01",
  "reason_code": "VALIDATION/INVALID_AMOUNT",
  "context": {
    "field": "/amount"
  }
}

Field	Type	Description
`type`	string	URI identifying the error type
`title`	string	Short, human-readable summary
`status`	number	HTTP status code
`detail`	string	Detailed explanation of the error
`instance`	string	The request path associated with this occurrence, when available
`reason_code`	string	Machine-readable code for programmatic handling
`context`	object	Optional error-specific data, such as the offending field

Best practices

SmartRetry applies rate limits per API Secret. If you receive a 429 Too Many Requests response, implement exponential backoff before retrying.

Always use a unique merchant_transaction_id per transaction so reconciliation back to your own system stays unambiguous.
Use a new Idempotency-Key for each new POST request, and reuse it only when retrying the exact same request body.
Fetch transaction status after a successful submission to retrieve order.payment_instrument.token - store it to speed up future requests for a returning payer. Submission responses do not include it.
Validate amount and currency on your side before sending - amount must be a positive number in major currency units.
Use the sandbox environment to test your integration before going live.

Get Started

Core Concepts

Integration

Release Notes

Security & Compliance

Base URL

Authentication

Request format

Amount format

merchant_transaction_id

Idempotency

Token-based payments

Payer fingerprint

Making a sale

Example request

Example response

Response format

Error format

Best practices

​Base URL

​Authentication

​Request format

​Amount format

​merchant_transaction_id

​Idempotency

​Token-based payments

​Payer fingerprint

​Making a sale

​Example request

​Example response

​Response format

​Error format

​Best practices

Base URL

Authentication

Request format

Amount format

merchant_transaction_id

Idempotency

Token-based payments

Payer fingerprint

Making a sale

Example request

Example response

Response format

Error format

Best practices