Sale

A sale authorizes and captures a payment in one request. Use this endpoint when you want to immediately charge the customer without a separate capture step.

Safe retries for this POST endpoint use the Idempotency-Key header. Reuse the same key only when retrying the exact same request body. See Idempotency.

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/sale/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: sale-order-20260331-001' \
  --data '{
    "merchant_transaction_id": "order-20260331-001",
    "amount": 49.99,
    "currency": "USD",
    "order": {
      "merchant_order_id": "my-order-20260331-001",
      "payment_instrument": {
        "card_number": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2027,
        "payment_method": "cards",
        "card_cardholder_name": "Jane Doe"
      },
      "payer": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com"
      },
      "description": "Order #20260331-001"
    },
    "cvv": "123"
  }'

import requests

response = requests.post(
    "https://terminal.smartretry.com/v1/payments/sale/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "sale-order-20260331-001"
    },
    json={
        "merchant_transaction_id": "order-20260331-001",
        "amount": 49.99,
        "currency": "USD",
        "order": {
            "merchant_order_id": "my-order-20260331-001",
            "payment_instrument": {
                "card_number": "4111111111111111",
                "expiry_month": 12,
                "expiry_year": 2027,
                "payment_method": "cards",
                "card_cardholder_name": "Jane Doe"
            },
            "payer": {
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "jane.doe@example.com"
            },
            "description": "Order #20260331-001"
        },
        "cvv": "123"
    }
)

print(response.json())

const response = await fetch(
  "https://terminal.smartretry.com/v1/payments/sale/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "sale-order-20260331-001"
    },
    body: JSON.stringify({
      merchant_transaction_id: "order-20260331-001",
      amount: 49.99,
      currency: "USD",
      order: {
        merchant_order_id: "my-order-20260331-001",
        payment_instrument: {
          card_number: "4111111111111111",
          expiry_month: 12,
          expiry_year: 2027,
          payment_method: "cards",
          card_cardholder_name: "Jane Doe"
        },
        payer: {
          first_name: "Jane",
          last_name: "Doe",
          email: "jane.doe@example.com"
        },
        description: "Order #20260331-001"
      },
      cvv: "123"
    })
  }
);

const data = await response.json();
console.log(data);

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

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "amount must be at least 0.01",
  "reason_code": "VALIDATION/INVALID_AMOUNT"
}

Path parameters

string

required

Your terminal identifier. Exactly 6 characters.

Request body

string

required

Your unique identifier for this transaction. Use this to correlate SmartRetry transactions with your own records. Maximum 100 characters.

number

required

Amount to charge in major currency units (e.g., 49.99 for $49.99). Minimum 0.01, maximum 999999.99.

string

required

Three-letter ISO 4217 currency code (e.g., USD, EUR, GBP).

object

Order details, including payer identity and payment instrument.

Show properties

string

Your own order reference. Maximum 100 characters.

object

Card or payment method details. Required when not using a top-level token or provider_token.

Show properties

string

required

Primary account number (PAN). Between 13 and 19 digits.

integer

required

Card expiry month. Integer between 1 and 12.

integer

required

Card expiry year. Integer between 2024 and 2099.

string

required

Payment method type. One of: cards, digital_wallets, bnpl, online_banking, rtp, vouchers, cash, direct_debit, cryptocurrencies.

string

Name as it appears on the card. Maximum 100 characters.

object

Show properties

string

Stored card profile fingerprint. Exactly 88 characters.

object

Payer identity details.

Show properties

string

required

Payer’s first name. Maximum 50 characters.

string

required

Payer’s last name. Maximum 50 characters.

string

required

Payer’s email address. Maximum 254 characters.

string

SmartRetry payer ID. Exactly 8 characters. Provide this to link the transaction to an existing payer profile.

string

Payer’s phone number in E.164 format (e.g., +12125551234).

object

Payer’s billing address.

Show properties

string

Primary street address.

string

Apartment, suite, or unit number.

string

City name.

string

Postal or ZIP code.

string

State or province code in ISO 3166-2 format (e.g., US-CA).

string

Two-letter country code in ISO 3166-1 alpha-2 format (e.g., US).

string

Human-readable description of the order. Maximum 500 characters.

string

Stored payment token (88 characters). Use this instead of order.payment_instrument.card_number for repeat customers.

string

Processor-issued payment token. Use exactly one of token, provider_token, or order.payment_instrument.

string

Card verification value (CVV/CVC). Optional but recommended for card-not-present transactions.

The CVV is never stored by SmartRetry and cannot be used in tokenized or retry flows.

string

Human-readable description of the transaction. Maximum 500 characters.

string

SmartRetry order ID (exactly 8 characters). Provide this to associate the transaction with an existing order.

string

IPv4 address of the payer making the request. Used for fraud detection.

object

Device and browser details for 3DS and fraud scoring.

Show properties

string

Device fingerprint. Exactly 88 characters.

string

Operating system name. Maximum 50 characters.

string

Operating system version. Maximum 20 characters.

string

Browser name. Maximum 50 characters.

string

Browser version. Maximum 20 characters.

string

Browser language as a 3-letter ISO 639-3 code.

string

Shipping indicator for 3DS authentication.

string

Indicates how long the shipping address has been associated with the customer. Used for 3DS.

string

Indicates the delivery timeframe for the order. Used for 3DS.

object

Shipping recipient details. Used for 3DS and fraud checks.

Show properties

string

required

Recipient’s first name. Maximum 50 characters.

string

required

Recipient’s last name. Maximum 50 characters.

string

Recipient’s full name. Maximum 150 characters.

string

SmartRetry payer ID of the recipient. Exactly 8 characters.

object

Shipping address.

Show properties

string

Primary street address.

string

City name.

string

Postal or ZIP code.

string

Two-letter country code in ISO 3166-1 alpha-2 format.

Response

string

required

SmartRetry’s unique identifier for this transaction. Exactly 8 characters. Use this in subsequent capture, refund, or void requests.

string

SmartRetry’s unique identifier for the order. Exactly 8 characters.

string

The merchant_transaction_id you provided in the request, echoed back for confirmation.

string

The merchant_order_id provided in the request order, when present.

boolean

required

true if the transaction was accepted for processing. A value of true does not guarantee approval - poll the status endpoint to confirm the final outcome.

accepted: true means SmartRetry has accepted the transaction for processing. To confirm whether the payment was approved by the issuer, fetch the transaction status using the returned transaction_id.

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/sale/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: sale-order-20260331-001' \
  --data '{
    "merchant_transaction_id": "order-20260331-001",
    "amount": 49.99,
    "currency": "USD",
    "order": {
      "merchant_order_id": "my-order-20260331-001",
      "payment_instrument": {
        "card_number": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2027,
        "payment_method": "cards",
        "card_cardholder_name": "Jane Doe"
      },
      "payer": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com"
      },
      "description": "Order #20260331-001"
    },
    "cvv": "123"
  }'

import requests

response = requests.post(
    "https://terminal.smartretry.com/v1/payments/sale/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "sale-order-20260331-001"
    },
    json={
        "merchant_transaction_id": "order-20260331-001",
        "amount": 49.99,
        "currency": "USD",
        "order": {
            "merchant_order_id": "my-order-20260331-001",
            "payment_instrument": {
                "card_number": "4111111111111111",
                "expiry_month": 12,
                "expiry_year": 2027,
                "payment_method": "cards",
                "card_cardholder_name": "Jane Doe"
            },
            "payer": {
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "jane.doe@example.com"
            },
            "description": "Order #20260331-001"
        },
        "cvv": "123"
    }
)

print(response.json())

const response = await fetch(
  "https://terminal.smartretry.com/v1/payments/sale/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "sale-order-20260331-001"
    },
    body: JSON.stringify({
      merchant_transaction_id: "order-20260331-001",
      amount: 49.99,
      currency: "USD",
      order: {
        merchant_order_id: "my-order-20260331-001",
        payment_instrument: {
          card_number: "4111111111111111",
          expiry_month: 12,
          expiry_year: 2027,
          payment_method: "cards",
          card_cardholder_name: "Jane Doe"
        },
        payer: {
          first_name: "Jane",
          last_name: "Doe",
          email: "jane.doe@example.com"
        },
        description: "Order #20260331-001"
      },
      cvv: "123"
    })
  }
);

const data = await response.json();
console.log(data);

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

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "amount must be at least 0.01",
  "reason_code": "VALIDATION/INVALID_AMOUNT"
}

Overview

Payments

Recurring

Future Transactions

Path parameters

Request body

Response

​Path parameters

​Request body

​Response

Path parameters

Request body

Response