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://api.smartretry.com/v1/payments/status/ABC123/TX8A3F2C \
  --header 'x-api-key: YOUR_API_KEY'

import requests

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

print(response.json())

const response = await fetch(
  "https://api.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": "AUTH.APPROVED",
    "name": "Approved",
    "description": "The transaction was approved by the issuer.",
    "domain": "AUTH"
  },
  "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://api.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_id not found",
  "reason_code": "TRANSACTION_NOT_FOUND"
}

Path parameters

terminal_friendly_id

string

required

Your terminal identifier. Exactly 6 characters.

transaction_id

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

transaction_id

string

required

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

type

string

required

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

amount

number

required

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

currency

string

required

Three-letter ISO 4217 currency code.

authorization_code

string

Authorization code assigned by the acquirer upon approval.

arn

string

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

attempt_number

integer

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

created_at

string

required

ISO 8601 timestamp of when the transaction was created.

updated_at

string

required

ISO 8601 timestamp of when the transaction was last updated.

status

object

required

The current status of the transaction.

Hide properties

status

string

required

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

reasonCode

string

required

A machine-readable code in {domain}.{reason} format (e.g., AUTH.APPROVED, RISK.DECLINED). Always present - use this to build targeted retry logic or surface specific error messages.

name

string

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

description

string

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

domain

string

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

order

object

required

Details about the order associated with this transaction.

Show properties

order_id

string

SmartRetry’s unique order identifier. Exactly 8 characters.

merchant_order_id

string

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

provider_order_id

string

The downstream payment provider’s order reference.

description

string

The order description provided at transaction time.

payer

object

Identity details for the payer associated with this order.

Show properties

friendly_id

string

required

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

first_name

string

Payer’s first name.

last_name

string

Payer’s last name.

email_username

string

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

email_domain

string

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

phone_number

string

Payer’s phone number in E.164 format.

payment_instrument

object

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

Show properties

token

string

required

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

payment_method

string

required

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

card_cardholder_name

string

Name as it appears on the card.

card_card_last_four_digit

string

Last four digits of the card number.

card_bin

string

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

expiration_date

string

Card expiration date in ISO 8601 format.

card_profile

object

Enriched card profile data.

Show properties

fingerprint

string

required

Card profile fingerprint. Exactly 88 characters.

issuer

object

Issuing bank information.

Show properties

name

string

required

Name of the card-issuing bank or institution.

brand

object

Card network brand information.

Show properties

name

string

required

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

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.

Void

Initialize recurring

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

import requests

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

print(response.json())

const response = await fetch(
  "https://api.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": "AUTH.APPROVED",
    "name": "Approved",
    "description": "The transaction was approved by the issuer.",
    "domain": "AUTH"
  },
  "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://api.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_id not found",
  "reason_code": "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