Pular para o conteúdo principal
Uma cobrança (collection) é uma cobrança Pix dinâmica e de uso único que pede um pagamento específico. O Plugin Pix Indireto (BTG) aceita dois tipos. Os dois tipos usam um QR Code dinâmico:
  • Imediata (COB) (cobrança imediata): uma cobrança de curta duração com valor fixo. Use para checkout e pagamentos únicos.
  • Com vencimento (COBV) (cobrança com vencimento): uma cobrança parecida com um boleto, com vencimento e, opcionalmente, multa, juros, desconto e abatimento. Use para contas, parcelas e faturamento B2B.
Este guia cobre o ciclo de vida da cobrança e o fluxo de pagamento. Para detalhes de geração de QR Code e a validação campo a campo, veja o guia de QR Codes.

​
Ciclo de vida

Cada tipo de cobrança informa o status com os próprios valores: Uma cobrança passa de ACTIVE para COMPLETED quando o pagador a paga. Uma cobrança imediata passa para DELETED quando o lojista a exclui. Cada tipo tem a própria janela de validade:
  • Imediata (COB): a cobrança vale por expirationSeconds depois da criação.
  • Com vencimento (COBV): a cobrança continua pagável até dueDate mais validAfterDue dias.
Depois que uma cobrança chega a COMPLETED, o plugin nega qualquer novo pagamento a ela. O plugin também rejeita qualquer tentativa de excluir ou atualizar uma cobrança COMPLETED (PIX-0704).

​
Campos principais

No COBV, o valor final depende do momento do pagamento. O pagamento antecipado aplica descontos. O pagamento em dia usa o valor original. O pagamento em atraso soma multa e juros, menos qualquer abatimento.

​
Criar, consultar, atualizar, excluir

Todas as requisições exigem o header X-Account-Id. Uma exclusão também exige X-Reason (DELETED_BY_USER ou DELETED_BY_PSP). Você pode atualizar ou excluir uma cobrança apenas enquanto ela está ACTIVE.

​
Fluxo de pagamento

O pagador liquida uma cobrança com um Pix recebido (cash-in) que carrega o txId da cobrança:
  1. O lojista cria uma cobrança e apresenta o QR Code dela (ou o txId) ao pagador.
  2. O pagador liquida a cobrança. O BTG notifica o plugin sobre o cash-in recebido.
  3. O plugin vincula o cash-in à cobrança comparando o txId do pagamento com o txId da cobrança e com o documento do recebedor. A cobrança deve estar ACTIVE. Em uma cobrança imediata, o valor também deve corresponder. Caso contrário, o plugin nega o pagamento.
  4. O plugin lança o cash-in no Midaz como uma transação no ledger e depois passa a cobrança para COMPLETED.
  5. O plugin emite o webhook de cash-in para notificar seu sistema.
Quando você define um debtor na cobrança, ela registra o CPF/CNPJ do pagador esperado. O plugin não bloqueia um pagador diferente na liquidação.

​
Evento de webhook no pagamento

Depois que um pagamento liquida uma cobrança, o plugin enfileira um webhook de saída: o evento TRANSFER / CASHIN do pagamento. O worker de webhooks de saída o entrega de forma assíncrona. Configure o destino pelas URLs de webhook de cash-in (WEBHOOK_TRANSFER_CASHIN_URL, depois WEBHOOK_TRANSFER_URL, com WEBHOOK_DEFAULT_URL como fallback). Para tipos de evento, payloads, novas tentativas e resolução de URL, veja o guia de Webhooks.

​
Casos de erro

​
Referência

Imediata (COB): Criar · Listar · Consultar · Atualizar · Excluir Com vencimento (COBV): Criar · Listar · Consultar · Atualizar

​
Próximos passos