> ## 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 > Gere e decodifique QR Codes Pix via BTG: BR Codes estáticos, cobranças imediatas COB e com vencimento COBV, payloads EMV e o decodificador universal de QR Code. O Plugin Pix Indireto (BTG) gera e gerencia QR Codes Pix (BR Codes) para que seus clientes possam receber pagamentos. O plugin aceita quatro tipos de QR Code: BR Codes estáticos, cobranças imediatas (COB), cobranças com vencimento (COBV) e um decodificador para iniciação de pagamento. Todos os QR Codes seguem a especificação EMV QCO e embutem a chave Pix do recebedor. Antes de você criar um QR Code, a chave do recebedor deve existir no DICT. A conta que faz a requisição deve ser dona da chave. Você identifica a conta com o header `X-Account-Id`. Veja o [guia do DICT](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-dict.md) para o cadastro de chaves. # Como escolher o tipo de QR Code *** | Tipo | Características | Melhor para | | - | - | - | | **Estático** | Reutilizável (vários 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 em segundos | Checkout, faturamento, compras avulsas | | **Com vencimento (COBV)** | Pagamento único · valor + encargos · vencimento + carência | Contas, parcelas, assinaturas, faturamento B2B (como um boleto) | | **Decodificação** | 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. Pagadores diferentes podem pagar o mesmo código muitas vezes. Cada código se liga a uma chave Pix e, opcionalmente, a dados do estabelecimento. **Valor fixo ou 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 adicionar dados do estabelecimento ao código: `merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC) e `merchant.postalCode`. Você também pode adicionar um `txId` opcional (alfanumérico, até 25 caracteres) para conciliação. A requisição exige um `clientRequestId`. Se você omitir os dados do estabelecimento, o plugin os preenche a partir dos dados do titular no CRM. ```json theme={null} POST /v1/brcode/static X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d { "clientRequestId": "8c4ffd09-a264-4779-8d7e-fd24c971d7ff", "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..." } ``` Passe `include_base64=true` para receber também um PNG do QR Code codificado em Base64. O plugin valida que a conta é dona da chave do recebedor antes de criar o código. **Referência:** [Criar um QR code estático](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-static-qr-code.md) · [Listar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-static-qr-codes.md) · [Consultar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-static-qr-code.md) # Cobranças imediatas (COB) *** As cobranças imediatas (`/v1/collections/immediate`), ou COB, são QR Codes dinâmicos de uso único. Cada cobrança define um valor específico e uma janela de validade curta. Um `txId` obrigatório identifica cada cobrança. Um pagador pode liquidar uma cobrança apenas uma vez. **Campos obrigatórios:** `amount`, `expirationSeconds`, `receiverKey` e `txId`. Os campos opcionais `debtorName` e `debtorDocument` identificam o pagador pretendido. **Pix Saque e Pix Troco:** para criar uma cobrança de Pix Saque, adicione o campo opcional `withdrawalAmount`. Para criar uma cobrança de Pix Troco, envie `withdrawalAmount` junto com `transactionAmount`. O `transactionAmount` deve ser igual a `amount`. Os dois valores devem ser maiores que zero. **Ciclo de vida:** | Status | Significado | | - | - | | `ACTIVE` | Criada e disponível para pagamento | | `COMPLETED` | Pagamento recebido com sucesso | | `DELETED` | Cancelada pelo estabelecimento | A cobrança vale por `expirationSeconds` depois da criação. Você pode atualizar (`PUT`) ou apagar (`DELETE`) uma cobrança apenas enquanto ela está `ACTIVE`. **Confirmação de pagamento:** quando um Pix recebido liquida a cobrança, o plugin a move para `COMPLETED`. Em seguida, o plugin emite um webhook para avisar seu sistema em tempo real. Veja o [guia de Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md) e o [guia de Cobranças](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-collections.md) para o fluxo completo de pagamento. **Referência:** [Criar uma cobrança imediata](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-an-immediate-charge.md) · [Listar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-immediate-charges.md) · [Consultar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-immediate-charge-details.md) · [Atualizar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/update-an-immediate-charge.md) · [Apagar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/delete-an-immediate-charge.md) # Cobranças com vencimento (COBV) *** As cobranças com vencimento (`/v1/collections/duedate`), ou COBV, são QR Codes dinâmicos para faturamento com data de vencimento, como um boleto. Elas aceitam regras de valor complexas. Elas exigem os dados completos do devedor e do recebedor. **Campos principais:** `dueDate`, `validAfterDue`, um `debtor` obrigatório e um objeto `amount`. O campo obrigatório `validAfterDue` define por quantos dias a cobrança continua pagável depois do vencimento. O `debtor` precisa de um nome e de um CPF ou CNPJ. Ele também aceita os campos opcionais email, address, city, state e zipCode. O objeto `amount` guarda o valor `original` e os componentes de encargo opcionais: | Componente | Modalidade | Aplicação | | - | - | - | | `fine` | `FIXED_VALUE` ou `PERCENT` | Multa por atraso no pagamento | | `interest` | por exemplo, `PERCENTAGE_PER_MONTH_CALENDAR_DAYS` | Incide depois do vencimento | | `discount` | uma modalidade com um valor, ou um array `discountDateFixed` | Benefício pelo pagamento antecipado | | `abatement` | `FIXED_VALUE` ou `PERCENT` | Redução sobre o valor | O momento do pagamento determina o valor final. Antes do vencimento, o pagador recebe o desconto que houver. Depois do vencimento, a multa e os juros se aplicam, menos o abatimento que houver. Um desconto com data (`discountDateFixed`) é obrigatório para as modalidades `FIXED_VALUE_UNTIL_THE_DATES_INFORMED` e `PERCENTAGE_DATE_REPORTED`, e recusado para qualquer outra modalidade. O plugin valida cada entrada, e cada `date` não pode ser posterior ao `dueDate`. Cada valor de multa, juros, desconto e abatimento deve ser maior que zero, com no máximo 2 casas decimais. O plugin exige um documento válido do devedor (CPF ou CNPJ). A cobrança continua pagável até o vencimento mais `validAfterDue` dias. **Referência:** [Criar uma cobrança com vencimento](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date.md) · [Listar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date.md) · [Consultar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details.md) · [Atualizar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date.md) # Decodificação de QR Codes *** O decodificador (`POST /v1/qrcodes/decode`) interpreta qualquer QR Code Pix escaneado. Ele retorna os dados de pagamento embutidos. Use-o em fluxos de iniciação de pagamento. Um cliente escaneia um QR Code, e você lê o recebedor, o valor e os detalhes da cobrança antes de confirmar o pagamento. O plugin detecta o tipo do QR Code automaticamente e retorna uma resposta tipada: * **STATIC**: chave do recebedor, valor e descrição opcionais, dados do estabelecimento, `txId`. * **IMMEDIATE (COB)**: chave do recebedor, valor, expiração, `txId`, status, número de revisão e o devedor opcional. * **DUE\_DATE (COBV)**: chave do recebedor, `txId`, vencimento, `validAfterDue`, devedor, recebedor, status, número de revisão e a estrutura de multa, juros, desconto e abatimento com o valor final. * **RECURRENCE**: os dados de recorrência de um QR Code do Pix Automático. Para códigos dinâmicos, o plugin resolve o payload no BTG antes de responder. 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](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/decode-a-pix-qr-code.md) # Próximos passos *** * [Cobranças](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-collections.md): Ciclo de vida da cobrança, vínculo com o pagamento e eventos de webhook * [DICT](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-dict.md): Cadastro das chaves Pix em que seus QR Codes recebem * [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): Notificações de pagamento e de status This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.