X-Account-Id. Veja o guia do DICT para o cadastro de chaves.
Como escolher o 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 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.
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 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 · Listar · Consultar
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.
Ciclo de vida:
Quando você cria uma cobrança, o plugin agenda um job de expiração. Depois que
expirationSeconds se esgota, a cobrança passa para EXPIRED e nenhum pagador consegue liquidá-la. 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 e o guia de Cobranças para o fluxo completo de pagamento.
Referência: Criar uma cobrança imediata · Listar · Consultar · Atualizar · Apagar
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:
O momento do pagamento determina o valor final. Antes do vencimento, o pagador recebe o desconto que houver. No dia do vencimento, vale o valor
original. Depois do vencimento, o plugin soma a multa e os juros, depois subtrai o abatimento que houver. Um desconto com data (discountDateFixed) precisa de uma date anterior ao dueDate.
O plugin exige um documento válido do devedor (CPF ou CNPJ). Ele mantém a cobrança pagável até o vencimento mais validAfterDue dias.
Referência: Criar uma cobrança com vencimento · Listar · Consultar · Atualizar
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): 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 vencimento,
validAfterDue, devedor, recebedor e a estrutura completa de multa, juros e desconto.