Skip to main content
PIX is Brazil’s instant payment system, operated by the Banco Central do Brasil. Transfers settle in seconds, 24/7, including weekends and holidays. It is the most widely used payment method in Brazil across consumer and B2B transactions.

​
Prerequisites

Before creating a PIX payment:
  • Country must be BR, currency must be BRL.
  • The customer must have a valid Brazilian tax ID: CPF (individuals, 11 digits) or CNPJ (businesses, 14 digits).
  • A PIX provider must be configured and enabled in Dashboard > Connections.
PIX payments without a valid customer.document field return a 400 INVALID_FIELD error. This is a Brazilian Central Bank regulatory requirement, not a Yuno limitation.

​
Payment flow

1

Create (or retrieve) a customer with document

The customer object must include the Brazilian tax ID. You can create a customer ahead of time or include the customer_payer inline in the payment request.
curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "merchant_customer_id": "customer-001",
    "first_name": "Ana",
    "last_name": "Silva",
    "email": "ana.silva@example.com",
    "document": {
      "document_type": "CPF",
      "document_number": "12345678901"
    }
  }'
2

Create a checkout session (backend)

curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header 'Content-Type: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_KEY' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "country": "BR",
    "customer_payer": { "id": "CUSTOMER_ID" },
    "amount": { "currency": "BRL", "value": "15000" }
  }'
3

Create the PIX payment (backend)

Pass payment_method.type = "PIX" along with the customer document. The checkout_session links the payment to the SDK session.
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "merchant_order_id": "order-br-001",
    "checkout_session": "SESSION_ID",
    "country": "BR",
    "amount": { "value": 15000, "currency": "BRL" },
    "payment_method": { "type": "PIX" },
    "customer_payer": {
      "id": "CUSTOMER_ID",
      "document": {
        "document_type": "CPF",
        "document_number": "12345678901"
      }
    }
  }'
A successful response returns status: "PENDING" — PIX is asynchronous.
4

Display the QR code to the customer

The payment response contains the PIX QR code in payment_method.detail:
{
  "payment_method": {
    "detail": {
      "qr_code": "BASE64_OR_STRING",
      "qr_code_url": "https://...",
      "expires_at": "2026-04-01T14:30:00Z"
    }
  }
}
  • If qr_code is a base64 string, render it as an <img src="data:image/png;base64,...">.
  • If qr_code is a PIX copy-paste string (EMV format), display it alongside a QR code generated on the frontend.
  • Always show the expiry countdown to prompt the customer to pay before it lapses.

​
PIX expiry

PIX transactions expire if the customer does not pay within the window set during payment creation (default: 30 minutes in most providers, minimum: 15 minutes). Once expired, the payment status transitions to EXPIRED and cannot be reused — create a new payment. To set a custom expiry, pass payment_method.expiration_date in the payment request (ISO 8601 format). Check your provider’s configuration in the Yuno Dashboard for supported ranges.

​
Confirming completion via webhook

PIX completion is asynchronous. When the customer pays, the Brazilian banking network notifies Yuno, which fires a PAYMENT_STATE_CHANGED webhook event. Configure webhooks in Dashboard > Developers > Webhooks and handle the event in your backend: 
{
  "type": "PAYMENT_STATE_CHANGED",
  "data": {
    "payment_id": "pay_abc123",
    "status": "SUCCEEDED",
    "payment_method_type": "PIX"
  }
}
Do not poll GET /v1/payments/{id} repeatedly for PIX status. Use webhooks — they are faster and do not count against your rate limit.

​
Sandbox behavior

In the Yuno sandbox environment, all PIX payments automatically transition to SUCCEEDED a few seconds after creation. No real QR scan is required. This lets you test your webhook handling and status updates end-to-end without a real bank account.

​
Document type reference

Document typeWhoFormatDigits
CPFIndividual (Pessoa Física)11 numeric digits, no formatting12345678901
CNPJBusiness (Pessoa Jurídica)14 numeric digits, no formatting12345678000195
Send digits only — no dots, dashes, or slashes.