Visão geral
O cash-out por QR Code processa um pagamento a partir de uma string EMV (pix copia e cola) — o código que começa com 000201.... O ciclo de vida e os webhooks são idênticos ao cash-out por chave; a diferença está no payload de criação.
Use este fluxo quando:
- O destinatário fornece um QR Code estático ou dinâmico.
- Você precisa pagar uma cobrança Pix emitida por terceiros.
- O valor já está codificado na string EMV.
Criar o pagamento
curl -X POST https://api.clearpago.com.br/api/pix/cash-out-qrcode \
-H "Authorization: Bearer <seu_api_token>" \
-H "Content-Type: application/json" \
-H "X-Correlation-ID: req-qrpay-001" \
-d '{
"value": 99.90,
"externalId": "pagamento-qr-456",
"qrCode": "00020101021226870014br.gov.bcb.pix2565...",
"description": "Pagamento via QR Code",
"name": "Loja XYZ",
"document": "00.000.000/0001-00"
}'
201:
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"status": "CREATED",
"externalId": "pagamento-qr-456"
}
Campos
| Campo | Obrigatório | Notas |
|---|
value | Sim | Valor em BRL a pagar. Deve ser consistente com o QR. |
externalId | Sim | Único por operação. 409 em duplicata. |
qrCode | Sim | String EMV completa (pix copia e cola). |
description | Não | Descrição interna da operação. |
name | Não | Nome do beneficiário para referência. |
document | Não | CPF/CNPJ do beneficiário. |
Atenção ao campo value: O valor informado deve ser coerente com o valor codificado no QR Code. QR Codes com valor fixo não permitem alteração. TODO: confirmar validação de consistência de valor com a spec.
Diferenças em relação ao cash-out por chave
| Aspecto | Cash-out por chave | Cash-out por QR Code |
|---|
| Rota | POST /api/pix/cash-out | POST /api/pix/cash-out-qrcode |
| Estrutura do corpo | transaction + recipient aninhados | campos na raiz |
| Endereçamento | pixKey + pixKeyType | qrCode (string EMV) |
| Ciclo de vida | Idêntico | Idêntico |
| Webhooks | pix_cash_out, pix_cash_out_reversal | pix_cash_out, pix_cash_out_reversal |
Ciclo de vida e webhooks
O ciclo de vida é o mesmo do cash-out por chave:
201 com estado inicial (CREATED, RESERVED, etc.).- Despacho ao BaaS.
- Webhook
pix_cash_out com CONFIRMED ou FAILED.
- Em caso de reversão posterior: webhook
pix_cash_out_reversal com REVERSED.
Consulte Enviar Pix por chave para detalhes do pipeline, estados ambíguos e reconciliação.
Cuidados práticos
- QR expirado: se o QR Code já expirou, a criação falhará com
4xx ou o BaaS rejeitará. Obtenha uma nova string EMV junto ao emissor.
- QR já pago: QR Codes dinâmicos de uso único são rejeitados se já foram liquidados.
- Não reutilize
externalId: cada tentativa de pagamento deve usar um externalId distinto.
Referências
