Skip to main content
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

Os dois tipos de cobrança compartilham o mesmo modelo de status: Uma cobrança passa de ACTIVE para COMPLETED quando o pagador a paga. Ela passa para REMOVED_BY_PSP quando expira, ou para REMOVED_BY_RECEIVER quando o lojista a exclui. Cada tipo tem a própria janela de validade:
  • Imediata (COB): a cobrança expira depois de expirationSeconds.
  • Com vencimento (COBV): a cobrança expira em dueDate mais validAfterDue dias.
Depois que uma cobrança expira ou chega a COMPLETED, o pagador não pode mais pagá-la. 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. 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. (FindByTxID(txID, receiverDocument).)
  4. Quando há correspondência, a cobrança passa para COMPLETED e o plugin lança o cash-in no Midaz como uma transação no ledger.
  5. O plugin emite um webhook de cobrança paga para notificar seu sistema em tempo real.
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 webhook descreve o pagamento e o novo status COMPLETED. 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, 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