PIX

Criar uma cobrança

curl -X POST https://api.gateway.example/v1/pix/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "payerDocument": "12345678900"
  }'

const charge = await gateway.pix.create({
  amountInCents: 5000,
  payerDocument: '12345678900',
});

{
  "id": "51119cde-...",
  "object": "pix_charge",
  "status": "pending_payment",
  "amountInCents": 5000,
  "currency": "BRL",
  "txid": "mock_pix_...",
  "qrCode": "00020126...",
  "copyPaste": "00020126...5303986540...",
  "expiration": "2026-08-25T20:44:15.906Z"
}

Renderize qrCode como um QR Code (qualquer lib de QR do seu frontend) e ofereça copyPaste como texto copiável ("Pix Copia e Cola").

Consultar

GET /v1/pix/charges/:id sempre reconsulta o status ao vivo — qrCode/copyPaste voltam de novo na resposta (não são descartados depois da criação):

const charge = await gateway.pix.get('pay_123');

Saber quando foi pago

Uma cobrança PIX é assíncrona por natureza — o jeito confiável de saber que foi paga é o webhook pix.paid (ou payment.paid), não polling. Ver Webhooks.

Estornar

await gateway.pix.refund('pay_123');

Só funciona numa cobrança já paga; estorno de PIX é sempre total nesta entrega.

Expiração

Toda cobrança expira (expiration, ISO 8601) — depois disso ela não pode mais ser paga. O prazo default é curto (pensado pra checkout); se seu caso de uso precisa de uma cobrança de longa duração (cobrança com vencimento), fale com quem administra sua instância.