Transaction status

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.

curl --request GET \
  --url https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C \
  --header 'x-api-key: YOUR_API_KEY'

import requests

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

print(response.json())

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);

{
  "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"
    }
  }
}

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_id not found",
  "reason_code": "VALIDATION/TRANSACTION_NOT_FOUND"
}

Path parameters

string

required

Your terminal identifier. Exactly 6 characters.

string

required

The SmartRetry transaction ID to look up. Exactly 8 characters. This is the transaction_id returned by the sale, pre-auth, capture, refund, or void response.

Response

string

required

SmartRetry’s unique identifier for this transaction. Exactly 8 characters.

string

required

The transaction type. One of: sale, preauth, capture, refund, void, recurring_init, recurring, payout.

integer

Transaction amount in major currency units (e.g., 49.99).

string

Three-letter ISO 4217 currency code.

string

Authorization code assigned by the acquirer upon approval.

string

Acquirer Reference Number (ARN). Use this when communicating with your acquiring bank about a specific transaction.

integer

The retry attempt number for this transaction. 1 means the first attempt; higher values indicate SmartRetry has automatically retried the transaction.

string

required

ISO 8601 timestamp of when the transaction was created.

string

required

ISO 8601 timestamp of when the transaction was last updated.

object

required

The current status of the transaction.

Hide properties

string

The high-level status code. See Status values below.

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.

string

required

A short, human-readable name for the current status (e.g., "Approved", "Insufficient Funds").

string

A full human-readable explanation of the status, suitable for logging or internal tooling. Do not display raw reasonCode values to end customers.

string

The system domain responsible for the status outcome. See Status domains below.

object

required

Details about the order associated with this transaction.

Show properties

string

SmartRetry’s unique order identifier. Exactly 8 characters.

string

Your own order reference, as submitted with the original transaction.

string

The downstream payment provider’s order reference.

string

The order description provided at transaction time.

object

Identity details for the payer associated with this order.

Show properties

string

required

SmartRetry’s unique identifier for this payer. Exactly 8 characters.

string

Payer’s first name.

string

Payer’s last name.

string

The local part of the payer’s email address (before the @).

string

The domain part of the payer’s email address (after the @).

string

Payer’s phone number in E.164 format.

object

Tokenized summary of the payment instrument used. Full card numbers are never returned.

Show properties

string

required

SmartRetry’s 88-character payment instrument token. Use this for subsequent tokenized payments.

string

required

Payment method type (e.g., cards, digital_wallets).

string

Name as it appears on the card.

string

Last four digits of the card number.

string

Bank Identification Number (first six or eleven digits of the card). Used to identify the issuing bank and card product.

string

Card expiration date in ISO 8601 format.

object

Enriched card profile data.

Show properties

string

required

Card profile fingerprint. Exactly 88 characters.

object

Issuing bank information.

Show properties

string

required

Name of the card-issuing bank or institution.

object

Card network brand information.

Show properties

string

required

Card network brand name (e.g., Visa, Mastercard, Amex).

string

Card category (e.g., consumer, commercial).

string

required

Card type (e.g., credit, debit).

integer

Length of the card’s primary account number (13–19 digits).

string

Intended card usage (e.g., personal, business).

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

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.

curl --request GET \
  --url https://terminal.smartretry.com/v1/payments/status/ABC123/TX8A3F2C \
  --header 'x-api-key: YOUR_API_KEY'

import requests

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

print(response.json())

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);

{
  "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"
    }
  }
}

{
  "type": "https://terminal.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_id not found",
  "reason_code": "VALIDATION/TRANSACTION_NOT_FOUND"
}

Overview

Payments

Recurring

Future Transactions

Path parameters

Response

Status values

Status domains

​Path parameters

​Response

​Status values

​Status domains

Path parameters

Response

Status values

Status domains