Pular para o conteúdo principal
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 renderizados como QR Codes dinâmicos:
  • 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:
StatusSignificado
ACTIVECriada e disponível para pagamento
CONCLUDEDPagamento recebido — a cobrança está liquidada
REMOVED_BY_RECEIVERCancelada pelo lojista (DELETE)
REMOVED_BY_PSPCancelada pelo PSP (sistema ou política)
Uma cobrança passa por: criada → ACTIVE → CONCLUDED (paga) ou expirada / removida. Na criação, o plugin agenda um job de expiração:
  • Imediata (COB): expira após expirationInSeconds.
  • Com vencimento (COBV): expira em dueDate + validAfterDue dias (padrão 30).
Depois de expirada ou CONCLUDED, uma cobrança não pode mais ser paga, e uma cobrança CONCLUDED não pode ser excluída (PIX-0104) nem atualizada (PIX-0022).

​
Campos principais

CampoObrigatório emObservações
txIdCOB + COBVIdentificador único entre todas as cobranças; usado para vincular o pagamento recebido
amountCOB + COBVDecimal com 2 casas, maior que 0
receiverKeyCOB + COBVChave Pix que recebe o pagamento; deve pertencer à conta
expirationInSecondsSomente COBJanela de validade para cobranças imediatas
dueDate / validAfterDueSomente COBVData de vencimento e período de tolerância após o vencimento
debtorCOBV (opcional em COB)Nome + CPF/CNPJ; restringe quem pode pagar
amount.fine / interest / discount / abatementSomente COBV (opcional)Regras de cobrança exclusivas de COBV
Para COBV, o valor final liquidado depende do momento do pagamento — o pagamento antecipado aplica descontos, o pagamento no prazo usa o valor original e o pagamento em atraso adiciona multa e juros (descontado qualquer abatimento).

​
Criar, recuperar, atualizar, excluir

AçãoImediata (COB)Com vencimento (COBV)
CriarPOST /v1/collections/immediatePOST /v1/collections/duedate
ListarGET /v1/collections/immediateGET /v1/collections/duedate
RecuperarGET /v1/collections/immediate/{id}GET /v1/collections/duedate/{id}
AtualizarPATCH /v1/collections/immediate/{id}PATCH /v1/collections/duedate/{id}
ExcluirDELETE /v1/collections/immediate/{id}—
Todas as requisições exigem o cabeçalho X-Account-Id. Atualizações e exclusões só são permitidas enquanto a cobrança estiver ACTIVE.

​
Fluxo de pagamento

Uma cobrança é paga por 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 CONCLUDED e o cash-in é lançado no Midaz como uma transação de ledger.
  5. O plugin emite um webhook de cobrança paga para que seu sistema seja notificado em tempo real.
Quando um debtor é definido na cobrança, somente um pagamento desse CPF/CNPJ a liquida. Essa é a principal defesa contra a conclusão de uma cobrança pelo pagador errado.

​
Evento de webhook ao pagar

Quando uma cobrança é liquidada, o plugin enfileira um webhook de saída descrevendo o pagamento e o novo status CONCLUDED, entregue de forma assíncrona pelo worker de webhooks de saída. Configure o destino por meio das URLs de webhook de cash-in (WEBHOOK_TRANSFER_CASHIN_URL, com fallback para WEBHOOK_DEFAULT_URL). Para tipos de eventos, payloads, retentativas e resolução de URL, consulte o guia de Webhooks.

​
Casos de erro

CasoComportamento
ExpiradaA cobrança não pode mais ser paga; um pagamento recebido em atraso não é vinculado e segue o fluxo padrão de cash-in não correspondido
Divergência de valorUm pagamento cujo valor não corresponde à cobrança é rejeitado/tratado conforme as regras do BACEN e não conclui a cobrança
Divergência de pagador (debtor)Um pagamento de um CPF/CNPJ diferente do debtor configurado não liquida a cobrança (PIX-0073 cobre erros de formato do documento do pagador)
txId duplicadoA criação falha — o txId deve ser único entre todas as cobranças
Atualização/exclusão após a conclusãoRejeitada (PIX-0022 / PIX-0104) — uma cobrança CONCLUDED é imutável

​
Referência

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

​
Próximos passos