Enviar pago PIX mediante código QR (Cash-Out QR Code)
POST /api/pix/cash-out-qrcode
POST https://<api-host>/api/pix/cash-out-qrcodeRequiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.
Envía un pago PIX a partir de un código QR escaneado o copiado (copiar y pegar). El código QR debe seguir el estándar EMV PIX del Banco Central.
Autenticación
Requiere un Bearer token en el header Authorization.
Cuerpo de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
value | number | Sí | Monto del pago en BRL (hasta 2 decimales). Debe coincidir con el monto incluido en el código QR, cuando esté presente |
qrCode | string | Sí | Contenido del código QR PIX (cadena EMV). Mín 50, máx 500 caracteres. Debe comenzar con 000201 |
externalId | string | Sí | Identificador externo único por cuenta (máx 36 caracteres) |
description | string | No | Descripción opcional del pago (máx 140 caracteres) |
name | string | No | Nombre del destinatario, informativo (máx 100 caracteres; puede estar incluido en el código QR) |
document | string | No | CPF o CNPJ válido del destinatario, solo números (máx 14 caracteres; puede estar incluido en el código QR) |
{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
}Ejemplos de Código
curl -X POST "https://<api-host>/api/pix/cash-out-qrcode" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/cash-out-qrcode',
{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);Respuesta (201)
| Campo | Tipo | Descripción |
|---|---|---|
transactionId | string | Identificador interno de la transacción generada |
externalId | string | Identificador externo proporcionado en la solicitud |
status | string | Estado actual de la transacción (PENDING, CONFIRMED, ERROR) |
generateTime | string | Fecha/hora de generación de la transacción (ISO 8601) |
{
"transactionId": "456",
"externalId": "QRPAY-987654-20240119",
"status": "PENDING",
"generateTime": "2024-01-19T14:30:00.000Z"
}Errores
| Estado | Descripción |
|---|---|
| 400 | Datos inválidos, código QR inválido, monto no coincide o saldo insuficiente |
| 401 | Token faltante o inválido |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — externalId ya utilizado en esta cuenta |
| 422 | Rechazo declarado por el proveedor de pago. Con QRCODE_ALREADY_PAID o QRCODE_NOT_AVAILABLE el código QR está consumido y el estado es FINAL: no reintentar. Sin uno de esos códigos, confirme mediante Get Transaction antes de tratarlo como definitivo |
| 500 | Error interno o indeterminado — el estado de la transacción es desconocido. No lo trate como fallo definitivo: consulte Get Transaction (en fallos internos el webhook puede no llegar) |