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.

Click the diagram to open it full size in a new tab.

The flow, step by step

1. Create a customer

   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.

2. Create a checkout session

   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.

   Only required for SDK integrations. The checkout session is what the Yuno SDK uses to render available methods, tokenize cards, and tie the flow together. If you are integrating through the Direct API (server to server with raw card data or network tokens) you can skip this step and call Create payment directly. The checkout field on the payment request is optional in that flow.

   {
     "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 for every field, validation rule, and the full response shape.

3. Customer selects a payment method

   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, the SDK renders the options, validates input, and tokenizes card data. Without the SDK, your server fetches the list via Get payment methods and renders its own UI. See the integration overview for the trade offs between each path.

4. Create the payment

   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 instead of creating a duplicate. See Create payment and Avoiding duplicates.

5. Yuno routes and processes

   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.

6. Webhook delivers the final status

   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 and see webhook 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 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.
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.

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.

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. See Authorize Payment.

Payment statuses reference

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 and Capture transaction.

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 to pick the path that fits your team.

What next

Quickstart

Build your first payment end to end with cURL, Node, or Python.

Payments

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

Transactions

What happens underneath a payment when Yuno cascades or retries.

Checkout sessions

The purchase intent you create before a payment.

Webhooks

How final payment statuses actually reach your server.

Avoiding duplicates

Use unique business keys to make retries safe.