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

# Transaction status

> Retrieve the current status and details of any transaction.

Fetch the full details and current status of any transaction by its `transaction_id`. Use this endpoint to confirm whether a payment was approved, to monitor retry attempts, or to display order history to your customers.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C \
    --header 'x-api-key: YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C",
      headers={"x-api-key": "YOUR_API_KEY"}
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C",
    {
      method: "GET",
      headers: {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "transaction_id": "TX8A3F2C",
    "type": "sale",
    "amount": 49.99,
    "currency": "USD",
    "authorization_code": "AUTH042",
    "arn": "74491803522700123456789",
    "attempt_number": 1,
    "created_at": "2026-03-31T14:22:10Z",
    "updated_at": "2026-03-31T14:22:13Z",
    "status": {
      "status": "APPROVED",
      "reasonCode": "SYSTEM.SUCCESSFUL",
      "name": "Successful",
      "description": "The transaction completed successfully.",
      "domain": "SYSTEM"
    },
    "order": {
      "order_id": "OR7B9E1D",
      "merchant_order_id": "order-20260331-001",
      "provider_order_id": "prov-88271",
      "description": "Order #20260331-001",
      "payer": {
        "friendly_id": "PY4A8C2D",
        "first_name": "Jane",
        "last_name": "Doe",
        "email_username": "jane.doe",
        "email_domain": "example.com"
      },
      "payment_instrument": {
        "token": "tok_4111...",
        "payment_method": "cards",
        "card_cardholder_name": "Jane Doe",
        "card_card_last_four_digit": "1111",
        "card_bin": "411111",
        "expiration_date": "2027-12-31T00:00:00Z"
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "type": "https://terminal.smartretry.com/errors/validation",
    "title": "Bad Request",
    "status": 400,
    "detail": "transaction_id not found",
    "reason_code": "VALIDATION/TRANSACTION_NOT_FOUND"
  }
  ```
</ResponseExample>

## Path parameters

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

<ParamField path="transaction_id" type="string" required>
  The SmartRetry transaction ID to look up. Exactly 8 characters. This is the `transaction_id` returned by the [sale](/docs/api-reference/payments/sale), [pre-auth](/docs/api-reference/payments/preauth), [capture](/docs/api-reference/payments/capture), [refund](/docs/api-reference/payments/refund), or [void](/docs/api-reference/payments/void) response.
</ParamField>

## Response

<ResponseField name="transaction_id" type="string" required>
  SmartRetry's unique identifier for this transaction. Exactly 8 characters.
</ResponseField>

<ResponseField name="type" type="string" required>
  The transaction type. One of: `sale`, `preauth`, `capture`, `refund`, `void`, `recurring_init`, `recurring`, `payout`.
</ResponseField>

<ResponseField name="amount" type="integer">
  Transaction amount in major currency units (e.g., `49.99`).
</ResponseField>

<ResponseField name="currency" type="string">
  Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
</ResponseField>

<ResponseField name="authorization_code" type="string">
  Authorization code assigned by the acquirer upon approval.
</ResponseField>

<ResponseField name="arn" type="string">
  Acquirer Reference Number (ARN). Use this when communicating with your acquiring bank about a specific transaction.
</ResponseField>

<ResponseField name="attempt_number" type="integer">
  The retry attempt number for this transaction. `1` means the first attempt; higher values indicate SmartRetry has automatically retried the transaction.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the transaction was created.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp of when the transaction was last updated.
</ResponseField>

<ResponseField name="status" type="object" required>
  The current status of the transaction.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="status" type="string">
      The high-level status code. See [Status values](#status-values) below.
    </ResponseField>

    <ResponseField name="reasonCode" type="string" required>
      A machine-readable code in `{domain}.{reason}` format (e.g., `SYSTEM.SUCCESSFUL`, `RISK.DECLINED`). Always present - use this to build targeted retry logic or surface specific error messages.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      A short, human-readable name for the current status (e.g., `"Approved"`, `"Insufficient Funds"`).
    </ResponseField>

    <ResponseField name="description" type="string">
      A full human-readable explanation of the status, suitable for logging or internal tooling. Do not display raw `reasonCode` values to end customers.
    </ResponseField>

    <ResponseField name="domain" type="string">
      The system domain responsible for the status outcome. See [Status domains](#status-domains) below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order" type="object" required>
  Details about the order associated with this transaction.

  <Expandable title="properties">
    <ResponseField name="order_id" type="string">
      SmartRetry's unique order identifier. Exactly 8 characters.
    </ResponseField>

    <ResponseField name="merchant_order_id" type="string">
      Your own order reference, as submitted with the original transaction.
    </ResponseField>

    <ResponseField name="provider_order_id" type="string">
      The downstream payment provider's order reference.
    </ResponseField>

    <ResponseField name="description" type="string">
      The order description provided at transaction time.
    </ResponseField>

    <ResponseField name="payer" type="object">
      Identity details for the payer associated with this order.

      <Expandable title="properties">
        <ResponseField name="friendly_id" type="string" required>
          SmartRetry's unique identifier for this payer. Exactly 8 characters.
        </ResponseField>

        <ResponseField name="first_name" type="string">
          Payer's first name.
        </ResponseField>

        <ResponseField name="last_name" type="string">
          Payer's last name.
        </ResponseField>

        <ResponseField name="email_username" type="string">
          The local part of the payer's email address (before the `@`).
        </ResponseField>

        <ResponseField name="email_domain" type="string">
          The domain part of the payer's email address (after the `@`).
        </ResponseField>

        <ResponseField name="phone_number" type="string">
          Payer's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payment_instrument" type="object">
      Tokenized summary of the payment instrument used. Full card numbers are never returned.

      <Expandable title="properties">
        <ResponseField name="token" type="string" required>
          SmartRetry's 88-character payment instrument token. Use this for subsequent tokenized payments.
        </ResponseField>

        <ResponseField name="payment_method" type="string" required>
          Payment method type (e.g., `cards`, `digital_wallets`).
        </ResponseField>

        <ResponseField name="card_cardholder_name" type="string">
          Name as it appears on the card.
        </ResponseField>

        <ResponseField name="card_card_last_four_digit" type="string">
          Last four digits of the card number.
        </ResponseField>

        <ResponseField name="card_bin" type="string">
          Bank Identification Number (first six or eleven digits of the card). Used to identify the issuing bank and card product.
        </ResponseField>

        <ResponseField name="expiration_date" type="string">
          Card expiration date in ISO 8601 format.
        </ResponseField>

        <ResponseField name="card_profile" type="object">
          Enriched card profile data.

          <Expandable title="properties">
            <ResponseField name="fingerprint" type="string" required>
              Card profile fingerprint. Exactly 88 characters.
            </ResponseField>

            <ResponseField name="issuer" type="object">
              Issuing bank information.

              <Expandable title="properties">
                <ResponseField name="name" type="string" required>
                  Name of the card-issuing bank or institution.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="brand" type="object">
              Card network brand information.

              <Expandable title="properties">
                <ResponseField name="name" type="string" required>
                  Card network brand name (e.g., `Visa`, `Mastercard`, `Amex`).
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="category" type="string">
              Card category (e.g., `consumer`, `commercial`).
            </ResponseField>

            <ResponseField name="cardType" type="string" required>
              Card type (e.g., `credit`, `debit`).
            </ResponseField>

            <ResponseField name="panLength" type="integer">
              Length of the card's primary account number (13–19 digits).
            </ResponseField>

            <ResponseField name="cardUsage" type="string">
              Intended card usage (e.g., `personal`, `business`).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Status values

The `status.status` field indicates the current state of the transaction:

| Value        | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `APPROVED`   | The transaction was approved by the issuer and funds have been reserved or captured. |
| `PROCESSING` | The transaction is still being processed. Poll again shortly.                        |
| `DECLINED`   | The transaction was declined. Check `status.reasonCode` for the specific reason.     |
| `ERROR`      | An unexpected error occurred during processing.                                      |
| `CANCELLED`  | The transaction was cancelled (e.g., by a void).                                     |
| `UNKNOWN`    | The status could not be determined. Contact support if this persists.                |

## Status domains

The `status.domain` field identifies which system was responsible for the status outcome:

| Domain           | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `SYSTEM`         | An internal SmartRetry system error.                                              |
| `VALIDATION`     | The request failed validation (e.g., missing or malformed fields).                |
| `RISK`           | The transaction was blocked or flagged by a risk or fraud rule.                   |
| `ROUTING`        | The transaction could not be routed to an available processor.                    |
| `AUTH`           | The issuer approved or declined the authorization.                                |
| `PROCESSOR`      | The acquiring processor returned a result.                                        |
| `PAYMENT_METHOD` | The issue is specific to the payment method (e.g., unsupported card type).        |
| `PAYER_ACCOUNT`  | The issue is related to the payer's account (e.g., card expired, account closed). |

<Tip>
  Use `status.domain` alongside `status.reasonCode` to build targeted retry logic or to surface the right error message to your customers - for example, prompting a payer to update their card details when `domain` is `PAYER_ACCOUNT`.
</Tip>