Guia de QR Code com Vencimento
Este guia explica como emitir cobranças PIX com data de vencimento — a cobrança “CobV” do Pix, com juros, multa, desconto e abatimento.
Visão Geral
O QR Code com vencimento é uma cobrança única, como o QR Code Dinâmico, mas com regras de boleto: tem um dia de vencimento, um devedor identificado e encargos que mudam o valor conforme a data do pagamento. É indicado para:
- Mensalidades e faturas - Cobranças com data certa para pagar
- Substituição de boleto - Mesmo vencimento e encargos, liquidação Pix
- Carnês - Uma cobrança por parcela, cada uma com o seu vencimento
O QR Code com vencimento precisa estar habilitado no seu tenant. Sem a
habilitação, a criação responde 403 feature_disabled. Peça a ativação ao
time da CorpX.
Fluxo de Integração
Passo 1: Emitir a cobrança
Request
Parâmetros do Body
O QR aceita pagamento até 23:59:59 (Brasília) do dia dueDate + daysAfterDueDate.
Esse dia não pode passar de 365 dias a partir de hoje. deduction + discount
precisa ser menor que value.
Resposta de Sucesso (201 Created)
Passo 2: Consultar e cancelar
A consulta e o cancelamento são os mesmos do QR dinâmico, pelo identifier:
O lookup devolve type: "due-date" e os mesmos campos de vencimento da
resposta de criação (dueDate, daysAfterDueDate, encargos, finalValue,
debtor, receiverName). Os status são os do
QR dinâmico;
EXPIRED significa que passou o último dia de pagamento sem pagamento.
Passo 3: Receber o webhook
O pagamento chega como qrcode.paid, com data.type = "due-date". O
data.amount é o valor efetivamente pago, que pode diferir de value:
desconto até o vencimento, juros e multa depois dele.
Concilie pelo identifier e compare data.amount com o valor que você espera
para a data do pagamento. Sem pagamento até expiresAt, chega qrcode.expired.
Permissões
A rota usa o mesmo escopo do QR dinâmico, qrcode.manage (ou api2/write).
No painel do integrador, a emissão exige a permissão Emitir QR code com
vencimento e Pix Location.
Erros Comuns
Próximos Passos
- Pix Location - QR impresso antes de saber o valor
- Webhooks - Configurar notificações
- Guia de Devolução - Devolver pagamentos recebidos