PIX - Yuno API Documentation

Overview

PIX is Brazil’s instant payment system, created and regulated by the Central Bank of Brazil (BACEN). It enables real-time fund transfers 24/7, including weekends and holidays. PIX has become the most popular payment method in Brazil, processing billions of transactions monthly. Key characteristics:

Instant settlement: Funds arrive in seconds, not days
24/7 availability: Works around the clock, every day
Low cost: Significantly cheaper than card payments for merchants
QR code based: Customers scan a QR code or copy-paste a code in their banking app

Requirements

Field	Value	Description
`country`	`BR`	Brazil only
`amount.currency`	`BRL`	Brazilian Real only
`customer.document.document_type`	`CPF` or `CNPJ`	Required by BACEN regulation
`customer.document.document_number`	11 digits (CPF) or 14 digits (CNPJ)	Digits only, no formatting

PIX requires a valid customer tax identification number. CPF (Cadastro de Pessoas Fisicas) is for individuals (11 digits). CNPJ (Cadastro Nacional da Pessoa Juridica) is for businesses (14 digits). Invalid documents will be rejected by the provider.

Creating a PIX Payment

const response = await fetch('https://api-sandbox.y.uno/v1/payments', {
  method: 'POST',
  headers: {
    'public-api-key': process.env.YUNO_PUBLIC_KEY,
    'private-secret-key': process.env.YUNO_PRIVATE_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    checkout_session: 'session-id',
    payment_method: { type: 'PIX' },
    amount: { currency: 'BRL', value: 150.00 },
    country: 'BR',
    customer: {
      email: 'cliente@example.com',
      first_name: 'Maria',
      last_name: 'Silva',
      document: {
        document_type: 'CPF',
        document_number: '12345678901',
      },
    },
    description: 'Pedido #456',
  }),
});
const payment = await response.json();

Handling the Response

A successful PIX payment creation returns status PENDING with QR code data:

{
  "id": "pay_pix_abc123",
  "status": "PENDING",
  "amount": { "currency": "BRL", "value": 150.00 },
  "payment_method": {
    "type": "PIX",
    "pix": {
      "qr_code": "data:image/png;base64,iVBORw0KGgo...",
      "qr_code_url": "00020126580014br.gov.bcb.pix0136..."
    }
  },
  "expiration_date": "2026-03-01T10:30:00Z",
  "created_at": "2026-03-01T10:00:00Z"
}

Field	Description
`pix.qr_code`	Base64-encoded PNG image of the QR code
`pix.qr_code_url`	PIX Copia e Cola string (copy-paste code)
`expiration_date`	When the PIX code expires

Displaying the QR Code

Present both options to the customer:

QR Code Image: Render the base64 image for scanning with a banking app
Copia e Cola: Show the qr_code_url string with a copy button for pasting into a banking app

<!-- QR Code display -->
<img src="{payment.payment_method.pix.qr_code}" alt="PIX QR Code" />

<!-- Copy-paste code -->
<div>
  <p>Or copy and paste this code in your banking app:</p>
  <input readonly value="{payment.payment_method.pix.qr_code_url}" />
  <button onclick="copyToClipboard()">Copy</button>
</div>

Show a countdown timer alongside the QR code so the customer knows how long they have to complete the payment.

PIX Expiration

PIX codes have a configurable expiration period. The default is 30 minutes from creation. You can set a custom expiration using the expiration_date field in the payment request:

{
  "payment_method": { "type": "PIX" },
  "expiration_date": "2026-03-01T12:00:00Z"
}

After expiration:

The QR code and Copia e Cola code become invalid
The payment status transitions to EXPIRED
A payment.expired webhook event is sent

PIX Refunds

PIX supports instant full and partial refunds. Refunds are processed in real-time and the customer receives funds immediately.

curl -X POST https://api-sandbox.y.uno/v1/payments/{payment_id}/refund \
  -H "public-api-key: your-public-api-key" \
  -H "private-secret-key: your-private-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": {"currency": "BRL", "value": 50.00}}'

PIX refunds can be issued up to 90 days after the original payment, per BACEN regulation. The refund amount cannot exceed the original payment amount.

PIX Copia e Cola

PIX Copia e Cola is the text-based representation of the PIX payment code. Customers copy this string and paste it into their banking app instead of scanning a QR code. This is especially useful for:

Desktop/laptop purchases where the customer pays from a mobile device
Accessibility scenarios
Situations where QR code scanning is not available

The Copia e Cola string is returned in payment_method.pix.qr_code_url and follows the EMV standard format defined by BACEN.

Webhook Events

Subscribe to these webhook events for PIX payment status updates:

Event	Description	When
`payment.pending`	PIX code generated	Payment created, waiting for customer
`payment.succeeded`	Customer completed PIX payment	Funds received (typically seconds)
`payment.expired`	PIX code expired	Customer did not pay before expiration
`payment.refunded`	Refund processed	Refund completed (instant)

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_pix_abc123",
    "status": "SUCCEEDED",
    "amount": { "currency": "BRL", "value": 150.00 },
    "payment_method": { "type": "PIX" },
    "paid_at": "2026-03-01T10:02:30Z"
  }
}

Always verify payment status server-side via webhooks before fulfilling orders. Do not rely on client-side callbacks alone, as PIX payments are asynchronous.

Testing PIX in Sandbox

In the sandbox environment, PIX payments can be tested without real funds:

Create a PIX payment using the sandbox API endpoint (api-sandbox.y.uno)
The response returns a test QR code and Copia e Cola code
Use the Yuno Dashboard sandbox tools to simulate payment completion
Verify your webhook handler receives the payment.succeeded event

Sandbox PIX payments are automatically approved after a short delay (typically 5-10 seconds) or can be manually approved via the Dashboard. Check Dashboard > Sandbox > Payments to manage test transactions.

Common Issues

Issue	Cause	Resolution
400: `customer.document is required`	Missing CPF/CNPJ	Add `customer.document` with valid `document_type` and `document_number`
400: `invalid document_number`	Wrong format or invalid check digits	Validate CPF (11 digits) or CNPJ (14 digits) before submission
403: `payment method not available`	PIX not enabled for merchant	Enable PIX in Dashboard > Settings > Payment Methods > Brazil
`EXPIRED` status	Customer did not pay in time	Create a new payment with a fresh PIX code

Response Handling

Synchronous Response

PIX payments return PENDING status with QR code data:

{
  "id": "pay_abc123",
  "status": "PENDING",
  "payment_method": {
    "type": "PIX",
    "pix": {
      "qr_code": "base64-encoded-qr-image",
      "qr_code_url": "00020126580014br.gov.bcb.pix..."
    }
  },
  "expiration": "2026-03-10T12:00:00Z"
}

Display either the QR code image (decode base64) or the qr_code_url (copy-paste code) to the customer.

Webhook Events

Event	Status	Action
`payment.succeeded`	`SUCCEEDED`	Customer paid. Fulfill the order
`payment.expired`	`EXPIRED`	QR code expired. Notify customer or create new payment
`payment.refunded`	`REFUNDED`	Refund processed. Update order status

PIX payments typically expire in 30 minutes to 24 hours depending on your configuration. Set appropriate expiration times based on your use case.

​Overview

​Requirements

​Creating a PIX Payment

​Handling the Response

​Displaying the QR Code

​PIX Expiration

​PIX Refunds

​PIX Copia e Cola

​Webhook Events

​Testing PIX in Sandbox

​Common Issues

​Response Handling

​Synchronous Response

​Webhook Events

Overview

Requirements

Creating a PIX Payment

Handling the Response

Displaying the QR Code

PIX Expiration

PIX Refunds

PIX Copia e Cola

Webhook Events

Testing PIX in Sandbox

Common Issues

Response Handling

Synchronous Response

Webhook Events