Quick Start

This guide walks you through making your first API request with SmartRetry. You’ll send a sale transaction and handle the response - all in a few minutes.

Get your API Secret and terminal ID

Contact SmartRetry to receive your credentials. You’ll get:

API Secret - used to sign every request. You send the resulting x-timestamp and x-signature headers, never the secret itself
Terminal ID (terminal_friendly_id) - a 6-character identifier for your merchant terminal, used as a path parameter on every payment endpoint

Keep both values secure. Your API Secret signs all requests, and your terminal ID identifies the merchant configuration SmartRetry uses for routing and optimization.

Send your first sale request

Use the POST /v1/payments/sale/{terminal_friendly_id} endpoint to charge a card. Replace ABC123 with your terminal ID. Replace UNIX_TIMESTAMP and SIGNATURE with the values you compute by following Authentication.The amount field uses major currency units. The example below charges $49.99 USD.

curl -X POST https://terminal.smartretry.com/v1/payments/sale/ABC123 \
  -H "x-timestamp: UNIX_TIMESTAMP" \
  -H "x-signature: SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_transaction_id": "order-10042",
    "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"
      }
    }
  }'

{
  "merchant_transaction_id": "order-10042",
  "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"
    }
  }
}

Handle the response

A successful request returns HTTP 200 with a JSON body. accepted: true means SmartRetry accepted the transaction for processing - it does not confirm issuer approval.

Success response

{
  "transaction_id": "TX8A3F2C",
  "order_id": "OR7B9E1D",
  "merchant_transaction_id": "order-10042",
  "accepted": true
}

Field	Description
`transaction_id`	SmartRetry’s unique identifier for this transaction
`order_id`	SmartRetry’s order reference
`merchant_transaction_id`	The ID you provided in the request
`accepted`	`true` if SmartRetry accepted the transaction for processing

Store both transaction_id and order_id in your system. You’ll need them to perform follow-up operations like capture, refund, or void.

Fetch transaction status using the returned transaction_id to find out whether the issuer approved or declined the payment.

Test in the sandbox

Before going live, use the SmartRetry sandbox environment to test your integration end to end - including API calls, response handling, and error scenarios - without processing real payments.The sandbox replicates the full production flow. Contact SmartRetry to request sandbox credentials if you don’t already have them.

Never use real card numbers in the sandbox. Use test card values provided by SmartRetry during onboarding.

Get Started

Core Concepts

Integration

Release Notes

Security & Compliance