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

# Sale

> Charge a payment instrument in a single step.

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.

<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/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"
    }'
  ```

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

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

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

  ```json 400 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## Path parameters

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

## Request body

<ParamField body="merchant_transaction_id" type="string" required>
  Your unique identifier for this transaction. Use this to correlate SmartRetry transactions with your own records. Maximum 100 characters.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to charge in major currency units (e.g., `49.99` for \$49.99). Minimum `0.01`, maximum `999999.99`.
</ParamField>

<ParamField body="currency" type="string" required>
  Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g., `USD`, `EUR`, `GBP`).
</ParamField>

<ParamField body="order" type="object">
  Order details, including payer identity and payment instrument.

  <Expandable title="properties">
    <ParamField body="merchant_order_id" type="string">
      Your own order reference. Maximum 100 characters.
    </ParamField>

    <ParamField body="payment_instrument" type="object">
      Card or payment method details. Required when not using a top-level `token` or `provider_token`.

      <Expandable title="properties">
        <ParamField body="card_number" type="string" required>
          Primary account number (PAN). Between 13 and 19 digits.
        </ParamField>

        <ParamField body="expiry_month" type="integer" required>
          Card expiry month. Integer between `1` and `12`.
        </ParamField>

        <ParamField body="expiry_year" type="integer" required>
          Card expiry year. Integer between `2024` and `2099`.
        </ParamField>

        <ParamField body="payment_method" type="string" required>
          Payment method type. One of: `cards`, `digital_wallets`, `bnpl`, `online_banking`, `rtp`, `vouchers`, `cash`, `direct_debit`, `cryptocurrencies`.
        </ParamField>

        <ParamField body="card_cardholder_name" type="string">
          Name as it appears on the card. Maximum 100 characters.
        </ParamField>

        <ParamField body="card_profile" type="object">
          <Expandable title="properties">
            <ParamField body="fingerprint" type="string">
              Stored card profile fingerprint. Exactly 88 characters.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="payer" type="object">
      Payer identity details.

      <Expandable title="properties">
        <ParamField body="first_name" type="string" required>
          Payer's first name. Maximum 50 characters.
        </ParamField>

        <ParamField body="last_name" type="string" required>
          Payer's last name. Maximum 50 characters.
        </ParamField>

        <ParamField body="email" type="string" required>
          Payer's email address. Maximum 254 characters.
        </ParamField>

        <ParamField body="friendly_id" type="string">
          SmartRetry payer ID. Exactly 8 characters. Provide this to link the transaction to an existing payer profile.
        </ParamField>

        <ParamField body="phone_number" type="string">
          Payer's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format (e.g., `+12125551234`).
        </ParamField>

        <ParamField body="address" type="object">
          Payer's billing address.

          <Expandable title="properties">
            <ParamField body="address_1" type="string">
              Primary street address.
            </ParamField>

            <ParamField body="address_2" type="string">
              Apartment, suite, or unit number.
            </ParamField>

            <ParamField body="city_name" type="string">
              City name.
            </ParamField>

            <ParamField body="postal_code" type="string">
              Postal or ZIP code.
            </ParamField>

            <ParamField body="state_code" type="string">
              State or province code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format (e.g., `US-CA`).
            </ParamField>

            <ParamField body="country_code" type="string">
              Two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (e.g., `US`).
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="description" type="string">
      Human-readable description of the order. Maximum 500 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="token" type="string">
  Stored payment token (88 characters). Use this instead of `order.payment_instrument.card_number` for repeat customers.
</ParamField>

<ParamField body="provider_token" type="string">
  Processor-issued payment token. Use exactly one of `token`, `provider_token`, or `order.payment_instrument`.
</ParamField>

<ParamField body="cvv" type="string">
  Card verification value (CVV/CVC). Optional but recommended for card-not-present transactions.

  <Warning>The CVV is never stored by SmartRetry and cannot be used in tokenized or retry flows.</Warning>
</ParamField>

<ParamField body="description" type="string">
  Human-readable description of the transaction. Maximum 500 characters.
</ParamField>

<ParamField body="order_id" type="string">
  SmartRetry order ID (exactly 8 characters). Provide this to associate the transaction with an existing order.
</ParamField>

<ParamField body="payer_request_ip_address" type="string">
  IPv4 address of the payer making the request. Used for fraud detection.
</ParamField>

<ParamField body="device_profile" type="object">
  Device and browser details for 3DS and fraud scoring.

  <Expandable title="properties">
    <ParamField body="fingerprint" type="string">
      Device fingerprint. Exactly 88 characters.
    </ParamField>

    <ParamField body="os_name" type="string">
      Operating system name. Maximum 50 characters.
    </ParamField>

    <ParamField body="os_version" type="string">
      Operating system version. Maximum 20 characters.
    </ParamField>

    <ParamField body="browser_name" type="string">
      Browser name. Maximum 50 characters.
    </ParamField>

    <ParamField body="browser_version" type="string">
      Browser version. Maximum 20 characters.
    </ParamField>

    <ParamField body="browser_language" type="string">
      Browser language as a 3-letter ISO 639-3 code.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ship_indicator" type="string">
  Shipping indicator for 3DS authentication.
</ParamField>

<ParamField body="delivery_address_usage_indicator" type="string">
  Indicates how long the shipping address has been associated with the customer. Used for 3DS.
</ParamField>

<ParamField body="delivery_timeframe" type="string">
  Indicates the delivery timeframe for the order. Used for 3DS.
</ParamField>

<ParamField body="shipping_recipient" type="object">
  Shipping recipient details. Used for 3DS and fraud checks.

  <Expandable title="properties">
    <ParamField body="first_name" type="string" required>
      Recipient's first name. Maximum 50 characters.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Recipient's last name. Maximum 50 characters.
    </ParamField>

    <ParamField body="full_name" type="string">
      Recipient's full name. Maximum 150 characters.
    </ParamField>

    <ParamField body="friendly_id" type="string">
      SmartRetry payer ID of the recipient. Exactly 8 characters.
    </ParamField>

    <ParamField body="address" type="object">
      Shipping address.

      <Expandable title="properties">
        <ParamField body="address_1" type="string">
          Primary street address.
        </ParamField>

        <ParamField body="city_name" type="string">
          City name.
        </ParamField>

        <ParamField body="postal_code" type="string">
          Postal or ZIP code.
        </ParamField>

        <ParamField body="country_code" type="string">
          Two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="transaction_id" type="string" required>
  SmartRetry's unique identifier for this transaction. Exactly 8 characters. Use this in subsequent [capture](/docs/api-reference/payments/capture), [refund](/docs/api-reference/payments/refund), or [void](/docs/api-reference/payments/void) requests.
</ResponseField>

<ResponseField name="order_id" type="string">
  SmartRetry's unique identifier for the order. Exactly 8 characters.
</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 transaction was accepted for processing. A value of `true` does not guarantee approval - poll the [status endpoint](/docs/api-reference/payments/status) to confirm the final outcome.
</ResponseField>

<Note>
  `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`.
</Note>