Pre-authorization

A pre-authorization places a hold on the customer’s funds without completing the charge. After a successful pre-auth, call capture to settle the payment, or void to release the hold.

Use pre-authorization when the final charge amount may differ from the initial estimate - for example, hotel stays, car rentals, or orders with variable shipping costs.

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/preauth/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: preauth-20260331-001' \
  --data '{
    "merchant_transaction_id": "preauth-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": "Hotel reservation #20260331-001"
    },
    "cvv": "123"
  }'

import requests

response = requests.post(
    "https://terminal.smartretry.com/v1/payments/preauth/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "preauth-20260331-001"
    },
    json={
        "merchant_transaction_id": "preauth-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": "Hotel reservation #20260331-001"
        },
        "cvv": "123"
    }
)

print(response.json())

const response = await fetch(
  "https://terminal.smartretry.com/v1/payments/preauth/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "preauth-20260331-001"
    },
    body: JSON.stringify({
      merchant_transaction_id: "preauth-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: "Hotel reservation #20260331-001"
      },
      cvv: "123"
    })
  }
);

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

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

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "currency is required",
  "reason_code": "VALIDATION/MISSING_FIELD"
}

Path parameters

string

required

Your terminal identifier. Exactly 6 characters.

Request body

The pre-authorization request body is identical to the sale request body. See the sale endpoint for the full field reference.

Response

string

required

SmartRetry’s unique identifier for this pre-authorization. Exactly 8 characters. Pass this as transaction_reference_id in a subsequent capture or void request.

string

SmartRetry’s unique identifier for the order. Exactly 8 characters. Pass this as order_reference_id in a subsequent capture or void request.

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 pre-authorization was accepted for processing. Poll the status endpoint to confirm the issuer’s authorization decision.

Save the transaction_id and order_id from this response. You will need both to capture or void the pre-authorization.

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/preauth/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: preauth-20260331-001' \
  --data '{
    "merchant_transaction_id": "preauth-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": "Hotel reservation #20260331-001"
    },
    "cvv": "123"
  }'

import requests

response = requests.post(
    "https://terminal.smartretry.com/v1/payments/preauth/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "preauth-20260331-001"
    },
    json={
        "merchant_transaction_id": "preauth-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": "Hotel reservation #20260331-001"
        },
        "cvv": "123"
    }
)

print(response.json())

const response = await fetch(
  "https://terminal.smartretry.com/v1/payments/preauth/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "preauth-20260331-001"
    },
    body: JSON.stringify({
      merchant_transaction_id: "preauth-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: "Hotel reservation #20260331-001"
      },
      cvv: "123"
    })
  }
);

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

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

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "currency is required",
  "reason_code": "VALIDATION/MISSING_FIELD"
}

Overview

Payments

Recurring

Future Transactions

Path parameters

Request body

Response

​Path parameters

​Request body

​Response

Path parameters

Request body

Response