Skip to main content
A collection (cobrança) is a dynamic, single-use Pix charge that requests a specific payment. The Pix Indirect Plugin (BTG) supports two kinds, both rendered as dynamic QR Codes:
  • Immediate (COB) — cobrança imediata: a short-lived charge for a fixed amount. Use it for checkout and one-time payments.
  • Due-date (COBV) — cobrança com vencimento: a boleto-like charge with a due date and optional fine, interest, discount, and abatement. Use it for bills, installments, and B2B invoicing.
This guide covers the collection lifecycle and the payment flow. For QR Code generation details and field-by-field validation, see the QR Codes guide.

​
Lifecycle

Both collection types share the same status model: A collection moves through: created → ACTIVE → CONCLUDED (paid) or expired / removed. On creation the plugin schedules an expiration job:
  • Immediate (COB): expires after expirationInSeconds.
  • Due-date (COBV): expires at dueDate + validAfterDue days (default 30).
Once expired or CONCLUDED, a collection can no longer be paid, and a CONCLUDED collection cannot be deleted (PIX-0104) or updated (PIX-0022).

​
Key fields

For COBV, the final settled value depends on payment timing — early payment applies discounts, on-time uses the original amount, and late payment adds fine and interest (minus any abatement).

​
Creating, retrieving, updating, deleting

All requests require the X-Account-Id header. Updates and deletes are only allowed while the collection is ACTIVE.

​
Payment flow

A collection is paid by an incoming Pix (cash-in) that carries the collection’s txId:
  1. The merchant creates a collection and presents its QR Code (or txId) to the payer.
  2. The payer settles the charge; BTG notifies the plugin of the inbound cash-in.
  3. The plugin links the cash-in to the collection by matching the payment’s txId against the collection’s txId and the receiver document. (FindByTxID(txId, receiverDocument).)
  4. On a match, the collection transitions to CONCLUDED and the cash-in is posted to Midaz as a ledger transaction.
  5. The plugin emits a collection-paid webhook so your system is notified in real time.
When a debtor is set on the collection, only a payment from that CPF/CNPJ settles it. This is the primary defense against the wrong payer concluding a charge.

​
Webhook event when paid

When a collection is settled, the plugin queues an outbound webhook describing the payment and the new CONCLUDED status, delivered asynchronously by the outbound webhook worker. Configure the destination via the cash-in webhook URLs (WEBHOOK_TRANSFER_CASHIN_URL, falling back to WEBHOOK_DEFAULT_URL). For event types, payloads, retries, and URL resolution, see the Webhooks guide.

​
Error cases

​
Reference

Immediate (COB): Create · List · Retrieve · Update · Delete Due-date (COBV): Create · List · Retrieve · Update

​
Next steps