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 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://api.smartretry.com

​
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 or public repositories.

​
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 valueCurrencyRepresents
49.99USD$49.99
10.00EUR€10.00
500JPY¥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

When SmartRetry processes a transaction, it can return a token - an 88-character stored payment token that represents the card. On future charges for the same customer, 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://api.smartretry.com/v1/payments/sale/TERM01 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --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",
    "payment_instrument": {
      "card_number": "4111111111111111",
      "expiry_month": 12,
      "expiry_year": 2027,
      "payment_method": "cards"
    },
    "cvv": "123",
    "payer": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com"
    }
  }'

​
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. Successful payment responses include an accepted boolean, the transaction_id and order_id assigned by SmartRetry, and your original merchant_transaction_id for reconciliation. A 200 OK with "accepted": false means the transaction was declined - not an error. Use the status endpoint to get the full transaction outcome.

​
Error format

When a request fails, SmartRetry returns a JSON error object using the RFC 7807 Problem Details format. 
{
  "type": "https://api.smartretry.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The field 'amount' must be a positive number in major currency units.",
  "reason_code": "INVALID_AMOUNT"
}
FieldTypeDescription
typestringURI identifying the error type
titlestringShort, human-readable summary
statusnumberHTTP status code
detailstringDetailed explanation of the error
reason_codestringMachine-readable code for programmatic handling

​
Best practices

SmartRetry applies rate limits per API key. 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.
  • Store the token and payer_fingerprint from successful responses to speed up future requests for returning customers.
  • 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.