Cobro Pix
POST /v1/br/payin/pix/instant
Genera un cobro Pix: devuelve el payload del QR y el texto “copia e cola” para que el pagador pague desde la app de su banco. El desenlace llega por webhook.
Request body
Sección titulada «Request body»{ "amount": 10000, "amountFormat": "cents", "amountType": "fixed", "expirationInSeconds": 900, "description": "Pedido #1234", "payerName": "João Silva", "payerTaxId": "123.456.789-09", "txIdSource": "ORD-20261005-0000000000001"}| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
amount | number | ✅ | > 0. Con cents: entero en centavos. Con brl: reales con hasta 2 decimales (12.34 → 1234 centavos) |
amountFormat | "cents" | "brl" | ✅ | Formato del monto enviado. Otro valor → 400 |
amountType | "fixed" | "custom" | ✅ | fixed = monto exacto. custom = el pagador puede cambiar el monto en su banco |
expirationInSeconds | integer | ❌ | Por defecto 900 (15 min). Si viene, entero > 0 |
description | string | ❌ | Visible al pagador |
payerName | string | ❌ | Nombre del pagador |
payerTaxId | string | ✅ | CPF del pagador (11 dígitos, con o sin máscara). Se valida el dígito verificador; CNPJ no se acepta. Si falta o es inválido → 400 VALIDATION_ERROR |
txIdSource | string | ❌ | Tu referencia, 26 a 35 caracteres (si no → 400). Vuelve en los webhooks como reference |
sandboxSettle | string | ❌ | Solo sandbox. Ver Sandbox |
El monto además se valida contra los mínimos y máximos de tu tarifa → 422 PROVIDER_REJECTED "El monto está fuera del rango permitido para este medio de pago".
Response 201 Created
Sección titulada «Response 201 Created»{ "txId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "txIdSource": "ORD-20261005-0000000000001", "status": "PENDING", "amount": 10000, "currency": "BRL", "qrCode": "00020126580014br.gov.bcb.pix...", "copiaECola": "00020126580014br.gov.bcb.pix...", "expiresAt": "2026-10-05T15:15:00.000Z", "estimatedFees": { "feeClient": 300, "feeBase": 300, "iva": 0, "netAmount": 9700, "currency": "BRL", "final": true }}| Campo | Descripción |
|---|---|
txId | ID de la transacción (32 caracteres hexadecimales) — guárdalo para consultar el estado |
qrCode | Payload del QR (renderízalo con cualquier librería QR) |
copiaECola | Texto “copia e cola” para pegar en la app del banco |
expiresAt | Vencimiento del QR |
estimatedFees.feeClient | Comisión estimada en centavos |
estimatedFees.netAmount | Monto que recibirás en tu saldo (centavos) |
estimatedFees.final | false = tu tarifa tiene tramos por número de transacciones; la comisión definitiva se fija al liquidar (la del webhook es la que vale) |
Consultar estado
Sección titulada «Consultar estado»GET /v1/br/payin/pix/{txId}
| Parámetro | Descripción |
|---|---|
txId | ID devuelto al crear el cobro |
{ "txId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "txIdOrigen": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "txIdSource": "ORD-20261005-0000000000001", "status": "COMPLETED", "amount": 10000, "currency": "BRL", "description": "Pedido #1234", "feeClient": 300, "netAmount": 9700, "e2eId": "E12345678202610051400000000001", "createdAt": "2026-10-05T15:00:00.000Z", "updatedAt": "2026-10-05T15:02:30.000Z"}Estados: PENDING, COMPLETED, FAILED, REVERSED. Ver Estados.
- Si el cobro lleva más de 5 minutos en
PENDING, la consulta pregunta en ese momento a la red y devuelve el estado actualizado (y dispara el webhook si cambió). - Un
txIdde otro aliado responde404.