Transaction status

Lifecycle

PROCESSING is the only non-final status. APPROVED, DECLINED, CANCELLED, ERROR, and UNKNOWN are all final — none of them transition to another status on their own.

Treat UNKNOWN as unresolved, not as a failure. Query transaction status again or contact support before taking any action based on it.

How to act on each status

APPROVED

The payment succeeded. For a sale, funds are captured. For a pre-authorization, funds are held — call capture to settle them, or void to release the hold.

PROCESSING

The transaction is still in flight. Poll transaction status or wait for a webhook event rather than resubmitting the request.

DECLINED

The issuer, processor, or a SmartRetry risk/validation rule refused the transaction. Read reasonCode and domain to determine whether the decline is retryable — see Decline codes.

ERROR

A technical failure prevented the transaction from completing, distinct from an issuer decline. These are typically safe to retry with a new Idempotency-Key.

CANCELLED

The transaction was cancelled — for example, by a void — before it reached a final outcome. No funds moved.

UNKNOWN

The outcome could not be determined, for example after a timeout with no response from the processor. Do not assume success or failure.

The status object

GET /v1/payments/status/{terminal_friendly_id}/{transaction_id} returns status as a structured object, not a plain string:

{
  "status": "DECLINED",
  "reasonCode": "PAYER_ACCOUNT.STOLEN_INSTRUMENT",
  "domain": "PAYER_ACCOUNT",
  "reason": "STOLEN_INSTRUMENT",
  "name": "Stolen Card",
  "description": "The payment card has been reported as stolen by the cardholder or the issuing bank."
}

string

The top-level outcome. See the values above.

string

required

A dot-separated code identifying the reason for the status. See Reason code formats below for how this differs from the reason_code on error responses.

string

The functional area responsible for the status. See Status reason codes for the full breakdown by domain.

string

The reason segment of the code, without the domain prefix.

string

required

A human-readable name for the specific reason.

string

A plain-language description of what this reason means.

object

Present for validation-related reasons. Identifies the offending field.

Show properties

string

required

A JSON pointer to the invalid field in the original request body.

Reason code formats

SmartRetry uses the same underlying catalog in two different string formats, depending on where it appears.

status.reasonCode
error reason_code

Dot-separated, and truncated to at most two segments: DOMAIN.REASON. The full three-segment detail is still reflected in name and description.

PAYER_ACCOUNT/STOLEN_INSTRUMENT/STOLEN_CARD   (underlying code)
  → reasonCode: "PAYER_ACCOUNT.STOLEN_INSTRUMENT"
  → domain:     "PAYER_ACCOUNT"
  → reason:     "STOLEN_INSTRUMENT"

Slash-separated, and never truncated: DOMAIN/REASON or DOMAIN/REASON/DETAIL. This is the value returned as reason_code on every error response, and it matches an entry in the full Status reason codes catalog exactly.

Status domains

The domain field tells you which part of the payment chain produced a status — SmartRetry’s own validation, risk rules, routing, the card network, the processor, the payment method, or the payer’s account. Domain names and descriptions are documented alongside the full code catalog.

Status reason codes

All 300+ reason codes, grouped and described by domain.