Realizar pagamento PIX via QR Code (Cash-Out QR Code)
POST /api/pix/cash-out-qrcode
POST https://<api-host>/api/pix/cash-out-qrcodeRequer um Bearer token no header Authorization. Veja Gerar Token para obter um.
Envia um pagamento PIX a partir de um QR Code escaneado ou copiado (copia-e-cola). O QR Code deve seguir o padrão EMV PIX do Banco Central.
Autenticação
Requer token Bearer no header Authorization.
Request Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
value | number | Sim | Valor do pagamento em reais (até 2 casas decimais). Deve corresponder ao valor embutido no QR Code, quando presente |
qrCode | string | Sim | Conteúdo do QR Code PIX (string EMV). Min 50, max 500 caracteres. Deve iniciar com 000201 |
externalId | string | Sim | Identificador externo único por conta (máx 36 caracteres) |
description | string | Não | Descrição opcional do pagamento (máx 140 caracteres) |
name | string | Não | Nome do destinatário, informativo (máx 100 caracteres; pode estar embutido no QR Code) |
document | string | Não | CPF ou CNPJ válido do destinatário, apenas números (máx 14 caracteres; pode estar embutido no QR Code) |
{
"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"
}Exemplos 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);Response (201)
| Campo | Tipo | Descrição |
|---|---|---|
transactionId | string | Identificador interno da transação gerada |
externalId | string | Identificador externo informado na requisição |
status | string | Status atual da transação (PENDING, CONFIRMED, ERROR) |
generateTime | string | Data/hora de geração da transação (ISO 8601) |
{
"transactionId": "456",
"externalId": "QRPAY-987654-20240119",
"status": "PENDING",
"generateTime": "2024-01-19T14:30:00.000Z"
}Erros
| Status | Descrição |
|---|---|
| 400 | Dados inválidos, QR Code inválido, valor divergente ou saldo insuficiente |
| 401 | Token não fornecido ou inválido |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — externalId já utilizado nesta conta |
| 422 | Rejeição declarada pelo provedor de pagamento. Com QRCODE_ALREADY_PAID ou QRCODE_NOT_AVAILABLE o QR Code está consumido e o estado é FINAL: não re-tentar. Sem um desses códigos, confirme pelo Get Transaction antes de tratar como definitivo |
| 500 | Erro interno ou indeterminado — o estado da transação é desconhecido. Não trate como falha definitiva: consulte o Get Transaction (para falhas internas o webhook pode não vir) |