X-Account-Id. Consulte o guia de DICT para o registro de chaves.
Escolhendo um tipo de QR Code
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 vincula 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.
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. Se você omitir os dados do estabelecimento, o plugin os preenche a partir dos dados do titular no CRM.
include_base64=true para também receber um PNG do QR Code codificado em Base64. O plugin valida que a conta é proprietária da chave do recebedor antes de criar o código.
Referência: Criar um QR code estático · Listar · Recuperar
Cobranças imediatas (COB)
As cobranças imediatas (
/v1/collections/immediate), ou cobrança imediata, são QR Codes dinâmicos e 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 só pode liquidar uma cobrança uma vez.
Campos obrigatórios: amount, expirationSeconds, receiverKey e txId. Os campos opcionais debtorName e debtorDocument identificam o pagador pretendido.
Ciclo de vida:
Quando você cria uma cobrança, o plugin agenda um job de expiração. Após decorrido
expirationSeconds, a cobrança passa para EXPIRED e nenhum pagador pode liquidá-la. Você só pode atualizar (PUT) ou excluir (DELETE) uma cobrança enquanto ela está em ACTIVE.
Confirmação de pagamento: quando um Pix recebido liquida a cobrança, o plugin a passa para COMPLETED. Em seguida, o plugin emite um webhook para notificar seu sistema em tempo real. Consulte o guia de Webhooks e o guia de Cobranças para o fluxo de pagamento completo.
Referência: Criar uma cobrança imediata · Listar · Recuperar · Atualizar · Excluir
Cobranças com vencimento (COBV)
As cobranças com vencimento (
/v1/collections/duedate), ou cobrança com vencimento, são QR Codes dinâmicos para faturamento com data de vencimento, como um boleto. Elas suportam regras de valor complexas. Elas exigem dados completos do pagador e do recebedor.
Campos principais: dueDate, validAfterDue, um debtor obrigatório e um objeto amount. O campo obrigatório validAfterDue define os dias em que a cobrança permanece pagável após o vencimento. O debtor precisa de um nome e um CPF ou CNPJ. Ele também aceita e-mail, endereço, cidade, estado e CEP opcionais. O objeto amount contém o valor original e componentes de encargo opcionais:
O momento do pagamento determina o valor final. Antes do vencimento, o pagador recebe qualquer desconto. Na data de vencimento, aplica-se o valor
original. Após o vencimento, o plugin adiciona a multa e os juros, e depois subtrai qualquer abatimento. Um desconto com data (discountDateFixed) precisa de uma date anterior à dueDate.
O plugin exige um documento de pagador válido (CPF ou CNPJ). Ele mantém a cobrança pagável até a data de vencimento mais validAfterDue dias.
Referência: Criar uma cobrança com vencimento · Listar · Recuperar · Atualizar
Decodificando QR Codes
O decodificador (
POST /v1/qrcodes/decode) analisa qualquer QR Code Pix escaneado. Ele retorna os dados de pagamento nele incorporados. 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 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.