> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> How Pix collections (cobranças) work in the Pix Indirect Plugin (BTG) — immediate (COB) and due-date (COBV) charges, their lifecycle, payment linking, and webhook events.

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](/en/midaz/plugins/pix/indirect/indirect-pix-qrcodes).

# Lifecycle

***

Both collection types share the same status model:

| Status                | Meaning                                      |
| --------------------- | -------------------------------------------- |
| `ACTIVE`              | Created and available for payment            |
| `CONCLUDED`           | Payment received — the collection is settled |
| `REMOVED_BY_RECEIVER` | Cancelled by the merchant (`DELETE`)         |
| `REMOVED_BY_PSP`      | Cancelled by the PSP (system or policy)      |

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

***

| 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                 |
| `expirationInSeconds`                                 | 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; restricts who may pay                                      |
| `amount.fine` / `interest` / `discount` / `abatement` | COBV only (optional)   | COBV-only charge rules                                                      |

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

***

| 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. 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.

<Note>
  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.
</Note>

# 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](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks).

# Error cases

***

| Case                               | Behavior                                                                                                                                      |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Expired**                        | Collection can no longer be paid; a late inbound payment is not linked and follows the standard unmatched cash-in flow                        |
| **Amount mismatch**                | A payment whose value does not match the charge is rejected/handled per BACEN rules and does not conclude the collection                      |
| **Debtor mismatch**                | A payment from a CPF/CNPJ other than the configured `debtor` does not settle the collection (`PIX-0073` covers debtor document format errors) |
| **Duplicate `txId`**               | Creation fails — `txId` must be unique across all collections                                                                                 |
| **Update/delete after conclusion** | Rejected (`PIX-0022` / `PIX-0104`) — a `CONCLUDED` collection is immutable                                                                    |

# Reference

***

**Immediate (COB):** [Create](/en/reference/midaz/plugins/indirect-pix/create-an-immediate-charge) · [List](/en/reference/midaz/plugins/indirect-pix/list-immediate-charges) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-immediate-charge-details) · [Update](/en/reference/midaz/plugins/indirect-pix/update-an-immediate-charge) · [Delete](/en/reference/midaz/plugins/indirect-pix/delete-an-immediate-charge)

**Due-date (COBV):** [Create](/en/reference/midaz/plugins/indirect-pix/create-a-dynamic-charge-with-due-date) · [List](/en/reference/midaz/plugins/indirect-pix/list-dynamic-charges-with-due-date) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-dynamic-charge-with-due-date-details) · [Update](/en/reference/midaz/plugins/indirect-pix/update-a-dynamic-charge-with-due-date)

# Next steps

***

* [QR Codes](/en/midaz/plugins/pix/indirect/indirect-pix-qrcodes) — QR Code types and the decoder
* [Intra-PSP transfers](/en/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Internal settlement when payer and payee share your ISPB
* [Webhooks](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Payment and status notifications