Payments - Yuno API Documentation

A payment is the merchant’s intent to collect funds from a customer. Every payment, regardless of method family, is created through the same POST /v1/payments endpoint. A card, a Pix, a Boleto, a PSE, a SEPA Direct Debit, a digital wallet, a BNPL, a crypto charge: all the same Yuno object created the same way. The payment_method field on the request selects which family is used.

For the conceptual lifecycle (statuses, state machine, capture modes) see payment flow. For every accepted field on the request, see Create payment in the API reference.

What happens when you create a payment

Creating a payment is more than recording a charge. It triggers the orchestration that makes Yuno useful as a single API across hundreds of providers.

Routing picks a provider. On every payment, the orchestrator consults your Smart Routing workflow (configured in the Dashboard) to decide which provider runs the transaction. Rules can route by cost, approval rate, BIN, country, amount, metadata, or any combination.
A transaction is created against that provider. Yuno translates the canonical request into the provider’s specific API, sends it, and waits for the response.
The provider response is normalized. Every provider integration includes a response mapper that converts the provider’s status codes and payload into Yuno’s canonical Payment and Transaction schema. Your code reads the same shape regardless of which provider processed the charge.
If the workflow allows it, Yuno may cascade. When a transaction is DECLINED, errors, or times out, the routing workflow can point to a fallback provider. Yuno creates a new transaction against that provider automatically. The full sequence is visible on the payment as transactions_history. See transactions.
The payment finalizes synchronously or asynchronously. See the next section.

Cascading is not an unconditional “try every provider until one accepts” loop. It only happens when your published routing workflow has a fallback step defined for that specific outcome. Hard declines (stolen card, fraud) typically end the flow rather than cascade. Configure the cascade behavior per outcome in the Dashboard.

Sync vs async finality

The HTTP response from POST /v1/payments is final for some methods and provisional for others. Always treat webhooks as the source of truth.

Path	Sync response	Async settlement
Card, auto capture, no 3DS challenge	Final status (`SUCCEEDED` or `DECLINED`) is returned immediately.	None. The HTTP response is the final word.
Card with a 3DS challenge	`PENDING` with `sub_status: WAITING_ADDITIONAL_STEP` and a redirect or challenge payload.	Final status arrives via webhook after the customer completes the challenge.
Card with a delayed issuer response	`PENDING` with sub status `DELAYED_PROVIDER_RESPONSE` or `PENDING_OTP_COMPLETION`.	Final status arrives via webhook.
Bank transfers (Pix, PSE, BreB, SPEI, SEPA, ACH, Khipu, Fintoc, Belvo, Transfiya, FPX, …)	`PENDING` with the QR code, redirect URL, or instrument detail the customer needs to complete the transfer.	Final status arrives via webhook when the transfer settles.
Cash vouchers (Boleto, OXXO, PagoEfectivo, Servipag, Efecty)	`PENDING` with the voucher reference and expiry.	Webhook fires when the customer pays at the agent or expiry passes.
Redirect wallets (PayPal, Mercado Pago, Yape, Nequi, Daviplata, Modo, Bizum, GCash, Twint, Vipps, …)	`PENDING` with a redirect URL.	Webhook fires after the customer authorizes in the wallet app.
BNPL (Klarna, Afterpay, Clearpay, Tabby, Tamara, Atome)	`PENDING` with a redirect to the BNPL provider’s flow.	Webhook fires after the BNPL provider completes its check.
Crypto	`PENDING` with the address or QR code to send to.	Webhook fires after enough network confirmations.

Register your endpoint via webhook setup, verify signatures per signature verification, and treat the latest webhook event as the source of truth for any payment that returns PENDING. See also Timeouts and async results.

Where checkout sessions fit in

Checkout sessions are optional on POST /v1/payments. SDK and hosted checkout integrations create a checkout session first so the Yuno SDK can render available methods, tokenize cards, and tie the flow together. Direct API integrations (server to server, with raw card data or network tokens) can skip the session entirely and call POST /v1/payments directly. The checkout field on the payment request is optional in that flow. See the Direct API guide.

Create a payment

For CARD via the SDK path, payment_method.token comes from the Yuno SDK after the customer enters card data on the client. For Direct API, you send payment_method.vaulted_token (a network token or vaulted PAN) instead.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "checkout_session": "cs_abc123def456",
    "payment_method": {
      "type": "CARD",
      "token": "tok_from-the-sdk"
    },
    "amount": { "currency": "USD", "value": 100.00 },
    "country": "US",
    "customer": {
      "first_name": "Dee",
      "last_name": "Hock",
      "email": "dee@hock.example"
    }
  }'

See Create payment for every accepted field (installments, three_ds, metadata, and more) and idempotency for safe retry behavior.

Authorize, then capture

Auto capture is the default. To split authorization from capture (see payment flow for when and why), pass payment_method.detail.card.capture: false on create, then call the capture endpoint once you know the final amount.

Create with auth only

{
  "checkout_session": "cs_abc123def456",
  "payment_method": {
    "type": "CARD",
    "token": "tok_from-the-sdk",
    "detail": {
      "card": {
        "capture": false,
        "installments": 1
      }
    }
  },
  "amount": { "currency": "USD", "value": 200.00 },
  "country": "US"
}

The response returns status: PENDING, sub_status: AUTHORIZED and a transaction of type: AUTHORIZE. Use the transaction_id from that response to capture.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{payment_id}/transactions/{transaction_id}/capture \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key'

See Authorize payment and Capture transaction.

Authorized payments must be captured within the provider’s hold window (varies by scheme and acquirer. Check your provider’s policy). Uncaptured authorizations are voided automatically.

Refund

Refund fully or partially. Omit amount for a full refund.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{payment_id}/refund \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 50.00,
    "reason": "Customer requested partial refund"
  }'

See Refund payment and Cancel or refund for the helper that picks the right operation based on current status.

Refund availability depends on the method and provider. Some cash voucher methods like Boleto and OXXO cannot be refunded programmatically and require a manual process.

Cancel

Cancel a payment before capture.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{payment_id}/cancel \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \

See Cancel payment. To cancel or refund depending on status, use Cancel or refund.

Required fields by method

Every method has its own required customer fields. For the per-country breakdown (documents, email, IBAN, VPA, and so on) see payment methods.

Call Get payment methods on a checkout session to discover which methods are available and which fields each one needs.

Dispute creation and updates

Payments can have disputes raised against them. The API supports creating dispute records and updating their state.

Notify fulfillment

Some flows (marketplace releases, subscription renewals with later shipment) require notifying Yuno when an order is fulfilled.

Notify fulfillment

What next

Payment flow

The conceptual lifecycle: statuses, state machine, and capture modes.

Transactions

How a single payment can generate multiple provider attempts.

Payment methods

Method specific requirements and how each method behaves.

API reference

The full Payment object, all fields, and every endpoint.

​What happens when you create a payment

​Sync vs async finality

​Where checkout sessions fit in

​Create a payment

​Authorize, then capture

​Refund

​Cancel

​Required fields by method

​Dispute creation and updates

​Notify fulfillment

​What next

Payment flow

Transactions

Payment methods

API reference

What happens when you create a payment

Sync vs async finality

Where checkout sessions fit in

Create a payment

Authorize, then capture

Refund

Cancel

Required fields by method

Dispute creation and updates

Notify fulfillment

What next