> ## 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 flow
> How a payment moves through Yuno end to end. The lifecycle, the status state machine, capture modes, and the integration patterns.
A Yuno payment follows the same path every time. Your server creates a customer and a checkout session, the customer picks a method, Yuno routes the transaction to the right provider, the provider processes it, and a webhook delivers the final status. This page covers both the narrative ("what happens at each step") and the reference ("what statuses, what capture modes, what integration patterns"). For the operational side (code to create, capture, refund, cancel) see [payments](/core-concepts/payments).
Click the diagram to open it full size in a new tab.
## The flow, step by step
Customers are your record of each buyer. Every payment, token, and saved method attaches to a customer. Many local methods also require a customer document (tax ID, national ID) before they can process, so you create the record up front and reuse the `customer_id` across future purchases.
Your server calls `POST /v1/customers` and stores the returned `customer_id`. See [Create customer](/api-reference/customers/create).
The checkout session commits a single purchase intent: amount, currency, country, and customer. Yuno uses it to compute which methods are available for that combination, and it ties the customer's method selection, authentication, and final payment together.
Your server calls `POST /v1/checkout/sessions` and returns the session token to your client. See [Create checkout session](/api-reference/checkout-sessions/create).
**Only required for SDK integrations.** The checkout session is what the [Yuno SDK](/guides/sdk/overview) uses to render available methods, tokenize cards, and tie the flow together. If you are integrating through the [Direct API](/guides/direct-api/overview) (server to server with raw card data or network tokens) you can skip this step and call [Create payment](/api-reference/payments/create) directly. The `checkout` field on the payment request is optional in that flow.
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
"account_id": "34a7c1a8-b5cf-11ec-b909-0242ac120002",
"merchant_order_id": "order-12345",
"payment_description": "Premium subscription",
"country": "US",
"amount": { "currency": "USD", "value": 150.00 },
"customer_id": "50bae77e-c65c-11ec-9d64-0242ac120002"
}
```
Required: `account_id` (UUID v4), `merchant_order_id`, `payment_description`, `country`, `amount`. `customer_id` is optional but must be a Yuno customer UUID v4 if sent. See [Create checkout session](/api-reference/checkout-sessions/create) for every field, validation rule, and the full response shape.
Each market has different methods customers expect. The session already knows which ones apply based on country, currency, and your provider configuration. With the [Yuno SDK](/guides/sdk/overview), the SDK renders the options, validates input, and tokenizes card data. Without the SDK, your server fetches the list via [Get payment methods](/api-reference/checkout-sessions/get-payment-methods) and renders its own UI. See the [integration overview](/guides/integration-overview) for the trade offs between each path.
The payment turns the session plus the selected method into a real charge. Your server calls `POST /v1/payments` with the checkout session id, the selected method, and any method specific fields (for example `customer.document` for Pix or Boleto). Use a stable `merchant_order_id` so a retry can be looked up via [Get Payment by Merchant Order](/api-reference/payments/get-by-merchant-order) instead of creating a duplicate. See [Create payment](/api-reference/payments/create) and [Avoiding duplicates](/core-concepts/idempotency).
Orchestration happens here and you do not write it. Yuno picks the best provider from your configured routing rules (cost, approval rate, BIN, geography), handles 3DS authentication on card flows when the issuer requires it, retries with a fallback provider on declines or timeouts, and normalizes the response so your code sees a consistent shape across every provider. See [multi-provider orchestration](/guides/multi-provider-orchestration).
Yuno POSTs the final payment status to your webhook endpoint. This is the source of truth, especially for asynchronous methods like Pix (the customer pays after scanning a QR code) or Boleto (the customer pays at a bank or convenience store). Register your endpoint via [Webhook registration](/api-reference/webhooks/register) and see [webhook setup](/guides/webhooks/setup) for signature verification and retry behavior.
Rely on webhooks for final payment status, not the synchronous API response. Asynchronous methods typically return `PENDING` at creation and settle to `SUCCEEDED` or `DECLINED` later through a webhook. See [Timeouts and async results](/api-reference/introduction#timeouts-and-async-results) for the full list of methods that behave this way.
## Key components
| Component | Role | Lifecycle |
| -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Checkout session** | Initializes purchase intent and determines available methods. | Created once per purchase attempt. |
| **Payment** | Represents the charge against a selected method. | One per checkout session. |
| **Transaction** | A single processing attempt inside a payment. | Multiple if Yuno retries or cascades across providers. See [transactions](/core-concepts/transactions). |
| **Provider** | The acquirer or processor that executes the charge. | Selected by the routing engine per transaction. |
| **Webhook** | Asynchronous notification of status changes. | Delivered on every status transition. See [webhooks](/core-concepts/webhooks). |
## Payment statuses
Yuno uses a two level model: a top level `status` and an optional `sub_status` that adds detail. For the full sub status taxonomy see [Payment statuses](/reference/payment-statuses).
| Top level `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` | Multiple sub statuses for various processing states (such as `AUTHORIZED`, `IN_PROCESS`, `WAITING_ADDITIONAL_STEP`, `PENDING_PROVIDER_CONFIRMATION`). | No |
| `VERIFIED` | Zero amount card authorization succeeded. | Yes |
| `SUCCEEDED` | Payment completed. Sub status carries detail like `APPROVED`, `CAPTURED`, `PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`. | Yes |
| `DECLINED` | Provider or issuer declined the transaction. | Yes |
| `REJECTED` | Yuno rejected the request for validation or risk reasons. | Yes |
| `EXPIRED` | Payment or authorization window expired before completion. | 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, awaiting response. | No |
| `CHARGEBACK` | Predispute deflected; funds lost. | Yes |
| `ERROR` | System error such as timeout or upstream failure. | No |
| `FRAUD` | Transaction verified by fraud provider during stand alone fraud verification. | Yes |
Non terminal statuses can still transition. Terminal statuses will not change further. Async methods typically surface `PENDING` first, then move to a terminal status through a webhook.
`AUTHORIZED` is a **sub status of `PENDING`**, not a top level status. Auth only flows return `status: PENDING, sub_status: AUTHORIZED` until you call [Capture](/api-reference/payments/capture). See [Authorize Payment](/api-reference/payments/authorize).
Every status, every sub status, and every transition in the payment lifecycle.
### Status state machine
Click the diagram to open it full size in a new tab.
## Capture modes
Yuno supports two capture strategies. The mode you choose decides when funds actually move.
### Auto capture (default)
The payment authorizes and captures in one step. It moves from `PENDING` directly to `SUCCEEDED` (or `DECLINED`). This is the right default for standard ecommerce where the charge amount is known up front.
### Auth only (two step)
When the final amount is not known up front (hotels, car rentals, pre orders, marketplace releases), separate authorization from capture:
1. **Create the payment** with `payment_method.detail.card.capture: false`. Status becomes `PENDING` with sub status `AUTHORIZED` once the provider reserves funds.
2. **Capture later** with the captured amount. Status moves to `SUCCEEDED`.
See [Authorize Payment](/api-reference/payments/authorize) and [Capture transaction](/api-reference/payments/capture).
Authorized payments that are not captured within the issuer's hold window are voided automatically. The window is typically **7 days** for most card schemes, but it varies by issuer and MCC. Check your provider's policy before relying on a specific duration.
How the customer's method data is collected (Full SDK, Lite / Secure Fields, or Direct API) changes your PCI scope but not the payment flow itself. See [integration overview](/guides/integration-overview) to pick the path that fits your team.
## What next
Build your first payment end to end with cURL, Node, or Python.
The operational page: create, capture, refund, and cancel with code.
What happens underneath a payment when Yuno cascades or retries.
The purchase intent you create before a payment.
How final payment statuses actually reach your server.
Use unique business keys to make retries safe.