PIX

Accept instant PIX payments in Brazil

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

Node.js

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: '[e-mail]',
      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:

1. QR Code Image: Render the base64 image for scanning with a banking app
2. 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:

1. Create a PIX payment using the sandbox API endpoint (api-sandbox.y.uno)
2. The response returns a test QR code and Copia e Cola code
3. Use the Yuno Dashboard sandbox tools to simulate payment completion
4. 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.