> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# QR Codes

> Como o Plugin Pix Indireto (BTG) gera e decodifica QR Codes Pix — BR Codes estáticos, cobranças imediatas (COB), cobranças com vencimento (COBV) e o decodificador universal.

O Plugin Pix Indireto (BTG) gera e gerencia QR Codes Pix (BR Codes) para que seus clientes possam receber pagamentos. Ele suporta quatro domínios de QR Code: BR Codes **estáticos**, cobranças **imediatas** (cobrança imediata / COB), cobranças **com vencimento** (cobrança com vencimento / COBV) e um **decodificador** universal para iniciação de pagamento.

Todos os QR Codes seguem a especificação EMV QCO e incorporam a chave Pix do recebedor. Antes de criar um QR Code, a **chave do recebedor já deve existir no DICT e pertencer à conta solicitante** (identificada pelo cabeçalho `X-Account-Id`). Consulte o [guia de DICT](/pt/midaz/plugins/pix/indirect/indirect-pix-dict) para o registro de chaves.

# Escolhendo um tipo de QR Code

***

| Tipo                      | Características                                                                                       | Indicado para                                                              |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Estático**              | Reutilizável (múltiplos pagamentos) · valor opcional (fixo ou informado pelo pagador) · sem expiração | Telas de POS, material impresso, doações, e-commerce com valores variáveis |
| **Imediata (COB)**        | Pagamento único · valor obrigatório · expiração baseada em segundos                                   | Checkout, faturamento, compras únicas                                      |
| **Com vencimento (COBV)** | Pagamento único · valor + encargos · data de vencimento + período de tolerância                       | Contas, parcelamentos, assinaturas, faturamento B2B (semelhante a boleto)  |
| **Decodificar**           | Lê qualquer QR Code escaneado                                                                         | Iniciar um pagamento a partir de um código escaneado                       |

# QR Codes estáticos

***

Os BR Codes estáticos (`/v1/brcode/static`) são **reutilizáveis** — o mesmo código pode ser pago muitas vezes por pagadores diferentes. Eles estão vinculados a uma chave Pix e, opcionalmente, a dados do estabelecimento.

**Valor fixo vs. variável:**

* **Com valor** — o pagador escaneia e confirma um valor predefinido. Útil para itens de preço fixo.
* **Sem valor** — o pagador escaneia e digita o valor manualmente. Útil para doações ou checkout aberto.

Você pode enriquecer o código com dados do estabelecimento (`merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC, 4 dígitos), `merchant.postalCode`) e um `txId` opcional (alfanumérico, ≤ 25 caracteres) para conciliação. Se os dados do estabelecimento forem omitidos, o plugin pode enriquecê-los a partir dos dados do titular no CRM.

```json theme={null}
POST /v1/brcode/static
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "receiverKey": "+5511999999999",
  "amount": "100.00",
  "description": "Payment for order #12345",
  "txId": "TX123ABC",
  "merchant": { "name": "Loja ABC", "city": "São Paulo", "categoryCode": "5411" }
}
→ 201 Created  { "id": "...", "emv": "00020126580014br.gov.bcb.pix...", "status": "ACTIVE" }
```

Passe `include_base64=true` para também receber um PNG do QR Code codificado em Base64. O plugin valida a propriedade da chave (retorna `PIX-0092` se a chave não pertencer à conta, `PIX-0093` se estiver inativa).

**Referência:** [Criar um QR code estático](/pt/reference/midaz/plugins/indirect-pix/create-a-static-qr-code) · [Listar](/pt/reference/midaz/plugins/indirect-pix/list-static-qr-codes) · [Recuperar](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-static-qr-code)

# Cobranças imediatas (COB)

***

As cobranças imediatas (`/v1/collections/immediate`) são QR Codes **dinâmicos e de uso único** para um valor específico com uma janela de validade curta. Cada uma é identificada de forma única por um `txId` obrigatório e só pode ser paga uma vez.

**Campos obrigatórios:** `amount`, `expirationInSeconds` (recomendado ≤ 3600), `receiverKey` e `txId`. Um `debtor` opcional (nome + documento) restringe quem pode pagar — quando definido, somente o CPF/CNPJ especificado pode liquidar a cobrança.

**Ciclo de vida:**

| Status                | Significado                              |
| --------------------- | ---------------------------------------- |
| `ACTIVE`              | Criada e disponível para pagamento       |
| `CONCLUDED`           | Pagamento recebido com sucesso           |
| `REMOVED_BY_RECEIVER` | Cancelada pelo lojista                   |
| `REMOVED_BY_PSP`      | Cancelada pelo PSP (sistema ou política) |

Quando criada, o plugin agenda um **job de expiração**; após decorrido `expirationInSeconds`, a cobrança não pode mais ser paga. Enquanto `ACTIVE`, a cobrança pode ser atualizada (`PATCH`) ou excluída (`DELETE`) — uma cobrança no status `CONCLUDED` não pode ser excluída (`PIX-0104`).

**Confirmação de pagamento:** quando um Pix recebido liquida a cobrança, o plugin a transiciona para `CONCLUDED` e emite um **webhook** para que seu sistema seja notificado em tempo real. Consulte o [guia de Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) e o [guia de Cobranças](/pt/midaz/plugins/pix/indirect/indirect-pix-collections) para o fluxo de pagamento completo.

**Referência:** [Criar uma cobrança imediata](/pt/reference/midaz/plugins/indirect-pix/create-an-immediate-charge) · [Listar](/pt/reference/midaz/plugins/indirect-pix/list-immediate-charges) · [Recuperar](/pt/reference/midaz/plugins/indirect-pix/retrieve-immediate-charge-details) · [Atualizar](/pt/reference/midaz/plugins/indirect-pix/update-an-immediate-charge) · [Excluir](/pt/reference/midaz/plugins/indirect-pix/delete-an-immediate-charge)

# Cobranças com vencimento (COBV)

***

As cobranças com vencimento (`/v1/collections/duedate`) são QR Codes dinâmicos para **faturamento com data de vencimento**, análogos a um boleto. Elas suportam regras de valor complexas e exigem dados completos do pagador e do recebedor.

**Campos principais:** `dueDate`, `validAfterDue` (dias em que a cobrança permanece pagável após o vencimento — padrão 30), um `debtor` obrigatório (nome + CPF/CNPJ, além de e-mail/endereço/cidade/estado/CEP opcionais) e um objeto `amount` com componentes de encargo opcionais:

| Componente  | Tipos                                                              | Aplica-se                            |
| ----------- | ------------------------------------------------------------------ | ------------------------------------ |
| `fine`      | `FIXED`, `PERCENTAGE`                                              | Multa por pagamento em atraso        |
| `interest`  | `DAILY_AMOUNT`, `DAILY_PERCENTAGE`, `MONTHLY_PERCENTAGE`           | Acumula após o vencimento            |
| `discount`  | `FIXED`, `PERCENTAGE`, `FIXED_UP_TO_DATE`, `PERCENTAGE_UP_TO_DATE` | Recompensa pelo pagamento antecipado |
| `abatement` | `FIXED`                                                            | Crédito/redução sobre o valor        |

O **momento do pagamento** determina o valor final: antes do vencimento o pagador recebe qualquer desconto aplicável; na data de vencimento aplica-se o valor original; após o vencimento são adicionados multas e juros (descontado qualquer abatimento). Os tipos de desconto `UP_TO_DATE` exigem uma `date` que deve ser anterior à `dueDate`.

O plugin valida o formato do documento do pagador (`PIX-0073`) e agenda a expiração em `dueDate + validAfterDue`.

**Referência:** [Criar uma cobrança com vencimento](/pt/reference/midaz/plugins/indirect-pix/create-a-dynamic-charge-with-due-date) · [Listar](/pt/reference/midaz/plugins/indirect-pix/list-dynamic-charges-with-due-date) · [Recuperar](/pt/reference/midaz/plugins/indirect-pix/retrieve-dynamic-charge-with-due-date-details) · [Atualizar](/pt/reference/midaz/plugins/indirect-pix/update-a-dynamic-charge-with-due-date)

# Decodificando QR Codes

***

O decodificador (`POST /v1/qrcodes/decode`) analisa qualquer QR Code Pix escaneado e retorna os dados de pagamento nele incorporados. Use-o em **fluxos de iniciação de pagamento** — quando um cliente escaneia um QR Code e você precisa do recebedor, do valor e dos detalhes de cobrança antes de confirmar o pagamento.

O plugin detecta automaticamente o tipo de QR Code e retorna uma resposta tipada:

* **STATIC** — chave do recebedor, valor/descrição opcionais, dados do estabelecimento, `txId`.
* **IMMEDIATE (COB)** — todos os campos do estático, mais valor obrigatório, expiração, status e número de revisão.
* **DUE\_DATE (COBV)** — todos os campos do imediato, mais data de vencimento, `validAfterDue`, pagador, recebedor e a estrutura completa de multa/juros/desconto.

Para códigos dinâmicos, o plugin resolve o payload dinâmico do BTG antes de retornar, de modo que a resposta reflete o estado atual da cobrança.

```json theme={null}
POST /v1/qrcodes/decode
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "emv": "00020126580014br.gov.bcb.pix..." }
→ 200 OK  { "type": "IMMEDIATE", "amount": "100.00", "receiverKey": "...", "status": "ACTIVE" }
```

**Referência:** [Decodificar um QR code Pix](/pt/reference/midaz/plugins/indirect-pix/decode-a-pix-qr-code)

# Próximos passos

***

* [Cobranças](/pt/midaz/plugins/pix/indirect/indirect-pix-collections) — Ciclo de vida da cobrança, vínculo de pagamento e eventos de webhook
* [DICT](/pt/midaz/plugins/pix/indirect/indirect-pix-dict) — Registrando as chaves Pix em que seus QR Codes recebem
* [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Notificações de pagamento e status