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.

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://api.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"
  }'

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

​
Path parameters

​
terminal_friendly_id
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

​
transaction_id
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.
​
order_id
string
required
SmartRetry’s unique identifier for the order. Exactly 8 characters. Pass this as order_reference_id in a subsequent capture or void request.
​
merchant_transaction_id
string
required
The merchant_transaction_id you provided in the request, echoed back for confirmation.
​
accepted
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.