> ## 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.

# Payments

> Create, authorize, capture, refund, and cancel payments through the Yuno API, with working examples and direct API reference links.

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.

<Note>
  For the conceptual lifecycle (statuses, state machine, capture modes) see [payment flow](/core-concepts/payment-flow). For every accepted field on the request, see [Create payment](/api-reference/payments/create) in the API reference.
</Note>

## 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.

1. **Routing picks a provider.** On every payment, the orchestrator consults your [Smart Routing workflow](/platform/dashboard/routing) (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.
2. **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.
3. **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.
4. **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](/core-concepts/transactions).
5. **The payment finalizes synchronously or asynchronously.** See the next section.

<Info>
  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.
</Info>

## 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](/guides/webhooks/setup), verify signatures per [signature verification](/guides/webhooks/verify-signatures), and treat the latest webhook event as the source of truth for any payment that returns `PENDING`. See also [Timeouts and async results](/api-reference/introduction#timeouts-and-async-results).

## Where checkout sessions fit in

<Info>
  **Checkout sessions are optional on `POST /v1/payments`.** SDK and hosted checkout integrations create a [checkout session](/core-concepts/checkout-sessions) first so the [Yuno SDK](/guides/sdk/overview) 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](/guides/direct-api/overview).
</Info>

## Create a payment

For CARD via the SDK path, `payment_method.token` comes from the [Yuno SDK](/guides/sdk/overview) 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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  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"
      }
    }'
  ```
</CodeGroup>

See [Create payment](/api-reference/payments/create) for every accepted field (`installments`, `three_ds`, `metadata`, and more) and [idempotency](/core-concepts/idempotency) for safe retry behavior.

## Authorize, then capture

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

```json Create with auth only theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "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.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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](/api-reference/payments/authorize) and [Capture transaction](/api-reference/payments/capture).

<Warning>
  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.
</Warning>

## Refund

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

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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](/api-reference/payments/refund) and [Cancel or refund](/api-reference/payments/cancel-or-refund) for the helper that picks the right operation based on current status.

<Note>
  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.
</Note>

## Cancel

Cancel a payment before capture.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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](/api-reference/payments/cancel). To cancel or refund depending on status, use [Cancel or refund](/api-reference/payments/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](/core-concepts/payment-methods#method-specific-requirements).

<Tip>
  Call [Get payment methods](/api-reference/checkout-sessions/get-payment-methods) on a checkout session to discover which methods are available and which fields each one needs.
</Tip>

## Dispute creation and updates

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

* [Create dispute](/api-reference/payments/create-dispute)
* [Update dispute](/api-reference/payments/update-dispute)

## Notify fulfillment

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

* [Notify fulfillment](/api-reference/payments/notify-fulfillment)

## What next

<div className="mdx-card-tiles">
  <CardGroup cols={2}>
    <Card title="Payment flow" icon="arrows-spin" href="/core-concepts/payment-flow">
      The conceptual lifecycle: statuses, state machine, and capture modes.
    </Card>

    <Card title="Transactions" icon="arrow-right-arrow-left" href="/core-concepts/transactions">
      How a single payment can generate multiple provider attempts.
    </Card>

    <Card title="Payment methods" icon="wallet" href="/core-concepts/payment-methods">
      Method specific requirements and how each method behaves.
    </Card>

    <Card title="API reference" icon="book" href="/api-reference/payments/object">
      The full Payment object, all fields, and every endpoint.
    </Card>
  </CardGroup>
</div>