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

> Create your first payment, and learn how payouts use the same API surface.

This guide walks through creating a payment end to end with the REST API in sandbox. For the underlying flow read [payment flow](/core-concepts/payment-flow).

If you don't want to render the checkout yourself, embed the [Yuno SDK](/guides/sdk/overview). It puts card fields in PCI-scoped iframes, drives alternative payment methods and 3DS flows, and applies the theme, method order, and required fields your team configures in the [Checkout Builder](/platform/dashboard/checkout-builder).

<Note>
  Handling raw card data requires PCI certification. To stay out of PCI scope, use the [Yuno SDK](/guides/sdk/overview).
</Note>

## Prerequisites

A Yuno account with sandbox access. From the [Yuno Dashboard](https://dashboard.y.uno), open the **Developers** section and copy three values:

* **`account_id`**: your merchant account identifier. Sent in request bodies on endpoints that take it.
* **`public-api-key`**: sent as an HTTP header on every call.
* **`private-secret-key`**: sent as an HTTP header on every call. Treat it like a database password.

See [authentication](/getting-started/authentication) for security rules and key rotation.

## Create your first payment

<Note>
  The code samples below show the **minimum required fields** for each call. For every accepted parameter, optional field, and response shape, see the linked endpoint in the [API reference](/api-reference/introduction) under each step.
</Note>

<Steps>
  <Step title="Get your credentials">
    From the [Yuno Dashboard](https://dashboard.y.uno) open the **Developers** section and copy your sandbox `account_id`, `public-api-key`, and `private-secret-key`. See [authentication](/getting-started/authentication) for security rules and key rotation.

    <Warning>
      Never expose your `private-secret-key` in client code, mobile apps, or version control. Treat it like a database password.
    </Warning>
  </Step>

  <Step title="Create a customer">
    Customers are your record of each buyer. Every payment attaches to one, and many local methods need the customer's document or contact details up front. Create the customer once and reuse the `customer_id` across future purchases.

    ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
    curl -X POST https://api-sandbox.y.uno/v1/customers \
      -H "public-api-key: your-public-api-key" \
      -H "private-secret-key: your-private-secret-key" \
      -H "Content-Type: application/json" \
      -d '{
        "merchant_customer_id": "cust-001",
        "first_name": "Dee",
        "last_name": "Hock",
        "email": "dee@hock.example"
      }'
    ```

    See [Create customer](/api-reference/customers/create).
  </Step>

  <Step title="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 and to tie the rest of the flow together.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      curl -X POST https://api-sandbox.y.uno/v1/checkout/sessions \
        -H "public-api-key: your-public-api-key" \
        -H "private-secret-key: your-private-secret-key" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": {
            "currency": "USD",
            "value": 50.00
          },
          "country": "US",
          "customer_id": "your-customer-id",
          "merchant_order_id": "order-001",
          "payment_description": "Test payment",
          "account_id": "your-account-id"
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      const response = await fetch('https://api-sandbox.y.uno/v1/checkout/sessions', {
        method: 'POST',
        headers: {
          'public-api-key': 'your-public-api-key',
          'private-secret-key': 'your-private-secret-key',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          amount: { currency: 'USD', value: 50.00 },
          country: 'US',
          customer_id: 'your-customer-id',
          merchant_order_id: 'order-001',
          payment_description: 'Test payment',
          account_id: 'your-account-id',
        }),
      });

      const session = await response.json();
      // Use session.checkout_session for the next step
      ```

      ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api-sandbox.y.uno/v1/checkout/sessions',
          headers={
              'public-api-key': 'your-public-api-key',
              'private-secret-key': 'your-private-secret-key',
              'Content-Type': 'application/json',
          },
          json={
              'amount': {'currency': 'USD', 'value': 50.00},
              'country': 'US',
              'customer_id': 'your-customer-id',
              'merchant_order_id': 'order-001',
              'payment_description': 'Test payment',
              'account_id': 'your-account-id',
          },
      )

      session = response.json()
      # Use session['checkout_session'] for the next step
      ```
    </CodeGroup>

    <Note>
      This endpoint returns HTTP **201**. The checkout session ID is in the response body as `checkout_session`.
    </Note>

    See [Create checkout session](/api-reference/checkout-sessions/create).
  </Step>

  <Step title="Create a payment">
    Use the checkout session to create a payment. Set a stable `merchant_order_id` so a retry after a network failure can be looked up via [Get Payment by Merchant Order](/api-reference/payments/get-by-merchant-order) instead of creating a duplicate. For cards, `payment_method.token` is the [one-time token](/core-concepts/tokens#one-time-token) produced by the [Yuno SDK](/guides/sdk/overview) when the customer enters card data on the client. Use `workflow: "DIRECT"` for server to server REST flows; `SDK_CHECKOUT` and `REDIRECT` are the other supported values.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      curl -X POST https://api-sandbox.y.uno/v1/payments \
        -H "public-api-key: your-public-api-key" \
        -H "private-secret-key: your-private-secret-key" \
        -H "Content-Type: application/json" \
        -d '{
          "account_id": "your-account-id",
          "description": "Test payment",
          "merchant_order_id": "order-001",
          "merchant_reference": "ref-001",
          "country": "US",
          "amount": { "currency": "USD", "value": 50.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": {
            "type": "CARD",
            "token": "tok_from-the-sdk"
          },
          "customer_payer": {
            "merchant_customer_id": "cust-001",
            "email": "dee@hock.example",
            "first_name": "Dee",
            "last_name": "Hock"
          }
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      const payment = await fetch('https://api-sandbox.y.uno/v1/payments', {
        method: 'POST',
        headers: {
          'public-api-key': 'your-public-api-key',
          'private-secret-key': 'your-private-secret-key',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          account_id: 'your-account-id',
          description: 'Test payment',
          merchant_order_id: 'order-001',
          merchant_reference: 'ref-001',
          country: 'US',
          amount: { currency: 'USD', value: 50.00 },
          workflow: 'DIRECT',
          checkout: { session: 'your-checkout-session-id' },
          payment_method: { type: 'CARD', token: 'tok_from-the-sdk' },
          customer_payer: {
            merchant_customer_id: 'cust-001',
            email: 'dee@hock.example',
            first_name: 'Dee',
            last_name: 'Hock',
          },
        }),
      });

      const result = await payment.json();
      ```

      ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api-sandbox.y.uno/v1/payments',
          headers={
              'public-api-key': 'your-public-api-key',
              'private-secret-key': 'your-private-secret-key',
              'Content-Type': 'application/json',
          },
          json={
              'account_id': 'your-account-id',
              'description': 'Test payment',
              'merchant_order_id': 'order-001',
              'merchant_reference': 'ref-001',
              'country': 'US',
              'amount': {'currency': 'USD', 'value': 50.00},
              'workflow': 'DIRECT',
              'checkout': {'session': 'your-checkout-session-id'},
              'payment_method': {'type': 'CARD', 'token': 'tok_from-the-sdk'},
              'customer_payer': {
                  'merchant_customer_id': 'cust-001',
                  'email': 'dee@hock.example',
                  'first_name': 'Dee',
                  'last_name': 'Hock',
              },
          },
      )

      payment = response.json()
      ```
    </CodeGroup>

    On success this endpoint returns HTTP **201** with the full Payment object. See [Create payment](/api-reference/payments/create) for every accepted field (`installments`, `three_ds`, `metadata`, and more) and [Avoiding duplicates](/core-concepts/idempotency) for safe retry behavior.

    ### Local methods

    The CARD example above is the simplest case. Yuno supports 1000+ methods through the same `POST /v1/payments` endpoint. Only `payment_method.type`, `country`, `currency`, and a few `customer_payer` fields change. The other root fields (`account_id`, `description`, `merchant_order_id`, `merchant_reference`, `workflow`, `checkout`) stay the same as the CARD example.

    Select a region to see how the body adapts.

    <Tabs>
      <Tab title="Brazil, Pix">
        Pix is Brazil's instant payment system. Real time, 24/7, and the most popular method in the country. Requires a CPF (individual tax ID) or CNPJ (business tax ID).

        ```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "Pix payment",
          "merchant_order_id": "order-br-001",
          "merchant_reference": "ref-br-001",
          "country": "BR",
          "amount": { "currency": "BRL", "value": 100.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "PIX" },
          "customer_payer": {
            "merchant_customer_id": "cust-001",
            "email": "cliente@example.com",
            "first_name": "Maria",
            "last_name": "Silva",
            "document": {
              "document_type": "CPF",
              "document_number": "12345678901"
            }
          }
        }
        ```

        The response returns a QR code and a copy paste code. The customer pays from their banking app and you receive confirmation in seconds through a webhook.
      </Tab>

      <Tab title="India, UPI">
        UPI (Unified Payments Interface) is India's dominant real time method, processing billions of transactions monthly through apps like Google Pay, PhonePe, and Paytm.

        ```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "UPI payment",
          "merchant_order_id": "order-in-001",
          "merchant_reference": "ref-in-001",
          "country": "IN",
          "amount": { "currency": "INR", "value": 2500.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "UPI" },
          "customer_payer": {
            "merchant_customer_id": "cust-002",
            "email": "customer@example.com",
            "first_name": "Priya",
            "last_name": "Sharma"
          }
        }
        ```

        UPI generates a payment link or QR code. The customer authorizes through their UPI app and you receive confirmation through a webhook.
      </Tab>

      <Tab title="Europe, iDEAL and SEPA">
        **iDEAL** is the leading bank redirect method in the Netherlands with over 70% of online payments. **SEPA** covers 36 European countries for euro payments.

        ```json iDEAL (Netherlands) theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "iDEAL payment",
          "merchant_order_id": "order-nl-001",
          "merchant_reference": "ref-nl-001",
          "country": "NL",
          "amount": { "currency": "EUR", "value": 75.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "IDEAL" },
          "customer_payer": {
            "merchant_customer_id": "cust-003",
            "email": "customer@example.com",
            "first_name": "Jan",
            "last_name": "de Vries"
          }
        }
        ```

        ```json SEPA (EU wide) theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "SEPA payment",
          "merchant_order_id": "order-de-001",
          "merchant_reference": "ref-de-001",
          "country": "DE",
          "amount": { "currency": "EUR", "value": 49.99 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "SEPA" },
          "customer_payer": {
            "merchant_customer_id": "cust-004",
            "email": "customer@example.com",
            "first_name": "Max",
            "last_name": "Mustermann"
          }
        }
        ```

        iDEAL redirects to the customer's bank for instant confirmation. SEPA is pull based, ideal for subscriptions and recurring billing.
      </Tab>

      <Tab title="Asia, Alipay and WeChat Pay">
        **Alipay** and **WeChat Pay** together cover over 90% of mobile payments in China, with growing cross border acceptance across Southeast Asia.

        ```json Alipay theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "Alipay payment",
          "merchant_order_id": "order-cn-001",
          "merchant_reference": "ref-cn-001",
          "country": "CN",
          "amount": { "currency": "CNY", "value": 500.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "ALIPAY" },
          "customer_payer": {
            "merchant_customer_id": "cust-005",
            "email": "customer@example.com",
            "first_name": "Wei",
            "last_name": "Zhang"
          }
        }
        ```

        ```json WeChat Pay theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "WeChat Pay payment",
          "merchant_order_id": "order-cn-002",
          "merchant_reference": "ref-cn-002",
          "country": "CN",
          "amount": { "currency": "CNY", "value": 500.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "WECHAT_PAY" },
          "customer_payer": {
            "merchant_customer_id": "cust-006",
            "email": "customer@example.com",
            "first_name": "Wei",
            "last_name": "Zhang"
          }
        }
        ```

        Both generate a QR code for in app scanning. For cross border scenarios, amounts can be quoted in your local currency and converted automatically.
      </Tab>

      <Tab title="US, ACH bank debit">
        ACH (Automated Clearing House) is the standard bank rail in the United States. Lower fees than cards and ideal for large or recurring payments.

        ```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
        {
          "account_id": "your-account-id",
          "description": "ACH payment",
          "merchant_order_id": "order-us-001",
          "merchant_reference": "ref-us-001",
          "country": "US",
          "amount": { "currency": "USD", "value": 250.00 },
          "workflow": "DIRECT",
          "checkout": { "session": "your-checkout-session-id" },
          "payment_method": { "type": "ACH" },
          "customer_payer": {
            "merchant_customer_id": "cust-007",
            "email": "customer@example.com",
            "first_name": "Dee",
            "last_name": "Hock"
          }
        }
        ```

        ACH payments settle in 1 to 3 business days. Track status transitions from `PENDING` to `SUCCEEDED` through webhooks.
      </Tab>
    </Tabs>

    <Tip>
      Same API, any method. Only `payment_method.type`, `country`, `currency`, and a few country specific customer fields change. See the [country reference](/reference/country-reference) for required fields per market.
    </Tip>
  </Step>

  <Step title="Handle the response and webhooks">
    Every payment response carries a top level `status` and an optional `sub_status`. There are 14 top level values. Branch on `status` for routing logic; read `sub_status` when you need detail (for example `AUTHORIZED` is a sub status of `PENDING`, not a top level value).

    | `status`       | When you see it                                                                                                                                              | Terminal |
    | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
    | `CREATED`      | Initial state at creation.                                                                                                                                   | No       |
    | `READY_TO_PAY` | Awaiting customer action (hosted redirect or QR scan).                                                                                                       | No       |
    | `PENDING`      | Awaiting customer action (3DS), provider confirmation, or async settlement (Pix, Boleto, OXXO, PSE, SPEI, SEPA, ACH, Khipu, BNPL, redirect wallets, crypto). | No       |
    | `VERIFIED`     | Zero amount card authorization succeeded.                                                                                                                    | Yes      |
    | `SUCCEEDED`    | Payment completed. Sub status carries detail (`APPROVED`, `CAPTURED`, `PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`).                                           | Yes      |
    | `DECLINED`     | Provider or issuer declined.                                                                                                                                 | Yes      |
    | `REJECTED`     | Yuno rejected the request for validation or risk reasons.                                                                                                    | Yes      |
    | `EXPIRED`      | Payment or authorization 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`        | Verified by fraud provider during stand alone fraud verification.                                                                                            | Yes      |

    For the full sub status taxonomy (every value `sub_status` can take per top level status) see [Payment statuses](/reference/payment-statuses) and the [payment flow lifecycle](/core-concepts/payment-flow#payment-statuses).

    **Webhooks are the source of truth for final status.** Any payment that returns `PENDING` synchronously will settle later through a webhook event. Register your endpoint, verify every payload, and treat the latest event as canonical.

    <CardGroup cols={2}>
      <Card title="Webhooks concept" icon="bell" href="/core-concepts/webhooks">
        How webhooks fit into the payment lifecycle and what events Yuno emits.
      </Card>

      <Card title="Webhook setup" icon="plug" href="/guides/webhooks/setup">
        Register your endpoint in the Dashboard.
      </Card>

      <Card title="Webhook events" icon="rectangle-list" href="/guides/webhooks/events">
        The full list of event types and payload shapes.
      </Card>

      <Card title="Verify signatures" icon="shield-check" href="/guides/webhooks/verify-signatures">
        Confirm every webhook is genuinely from Yuno.
      </Card>

      <Card title="Test locally" icon="flask" href="/guides/webhooks/testing-locally">
        Tunnel webhooks to your machine in development.
      </Card>

      <Card title="Register webhook" icon="code" href="/api-reference/webhooks/register">
        The API endpoint for programmatic registration.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Payouts

Payouts disburse funds **out** of your Yuno balance to a recipient (sellers, marketplace participants, vendors). They share authentication, idempotency, and webhooks with payins, so you do not learn a second API. The model is:

1. **Onboard the recipient.** Create a [recipient](/api-reference/recipients/object) and complete [recipient onboarding](/api-reference/recipients/create-onboarding) so they can legally receive funds.
2. **Send funds.** Call [Create payout](/api-reference/payouts/create) with the recipient and amount.
3. **Track status.** Poll [Get payout](/api-reference/payouts/get) or rely on the webhook event for the final state.

For the broader concept (split marketplace, scheduling, reversals) see [Payouts](/features/payouts) and [Recipients](/api-reference/recipients/object). For account funding flows (top up your Yuno balance) see [Account funding](/features/account-funding).

## Next steps

Now that you have a working sandbox payment, harden your integration with the foundations every production setup needs.

<CardGroup cols={2}>
  <Card title="Payment flow" icon="arrows-spin" href="/core-concepts/payment-flow">
    The end to end lifecycle, status state machine, and capture modes.
  </Card>

  <Card title="Authentication" icon="lock" href="/getting-started/authentication">
    The two required headers, key rotation, and security rules.
  </Card>

  <Card title="Environments" icon="server" href="/getting-started/environments">
    Sandbox vs production, base URLs, and the go live checklist.
  </Card>

  <Card title="Avoiding duplicates" icon="rotate" href="/core-concepts/idempotency">
    Use unique business keys to make retries safe across endpoints.
  </Card>
</CardGroup>

## Go deeper

<CardGroup cols={2}>
  <Card title="SDK overview" icon="window" href="/guides/sdk/overview">
    The hosted checkout path that handles cards for you on web, iOS, Android, and Flutter.
  </Card>

  <Card title="Payment methods by region" icon="globe" href="/guides/payment-methods/by-region">
    The right methods for each market you serve, with required fields per country.
  </Card>

  <Card title="Sandbox testing" icon="flask" href="/guides/testing/sandbox-guide">
    Reproduce declines, 3DS challenges, and edge cases safely before you go live.
  </Card>

  <Card title="Dashboard" icon="gauge-high" href="/platform/dashboard/overview">
    Configure providers, routing, risk, and monitoring without code changes.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/core-concepts/error-handling">
    The error envelope, the real code catalog, and a sane retry strategy.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/introduction">
    Every endpoint with request and response schemas.
  </Card>
</CardGroup>

For product questions or unclear behavior, email [support@y.uno](mailto:support@y.uno).