Skip to main content
Uma cobrança é uma cobrança Pix dinâmica e de uso único que solicita um pagamento específico. O Plugin Pix Indireto (BTG) suporta dois tipos. Ambos os 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 semelhante a um boleto, com data de vencimento e multa, juros, desconto e abatimento opcionais. Use para contas, parcelamentos 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 validação campo a campo, consulte o guia de QR Codes.

​
Ciclo de vida

Ambos os 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 sua própria janela de validade:
  • Imediata (COB): a cobrança expira após expirationSeconds.
  • Com vencimento (COBV): a cobrança expira em dueDate mais validAfterDue dias.
Depois que uma cobrança expira ou atinge 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

Para COBV, o valor final depende do momento do pagamento. O pagamento antecipado aplica descontos. O pagamento no prazo usa o valor original. O pagamento em atraso adiciona multa e juros, menos qualquer abatimento.

​
Criar, recuperar, atualizar, excluir

Todas as requisições exigem o cabeçalho X-Account-Id. Você pode atualizar ou excluir uma cobrança somente enquanto ela estiver 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 seu QR Code (ou 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 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 de 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, a cobrança registra o CPF/CNPJ do pagador esperado. O plugin não bloqueia um pagador diferente na liquidação.

​
Evento de webhook ao pagar

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 por meio das URLs de webhook de cash-in (WEBHOOK_TRANSFER_CASHIN_URL, com WEBHOOK_DEFAULT_URL como fallback). Para tipos de eventos, payloads, retentativas e resolução de URL, consulte o guia de Webhooks.

​
Casos de erro

​
Referência

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

​
Próximos passos