Skip to navigation

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
Produto habilitado por tenant

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

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Emitir │ │ Devedor │ │ Webhook │
│ Cobrança │ ───► │ Paga QR │ ───► │ qrcode.paid │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
Retorna EMV amount = valor pago
(com encargos)

Passo 1: Emitir a cobrança

Request

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/due-date" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fatura-2026-12" \
-d '{
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"identifier": "fatura-2026-12",
"value": 150.00,
"dueDate": "2026-12-10",
"daysAfterDueDate": 5,
"discount": 10.00,
"interest": 1.50,
"penalty": 3.00,
"debtor": {
"name": "Maria Oliveira",
"document": "98765432100"
},
"message": "Mensalidade de dezembro"
}'

Parâmetros do Body

CampoTipoObrigatórioDescrição
pixKeystringSimChave PIX da conta recebedora (deve estar cadastrada)
valuenumberSimValor original da cobrança em BRL, maior que zero, no máximo 2 casas decimais
dueDatedateSimDia do vencimento, YYYY-MM-DD, no horário de Brasília. Não pode estar no passado
daysAfterDueDateintegerNãoPor quantos dias depois do vencimento o QR ainda aceita pagamento. Padrão 0
debtor.namestringSimNome do devedor
debtor.documentstringSimCPF (11 dígitos) ou CNPJ (14 dígitos) do devedor; pontuação é ignorada
deductionnumberNãoAbatimento em BRL
discountnumberNãoDesconto em BRL para pagamento até o vencimento
interestnumberNãoJuros em BRL para pagamento depois do vencimento
penaltynumberNãoMulta em BRL para pagamento depois do vencimento
finalValuenumberNãoValor a pagar até o vencimento. Se omitido, é value − deduction − discount
receiverNamestringNãoNome do recebedor exibido ao pagador. Se omitido, é o titular da conta
identifierstringRecomendadoIdentificador único da cobrança (máximo 38 caracteres, charset [A-Za-z0-9._-]). Se omitido, a API gera um UUID sem hifens
messagestringNãoMensagem exibida ao pagador (máximo 140 caracteres)
Prazo máximo

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)

{
"txid": "fatura-2026-12",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/fatura-2026-1252040000530398654061505802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
"type": "due-date",
"status": "ACTIVE",
"value": 150.00,
"message": "Mensalidade de dezembro",
"description": "Mensalidade de dezembro",
"identifier": "fatura-2026-12",
"accountId": "{accountId}",
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"allowChange": false,
"expiresAt": "2026-12-16T02:59:59Z",
"dueDate": "2026-12-10",
"daysAfterDueDate": 5,
"deduction": 0,
"discount": 10.00,
"interest": 1.50,
"penalty": 3.00,
"finalValue": 140.00,
"debtor": {
"name": "Maria Oliveira",
"document": "98765432100"
},
"receiverName": "LOJA EXEMPLO"
}
CampoDescrição
emvCódigo PIX Copia e Cola. Renderize como QR
typeSempre due-date
expiresAtÚltimo instante em que o QR aceita pagamento (fim do dia dueDate + daysAfterDueDate, Brasília), em UTC
finalValueValor a pagar até o vencimento
debtorDevedor informado na emissão. Quem efetivamente pagou vem em payer depois do pagamento

Passo 2: Consultar e cancelar

A consulta e o cancelamento são os mesmos do QR dinâmico, pelo identifier:

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/lookup?identifier=fatura-2026-12" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}"
curl -X DELETE "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code?identifier=fatura-2026-12" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}"

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.

{
"id": "qrcode-paid-fatura-2026-12",
"type": "qrcode.paid",
"occurredAt": "2026-12-12T14:03:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-yourcompany",
"accountId": "{accountId}",
"data": {
"qrcodeId": "fatura-2026-12",
"identifier": "fatura-2026-12",
"accountId": "{accountId}",
"tenantId": "tenant-yourcompany",
"type": "due-date",
"amount": 154.50,
"endToEnd": "E0000000020261212140300000",
"transactionId": "171234-pix",
"status": "SUCCESS",
"receivedAt": "2026-12-12T14:03:11.000Z",
"payer": {
"name": "MARIA OLIVEIRA",
"document": "98765432100"
}
}
}

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

errorCodeHTTPCausaSolução
missing_field400pixKey, dueDate, debtor.name, debtor.document ou o recebedor ausenteEnvie os campos obrigatórios
invalid_document400debtor.document sem 11 nem 14 dígitosEnvie um CPF ou CNPJ válido
invalid_field400Valor negativo ou com mais de 2 casas, deduction + discount ≥ value, vencimento no passado ou além de 365 dias, message acima de 140 caracteresAjuste os termos
invalid_identifier400identifier fora do charset ou acima de 38 caracteresAjuste o identificador
invalid_payload400JSON malformadoCorrija o corpo da requisição
feature_disabled403Produto não habilitado no tenantPeça a ativação à CorpX
policy_denied422Uma regra de política de QR dinâmico recusou a emissãoVeja violations — Políticas e Regras

Próximos Passos