> ## 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.

# Pre-authorization

> Reserve funds on a payment instrument without capturing immediately.

A pre-authorization places a hold on the customer's funds without completing the charge. After a successful pre-auth, call [capture](/docs/api-reference/payments/capture) to settle the payment, or [void](/docs/api-reference/payments/void) to release the hold.

<Tip>
  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.
</Tip>

<Note>
  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](/docs/api-reference/idempotency).
</Note>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "transaction_id": "TX8A3F2C",
    "order_id": "OR7B9E1D",
    "merchant_transaction_id": "preauth-20260331-001",
    "accepted": true
  }
  ```

  ```json 400 theme={null}
  {
    "type": "https://terminal.smartretry.com/errors/validation",
    "title": "Bad Request",
    "status": 400,
    "detail": "currency is required",
    "reason_code": "VALIDATION/MISSING_FIELD"
  }
  ```
</ResponseExample>

## Path parameters

<ParamField path="terminal_friendly_id" type="string" required>
  Your terminal identifier. Exactly 6 characters.
</ParamField>

## Request body

The pre-authorization request body is identical to the [sale](/docs/api-reference/payments/sale) request body. See the [sale endpoint](/docs/api-reference/payments/sale) for the full field reference.

## Response

<ResponseField name="transaction_id" type="string" required>
  SmartRetry's unique identifier for this pre-authorization. Exactly 8 characters. Pass this as `transaction_reference_id` in a subsequent [capture](/docs/api-reference/payments/capture) or [void](/docs/api-reference/payments/void) request.
</ResponseField>

<ResponseField name="order_id" type="string">
  SmartRetry's unique identifier for the order. Exactly 8 characters. Pass this as `order_reference_id` in a subsequent capture or void request.
</ResponseField>

<ResponseField name="merchant_transaction_id" type="string">
  The `merchant_transaction_id` you provided in the request, echoed back for confirmation.
</ResponseField>

<ResponseField name="merchant_order_id" type="string">
  The `merchant_order_id` provided in the request order, when present.
</ResponseField>

<ResponseField name="accepted" type="boolean" required>
  `true` if the pre-authorization was accepted for processing. Poll the [status endpoint](/docs/api-reference/payments/status) to confirm the issuer's authorization decision.
</ResponseField>

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