Payment intent statuses
| Status | Type | Meaning |
|---|---|---|
pending | Transitory | Created and not yet resolved; one or more attempts may be in progress. |
completed | Final | Paid successfully. |
failed | Final | All attempts failed. |
expired | Final | The intent was not completed before it expired. |
partially_refunded | Final | Completed, then partially refunded. |
refunded | Final | Completed, then fully refunded. |
Payment attempt statuses
| Status | Type | Meaning |
|---|---|---|
processing | Transitory | Sent to the gateway, awaiting an outcome. |
action_required | Transitory | The customer must act (OTP, redirect, QR, approval). Read next_action. |
completed | Final | Captured successfully. |
failed | Final | Declined. Read the failure object. |
cancelled | Final | Abandoned. |
How the two relate
- A completed attempt completes the intent.
- When all attempts fail (after any automatic failover), the intent becomes failed.
- A completed refund moves the intent to
partially_refundedorrefunded.
Only
pending (intent) and processing / action_required (attempt) are non-terminal.
Treat every other status as final and act on it. The authoritative status always comes from
the API — see Verify a payment.Failure codes
When an attempt reachesfailed, the failure.code field contains a structured object:
| Field | Type | Description |
|---|---|---|
value | string | Machine-readable code, e.g. INSUFFICIENT_BALANCE. |
category | string | High-level category (see below). |
message | string|null | Human-readable merchant-facing description. |
Failure categories
| Category | Meaning |
|---|---|
GATEWAY_ERROR | Provider-side outage or rejection. Failover may succeed. |
CUSTOMER_ERROR | Customer-fixable: wrong card, insufficient balance, cancelled. |
TELCO_ERROR | Mobile network operator failure. |
MERCHANT_CONFIG_ERROR | Misconfiguration: routing, gateway credentials. ROUTING_NOT_CONFIGURED falls here. |
PLATFORM_ERROR | Platform fault — contact support if persistent. |
SECURITY_ERROR | Integrity or fraud block. |