Collections

Create Pix collections (cobranças) through the Pix Indirect Plugin via BTG — immediate COB, due-date COBV, lifecycle states, payment linking, and webhooks.

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

---

Both collection types share the same status model:

Status	Meaning
ACTIVE	Created and available for payment
COMPLETED	Payment received — the collection is settled
REMOVED_BY_RECEIVER	Deleted by the merchant (DELETE)
REMOVED_BY_PSP	Expired after its validity window

A collection moves from ACTIVE to COMPLETED when the payer pays it. It moves to REMOVED_BY_PSP when it expires, or to REMOVED_BY_RECEIVER when the merchant deletes it. Each type has its own validity window:

• Immediate (COB): the charge expires after expirationSeconds.
• Due-date (COBV): the charge expires at dueDate plus validAfterDue days.

After a collection expires or reaches COMPLETED, the payer can no longer pay it. The plugin also rejects any attempt to delete or update a COMPLETED collection (PIX-0704).

Key fields

---

Field	Required in	Notes
txId	COB + COBV	Unique identifier across all collections; used to link the incoming payment
amount	COB + COBV	Decimal with 2 places, greater than 0
receiverKey	COB + COBV	Pix key receiving the payment; must be owned by the account
expirationSeconds	COB only	Validity window for immediate charges
dueDate / validAfterDue	COBV only	Due date and post-due grace period
debtor	COBV (optional in COB)	Name + CPF/CNPJ of the expected payer
amount.fine / interest / discount / abatement	COBV only (optional)	COBV-only charge rules

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

---

Action	Immediate (COB)	Due-date (COBV)
Create	POST /v1/collections/immediate	POST /v1/collections/duedate
List	GET /v1/collections/immediate	GET /v1/collections/duedate
Retrieve	GET /v1/collections/immediate/{id}	GET /v1/collections/duedate/{id}
Update	PATCH /v1/collections/immediate/{id}	PATCH /v1/collections/duedate/{id}
Delete	DELETE /v1/collections/immediate/{id}	—

All requests require the X-Account-Id header. 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. (FindByTxID(txID, receiverDocument).)
4. On a match, the collection moves to COMPLETED and the plugin posts the cash-in to Midaz as a ledger transaction.
5. The plugin emits a collection-paid webhook to notify your system in real time.

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 webhook describes the payment and the new COMPLETED status. The outbound webhook worker delivers it asynchronously. Configure the destination through the cash-in webhook URLs (WEBHOOK_TRANSFER_CASHIN_URL, with WEBHOOK_DEFAULT_URL as the fallback). For event types, payloads, retries, and URL resolution, see the Webhooks guide.

Error cases

---

Case	Behavior
Expired	The payer can no longer pay the collection. A late inbound payment stays unlinked and follows the standard unmatched cash-in flow
Amount mismatch	For an immediate charge, a payment whose amount differs from the charge does not complete the collection (PIX-0729)		Duplicate txId	Creation fails — a txId must be unique across all collections (PIX-0701)
Update/delete after completion	The plugin rejects the request (PIX-0704) — a COMPLETED collection is immutable

Reference

---

Immediate (COB): Create · List · Retrieve · Update · Delete

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

Next steps

---

• QR Codes — QR Code types and the decoder
• Intra-PSP transfers — Internal settlement when payer and payee share your ISPB
• Webhooks — Payment and status notifications