Skip to main content
This guide walks through creating a payment end to end with the REST API in sandbox. For the underlying flow read payment flow. If you don’t want to render the checkout yourself, embed the Yuno SDK. 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.
Handling raw card data requires PCI certification. To stay out of PCI scope, use the Yuno SDK.

​
Prerequisites

A Yuno account with sandbox access. From the Yuno Dashboard, 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 for security rules and key rotation.

​
Create your first payment

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 under each step.
1

Get your credentials

From the Yuno Dashboard open the Developers section and copy your sandbox account_id, public-api-key, and private-secret-key. See authentication for security rules and key rotation.
Never expose your private-secret-key in client code, mobile apps, or version control. Treat it like a database password.
2

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.
cURL
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.
3

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.
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"
  }'
This endpoint returns HTTP 201. The checkout session ID is in the response body as checkout_session.
See Create checkout session.
4

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 instead of creating a duplicate. For cards, payment_method.token is the one-time token produced by the Yuno SDK 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.
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"
    }
  }'
On success this endpoint returns HTTP 201 with the full Payment object. See Create payment for every accepted field (installments, three_ds, metadata, and more) and Avoiding duplicates 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.
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).
{
  "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.
Same API, any method. Only payment_method.type, country, currency, and a few country specific customer fields change. See the country reference for required fields per market.
5

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).
statusWhen you see itTerminal
CREATEDInitial state at creation.No
READY_TO_PAYAwaiting customer action (hosted redirect or QR scan).No
PENDINGAwaiting customer action (3DS), provider confirmation, or async settlement (Pix, Boleto, OXXO, PSE, SPEI, SEPA, ACH, Khipu, BNPL, redirect wallets, crypto).No
VERIFIEDZero amount card authorization succeeded.Yes
SUCCEEDEDPayment completed. Sub status carries detail (APPROVED, CAPTURED, PARTIALLY_CAPTURED, PARTIALLY_REFUNDED).Yes
DECLINEDProvider or issuer declined.Yes
REJECTEDYuno rejected the request for validation or risk reasons.Yes
EXPIREDPayment or authorization expired before completion.Yes
CANCELEDCancellation succeeded (single L spelling, matches the API).Yes
REFUNDEDCaptured funds were returned to the customer.Yes
IN_DISPUTEChargeback or inquiry received, awaiting response.No
CHARGEBACKPredispute deflected; funds lost.Yes
ERRORSystem error such as timeout or upstream failure.No
FRAUDVerified 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 and the payment flow lifecycle.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.

Webhooks concept

How webhooks fit into the payment lifecycle and what events Yuno emits.

Webhook setup

Register your endpoint in the Dashboard.

Webhook events

The full list of event types and payload shapes.

Verify signatures

Confirm every webhook is genuinely from Yuno.

Test locally

Tunnel webhooks to your machine in development.

Register webhook

The API endpoint for programmatic registration.

​
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 and complete recipient onboarding so they can legally receive funds.
  2. Send funds. Call Create payout with the recipient and amount.
  3. Track status. Poll Get payout or rely on the webhook event for the final state.
For the broader concept (split marketplace, scheduling, reversals) see Payouts and Recipients. For account funding flows (top up your Yuno balance) see Account funding.

​
Next steps

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

Payment flow

The end to end lifecycle, status state machine, and capture modes.

Authentication

The two required headers, key rotation, and security rules.

Environments

Sandbox vs production, base URLs, and the go live checklist.

Avoiding duplicates

Use unique business keys to make retries safe across endpoints.

​
Go deeper

SDK overview

The hosted checkout path that handles cards for you on web, iOS, Android, and Flutter.

Payment methods by region

The right methods for each market you serve, with required fields per country.

Sandbox testing

Reproduce declines, 3DS challenges, and edge cases safely before you go live.

Dashboard

Configure providers, routing, risk, and monitoring without code changes.

Error handling

The error envelope, the real code catalog, and a sane retry strategy.

API reference

Every endpoint with request and response schemas.
For product questions or unclear behavior, email support@y.uno.