> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment statuses
> Complete reference of every top level payment status and every sub status. Verified against the production codebase and canonical Yuno spec.
Yuno uses a two level model for every payment.
* **`status`** is the top level value. Branch on this in your business logic.
* **`sub_status`** is an optional refinement that adds detail. Useful for support, debugging, and granular UI states.
There are **14 top level statuses** and a defined set of sub statuses per top level. The list below is the canonical taxonomy as enforced by `payment-rx-orc` and surfaced through `POST /v1/payments`.
`AUTHORIZED` is **not a top level status**. It is a **sub status of `PENDING`**. Auth only flows return `status: PENDING, sub_status: AUTHORIZED` until you call [Capture](/api-reference/payments/capture). The same is true for `PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`, and `CAPTURED`, which are sub statuses of `SUCCEEDED`, not separate top level values.
## Top level statuses
| `status` | Meaning | Terminal |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `CREATED` | Initial state at the time of creating a payment. | No |
| `READY_TO_PAY` | Awaiting customer action (for example a hosted redirect or QR code scan). | No |
| `PENDING` | Multi step processing, customer action, async settlement, or 3DS challenge in progress. The `sub_status` carries the specific reason. | No |
| `VERIFIED` | Zero amount card authorization succeeded (used for card verification flows). | Yes |
| `SUCCEEDED` | Payment completed. The `sub_status` carries detail (`APPROVED`, `CAPTURED`, `PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`, `PARTIALLY_CHARGEBACKED`, etc.). | Yes |
| `DECLINED` | Provider or issuer declined the transaction. | Yes |
| `REJECTED` | Yuno rejected the request for validation or risk reasons (failed before reaching a provider). | Yes |
| `EXPIRED` | Payment or authorization window expired before completion. Common for unpaid Boleto, OXXO, Pix QR codes that timed out. | Yes |
| `CANCELED` | Cancellation succeeded. **Single L spelling, matches the API.** | Yes |
| `REFUNDED` | Captured funds were returned to the customer. | Yes |
| `IN_DISPUTE` | Chargeback or inquiry received from the issuer. Awaiting evidence or response. | No |
| `CHARGEBACK` | Predispute deflected. Funds lost. | Yes |
| `ERROR` | System error such as timeout or upstream failure. The `sub_status` indicates the failure mode. | No |
| `FRAUD` | Transaction verified by the fraud provider during stand alone fraud verification. | Yes |
Non terminal statuses can transition. Terminal statuses do not. Async methods typically surface `PENDING` first and settle to a terminal status through a webhook.
## Sub statuses by top level status
Each top level status has a defined set of allowed sub statuses. Use them for UI detail and support workflows. The `code` is the canonical Yuno value you will see on the payment object and on webhook payloads.
### `CREATED`
| `sub_status` | Meaning |
| ------------ | -------------------------------------------------------------------------- |
| `CREATED` | The payment record has been created but no further processing has started. |
### `READY_TO_PAY`
| `sub_status` | Meaning |
| ------------ | ---------------------------------------------------------------------------- |
| `CREATED` | The payment is ready for customer action (redirect URL or QR code returned). |
### `PENDING`
| `sub_status` | Meaning |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `AUTHORIZED` | Funds reserved on a card. Auth only flow waiting for capture. |
| `IN_PROCESS` | Provider is actively processing. |
| `WAITING_ADDITIONAL_STEP` | Customer must complete a follow up (3DS challenge, redirect, OTP). Inspect `require_action_type` and `require_action.redirect_url`. |
| `PENDING_PROVIDER_CONFIRMATION` | Provider acknowledged the request and is finalizing async settlement. |
| `PENDING_FRAUD_REVIEW` | Fraud screening is in progress. |
| `PENDING_OTP_COMPLETION` | Awaiting OTP from the cardholder. |
### `VERIFIED`
| `sub_status` | Meaning |
| ------------ | ----------------------------------- |
| `VERIFIED` | Zero amount verification succeeded. |
### `SUCCEEDED`
| `sub_status` | Meaning |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| `APPROVED` | Provider approved the transaction (auto capture). |
| `CAPTURED` | Authorized funds were captured. |
| `PARTIALLY_APPROVED` | Provider approved a partial amount of the requested authorization. |
| `PARTIALLY_CAPTURED` | A partial capture was settled against the authorization. |
| `PARTIALLY_REFUNDED` | At least one partial refund was issued. The remainder of the captured amount is still held. |
| `PARTIALLY_CHARGEBACKED` | A partial chargeback was applied. |
| `FRAUD_DECLINED` | Initially succeeded then later flagged by the fraud screening pipeline. |
| `REFUND_RETRY_IN_PROCESS` | A refund retry is in progress against this succeeded payment. |
| `CAPTURE_RETRY_IN_PROCESS` | A capture retry is in progress. |
| `CAPTURE_RETRY_PROCESS_FAILED` | The capture retry failed permanently. |
### `DECLINED`
| `sub_status` | Meaning |
| ---------------- | --------------------------------------------------------------------------- |
| `DECLINED` | Provider or issuer declined. |
| `FRAUD_DECLINED` | Fraud screening declined the transaction before or after the provider call. |
### `REJECTED`
| `sub_status` | Meaning |
| ------------ | ------------------------------------------------------------------------- |
| `REJECTED` | Yuno rejected the request for validation, configuration, or risk reasons. |
### `EXPIRED`
| `sub_status` | Meaning |
| ------------ | --------------------------------------------------- |
| `EXPIRED` | The payment window or authorization window expired. |
### `CANCELED`
| `sub_status` | Meaning |
| ------------------------------- | ---------------------------------------------------------- |
| `CANCELED` | The cancellation completed. |
| `PENDING_PROVIDER_CONFIRMATION` | Cancellation submitted, awaiting provider acknowledgement. |
### `REFUNDED`
| `sub_status` | Meaning |
| ------------------------------- | ---------------------------------------------------- |
| `REFUNDED` | The refund completed. |
| `PENDING_PROVIDER_CONFIRMATION` | Refund submitted, awaiting provider acknowledgement. |
### `IN_DISPUTE`
| `sub_status` | Meaning |
| ---------------- | ----------------------------------------------------------- |
| `RECEIVED` | Chargeback or inquiry received, evidence not yet submitted. |
| `PENDING_REVIEW` | Provider or scheme is reviewing submitted evidence. |
### `CHARGEBACK`
| `sub_status` | Meaning |
| ------------ | ---------------------------------------- |
| `LOST` | The chargeback was lost. Funds are gone. |
### `ERROR`
| `sub_status` | Meaning |
| --------------------- | ------------------------------------------------------- |
| `ERROR` | Unspecified system or provider error. |
| `TIMEOUT` | The provider did not respond inside the timeout window. |
| `PENDING_REVERSE` | A reverse operation is pending after a timeout. |
| `REVERSED_BY_TIMEOUT` | The transaction was reversed because of a timeout. |
### `FRAUD`
| `sub_status` | Meaning |
| ---------------- | ----------------------------------------------------------------------------------- |
| `FRAUD_VERIFIED` | The fraud provider completed verification (used in stand alone fraud verification). |
## Status state machine
The full transition diagram for every top level status. Click to open at full size.
## Common flows by payment method
### Card, auto capture, no 3DS challenge
```
CREATED -> PENDING (IN_PROCESS) -> SUCCEEDED (APPROVED)
```
The provider authorizes and captures in a single step. The synchronous response is final.
### Card, auto capture, with 3DS challenge
```
CREATED -> PENDING (WAITING_ADDITIONAL_STEP) -> SUCCEEDED (APPROVED)
or DECLINED
```
The synchronous response carries the redirect or challenge payload. The final status arrives via webhook after the customer completes the challenge.
### Card, authorize then capture
```
CREATED -> PENDING (AUTHORIZED) -> SUCCEEDED (CAPTURED)
or CANCELED
or EXPIRED
```
Auth holds funds. You either call Capture, Cancel, or let the issuer's hold window expire.
### Pix, Boleto, OXXO, PSE, SPEI, SEPA, ACH and other async methods
```
CREATED -> PENDING (PENDING_PROVIDER_CONFIRMATION) -> SUCCEEDED (APPROVED)
or EXPIRED
```
The synchronous response returns `PENDING` with the QR code, voucher reference, or redirect URL. The final status arrives via webhook when the customer completes the off platform action (or the window expires).
### Refund
```
SUCCEEDED -> REFUNDED (full refund)
SUCCEEDED -> SUCCEEDED (PARTIALLY_REFUNDED) (partial refund, more remaining)
```
Partial refunds keep the payment in `SUCCEEDED` with a sub status. A refund that consumes the full captured amount transitions to `REFUNDED`.
### Dispute
```
SUCCEEDED -> IN_DISPUTE (RECEIVED) -> IN_DISPUTE (PENDING_REVIEW) -> SUCCEEDED (won)
or CHARGEBACK (LOST) (lost)
```
## How statuses reach your server
1. **Synchronous response** from `POST /v1/payments` carries the initial status. For sync methods this is final. For async methods it is `PENDING`.
2. **Webhook events** carry every subsequent transition. Webhooks are the source of truth.
3. **Polling** with `GET /v1/payments/{payment_id}` is a fallback for missed webhooks. Do not poll as a primary mechanism.
Never rely on client side status checks. Many transitions (3DS settlement, async APM confirmation, dispute updates, capture retries) happen entirely server side and only ever surface through webhooks.
## Handling each status in your application
| `status` | What to do |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CREATED`, `READY_TO_PAY` | Show "preparing payment" UI. Surface the redirect or QR code if present. |
| `PENDING` | Show "processing" UI. For 3DS, redirect to `require_action.redirect_url`. For async APMs, render the QR code, voucher, or redirect. Set a timeout matched to the method. |
| `VERIFIED` | Card was successfully verified. Store the token if your flow vaults the instrument. |
| `SUCCEEDED` | Confirm the order. Fulfill. Store `payment_id` for refunds. |
| `DECLINED` | Show a generic decline message. Do not expose raw provider codes to customers. See [Provider errors](/troubleshooting/provider-errors). |
| `REJECTED` | Inspect the error response. Fix the request and retry. See [Error codes](/troubleshooting/error-codes). |
| `EXPIRED` | Notify the customer the window closed. Offer to create a new payment. |
| `CANCELED` | Confirm the cancellation. Release reserved inventory. |
| `REFUNDED` | Notify the customer. Update your order record. |
| `IN_DISPUTE` | Pull the dispute, gather evidence, respond before the deadline. |
| `CHARGEBACK` | Funds are gone. Update internal accounting. |
| `ERROR` | Inspect `messages` and `x-trace-id`. Retry transient errors with backoff. Open a support ticket for persistent ones. |
| `FRAUD` | Fraud verification completed. Treat per your risk policy. |
## Related
The conceptual lifecycle, capture modes, and integration patterns.
The operational page: create, capture, refund, and cancel with code.
How status transitions reach your server.
The error envelope and retry strategy for `ERROR`, `DECLINED`, `REJECTED`.