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 types. Both types use a dynamic QR Code:
  • 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

Each collection type reports its status with its own values: A collection moves from ACTIVE to COMPLETED when the payer pays it. An immediate collection moves to DELETED when the merchant deletes it. Each type has its own validity window:
  • Immediate (COB): the charge is valid for expirationSeconds after creation.
  • Due-date (COBV): the charge stays payable until dueDate plus validAfterDue days.
After a collection reaches COMPLETED, the plugin denies any further payment to it. The plugin also rejects any attempt to delete or update a COMPLETED collection (PIX-0704).

​
Key fields

For COBV, the final value depends on payment timing. Early payment applies discounts. On-time payment uses the original amount. Late payment adds fine and interest, minus any abatement.

​
Creating, retrieving, updating, deleting

All requests require the X-Account-Id header. A delete also requires X-Reason (DELETED_BY_USER or DELETED_BY_PSP). You can update or delete a collection only while it is ACTIVE.

​
Payment flow

The payer settles a collection with 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. The collection must be ACTIVE. For an immediate charge, the amount must also match. Otherwise the plugin denies the payment.
  4. The plugin posts the cash-in to Midaz as a ledger transaction, then moves the collection to COMPLETED.
  5. The plugin emits the cash-in webhook to notify your system.
When you set a debtor on the collection, the charge records the expected payer’s CPF/CNPJ. The plugin does not block a different payer at settlement.

​
Webhook event when paid

After a payment settles a collection, the plugin queues an outbound webhook: the TRANSFER / CASHIN event of the payment. The outbound webhook worker delivers it asynchronously. Configure the destination through the cash-in webhook URLs (WEBHOOK_TRANSFER_CASHIN_URL, then WEBHOOK_TRANSFER_URL, with WEBHOOK_DEFAULT_URL as the fallback). 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