Ir al contenido

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.

{
"amount": 10000,
"amountFormat": "cents",
"amountType": "fixed",
"expirationInSeconds": 900,
"description": "Pedido #1234",
"payerName": "João Silva",
"payerTaxId": "123.456.789-09",
"txIdSource": "ORD-20261005-0000000000001"
}
CampoTipoRequeridoDescripción
amountnumber✅> 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
expirationInSecondsinteger❌Por defecto 900 (15 min). Si viene, entero > 0
descriptionstring❌Visible al pagador
payerNamestring❌Nombre del pagador
payerTaxIdstring✅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
txIdSourcestring❌Tu referencia, 26 a 35 caracteres (si no → 400). Vuelve en los webhooks como reference
sandboxSettlestring❌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".

{
"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
}
}
CampoDescripción
txIdID de la transacción (32 caracteres hexadecimales) — guárdalo para consultar el estado
qrCodePayload del QR (renderízalo con cualquier librería QR)
copiaEColaTexto “copia e cola” para pegar en la app del banco
expiresAtVencimiento del QR
estimatedFees.feeClientComisión estimada en centavos
estimatedFees.netAmountMonto que recibirás en tu saldo (centavos)
estimatedFees.finalfalse = tu tarifa tiene tramos por número de transacciones; la comisión definitiva se fija al liquidar (la del webhook es la que vale)

GET /v1/br/payin/pix/{txId}

ParámetroDescripción
txIdID 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 txId de otro aliado responde 404.