Quickstart

Make your first checkout session against sandbox in under 5 minutes.

This walkthrough takes you from zero to a working checkout session against Yuno’s sandbox. By the end you’ll have created a session, rendered it in the Yuno SDK, and confirmed the payment landed.

1. Prerequisites

You need:

• A Yuno sandbox account. Sign up if you don’t have one.
• Your sandbox public-api-key and private-secret-key — find them in Dashboard → Developers → API keys. See Authentication for the full key reference.
• Your account_id (sometimes called the account code). Available alongside the API keys.
• curl, or one of: Node 18+, Python 3.9+, Go 1.21+.

Sandbox processes no real funds and exposes no PCI surface. Use it freely for testing.

2. Set your credentials

Export your sandbox credentials so the snippets below can read them:

export YUNO_PUBLIC_API_KEY="pk_sandbox_..."
export YUNO_PRIVATE_SECRET_KEY="sk_sandbox_..."
export YUNO_ACCOUNT_ID="acc_..."

Never commit these values or ship them to a browser bundle. Both keys belong on your server only.

3. Create a checkout session

A checkout session is the entry point for every payment in Yuno. It captures the transaction context (amount, country, order id) and returns an sdk_token your client uses to render the payment UI.

cURL

curl https://api-sandbox.y.uno/v1/checkout/sessions \
  -H "public-api-key: $YUNO_PUBLIC_API_KEY" \
  -H "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "'"$YUNO_ACCOUNT_ID"'",
    "merchant_order_id": "order-2026-001",
    "country": "BR",
    "amount": { "currency": "BRL", "value": 150.00 },
    "payment_description": "First sandbox order",
    "workflow": "SDK_CHECKOUT"
  }'

Node.js

const res = await fetch("https://api-sandbox.y.uno/v1/checkout/sessions", {
  method: "POST",
  headers: {
    "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
    "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_id: process.env.YUNO_ACCOUNT_ID,
    merchant_order_id: "order-2026-001",
    country: "BR",
    amount: { currency: "BRL", value: 150.0 },
    payment_description: "First sandbox order",
    workflow: "SDK_CHECKOUT",
  }),
});
const session = await res.json();
console.log(session.checkout_session, session.sdk_token);

Python

import os, requests

res = requests.post(
    "https://api-sandbox.y.uno/v1/checkout/sessions",
    headers={
        "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
        "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "account_id": os.environ["YUNO_ACCOUNT_ID"],
        "merchant_order_id": "order-2026-001",
        "country": "BR",
        "amount": {"currency": "BRL", "value": 150.00},
        "payment_description": "First sandbox order",
        "workflow": "SDK_CHECKOUT",
    },
)
session = res.json()
print(session["checkout_session"], session["sdk_token"])

Go

payload := strings.NewReader(`{
  "account_id": "` + os.Getenv("YUNO_ACCOUNT_ID") + `",
  "merchant_order_id": "order-2026-001",
  "country": "BR",
  "amount": { "currency": "BRL", "value": 150.00 },
  "payment_description": "First sandbox order",
  "workflow": "SDK_CHECKOUT"
}`)

req, _ := http.NewRequest("POST", "https://api-sandbox.y.uno/v1/checkout/sessions", payload)
req.Header.Set("public-api-key", os.Getenv("YUNO_PUBLIC_API_KEY"))
req.Header.Set("private-secret-key", os.Getenv("YUNO_PRIVATE_SECRET_KEY"))
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)

A successful call returns 200 OK with the session. Hold onto checkout_session (the id) and sdk_token (the value your frontend will mount).

Sample success response

{
  "checkout_session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": { "value": 150.00, "currency": "BRL" },
  "country": "BR",
  "merchant_order_id": "order-2026-001",
  "status": "ACTIVE",
  "payment_description": "First sandbox order",
  "payment_methods": ["CARD", "BANK_TRANSFER", "WALLET"],
  "sdk_token": "stok_sandbox_abc123def456...",
  "created_at": "2026-05-11T14:32:01.482Z"
}

Pass sdk_token to the Yuno SDK on the client; pass checkout_session along with it so the SDK can resolve the session.

Sample error response (4xx)

Every Yuno error returns the same envelope:

{
  "code": "VALIDATION_ERROR",
  "message": "Field 'amount.currency' must be ISO 4217",
  "details": [
    { "field": "amount.currency", "issue": "invalid_format" }
  ],
  "request_id": "req_01HX9P5KXZ7YQ8R0M2T4WV6BNE"
}

Share request_id with Yuno support when opening a ticket. See Error handling for the full code catalog.

4. Render the checkout

The sdk_token is consumed by the Yuno SDK to render the payment UI in your application. Pick your platform and follow the SDK quickstart from there:

Web SDK

Mount the full checkout, seamless, lite, secure-fields, or headless variant in any web app.

Mobile SDKs

iOS, Android, and Flutter quickstarts with native checkout components.

The SDK takes the sdk_token, renders the available payment methods, collects sensitive details client side, and submits to Yuno without your servers ever touching card data.

5. Confirm the payment landed

Once the customer completes the SDK flow, retrieve the resulting payment to confirm its status:

curl https://api-sandbox.y.uno/v1/payments/<payment_id> \
  -H "public-api-key: $YUNO_PUBLIC_API_KEY" \
  -H "private-secret-key: $YUNO_PRIVATE_SECRET_KEY"

A transaction_status of SUCCEEDED means funds are captured. For methods like Pix, Boleto, or PSE you’ll see PENDING synchronously — the final status arrives by webhook. See Async results and timeouts for the full list.

Next steps

Save the card

Vault the customer’s card for one-click checkout and MIT.

Set up webhooks

Receive real-time payment lifecycle events, signed for verification.

Move to production

Swap base URLs and keys; everything else stays the same.