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. 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.
REJECTED	Inspect the error response. Fix the request and retry. See 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

Payment flow

The conceptual lifecycle, capture modes, and integration patterns.

Payments

The operational page: create, capture, refund, and cancel with code.

Webhooks

How status transitions reach your server.

Error handling

The error envelope and retry strategy for ERROR, DECLINED, REJECTED.