> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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](/baas/guias/receber/qr-code-dinamico), 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

```bash
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

| Campo              | Tipo    | Obrigatório | Descrição                                                                                                                   |
| ------------------ | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `pixKey`           | string  | Sim         | Chave PIX da conta recebedora (deve estar cadastrada)                                                                       |
| `value`            | number  | Sim         | Valor original da cobrança em BRL, maior que zero, no máximo 2 casas decimais                                               |
| `dueDate`          | date    | Sim         | Dia do vencimento, `YYYY-MM-DD`, no horário de Brasília. Não pode estar no passado                                          |
| `daysAfterDueDate` | integer | Não         | Por quantos dias depois do vencimento o QR ainda aceita pagamento. Padrão `0`                                               |
| `debtor.name`      | string  | Sim         | Nome do devedor                                                                                                             |
| `debtor.document`  | string  | Sim         | CPF (11 dígitos) ou CNPJ (14 dígitos) do devedor; pontuação é ignorada                                                      |
| `deduction`        | number  | Não         | Abatimento em BRL                                                                                                           |
| `discount`         | number  | Não         | Desconto em BRL para pagamento até o vencimento                                                                             |
| `interest`         | number  | Não         | Juros em BRL para pagamento depois do vencimento                                                                            |
| `penalty`          | number  | Não         | Multa em BRL para pagamento depois do vencimento                                                                            |
| `finalValue`       | number  | Não         | Valor a pagar até o vencimento. Se omitido, é `value − deduction − discount`                                                |
| `receiverName`     | string  | Não         | Nome do recebedor exibido ao pagador. Se omitido, é o titular da conta                                                      |
| `identifier`       | string  | Recomendado | Identificador único da cobrança (máximo 38 caracteres, charset `[A-Za-z0-9._-]`). Se omitido, a API gera um UUID sem hifens |
| `message`          | string  | Não         | Mensagem 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)

```json
{
  "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"
}
```

| Campo        | Descrição                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `emv`        | Código PIX Copia e Cola. Renderize como QR                                                               |
| `type`       | Sempre `due-date`                                                                                        |
| `expiresAt`  | Último instante em que o QR aceita pagamento (fim do dia `dueDate + daysAfterDueDate`, Brasília), em UTC |
| `finalValue` | Valor a pagar até o vencimento                                                                           |
| `debtor`     | Devedor 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`:

```bash
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](/baas/guias/receber/qr-code-dinamico#status-possíveis);
`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.

```json
{
  "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"
    }
  }
}
```

> **Tip**
>
> 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

| `errorCode`          | HTTP | Causa                                                                                                                                               | Solução                                                                      |
| -------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `missing_field`      | 400  | `pixKey`, `dueDate`, `debtor.name`, `debtor.document` ou o recebedor ausente                                                                        | Envie os campos obrigatórios                                                 |
| `invalid_document`   | 400  | `debtor.document` sem 11 nem 14 dígitos                                                                                                             | Envie um CPF ou CNPJ válido                                                  |
| `invalid_field`      | 400  | Valor negativo ou com mais de 2 casas, `deduction + discount ≥ value`, vencimento no passado ou além de 365 dias, `message` acima de 140 caracteres | Ajuste os termos                                                             |
| `invalid_identifier` | 400  | `identifier` fora do charset ou acima de 38 caracteres                                                                                              | Ajuste o identificador                                                       |
| `invalid_payload`    | 400  | JSON malformado                                                                                                                                     | Corrija o corpo da requisição                                                |
| `feature_disabled`   | 403  | Produto não habilitado no tenant                                                                                                                    | Peça a ativação à CorpX                                                      |
| `policy_denied`      | 422  | Uma regra de política de QR dinâmico recusou a emissão                                                                                              | Veja `violations` — [Políticas e Regras](/baas/guias/autenticacao/politicas) |

## Próximos Passos

* [Pix Location](/baas/guias/receber/pix-location) - QR impresso antes de saber o valor
* [Webhooks](/baas/guias/conta/webhooks) - Configurar notificações
* [Guia de Devolução](/baas/guias/pagar/devolucao) - Devolver pagamentos recebidos