# QI Tech — Investment-as-a-Service › Asset Settlement

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
12 página(s).

Índice:
- CNAB 444 Layout — Settlement (/en/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa)
- Settlement by File (/en/documentation/iaas/liquidacao_ativos/arquivo/inicio)
- Settlement Insertion (/en/documentation/iaas/liquidacao_ativos/ativos/)
- Settlement Retrieval (/en/documentation/iaas/liquidacao_ativos/ativos/recuperacao)
- Settlement Webhooks (/en/documentation/iaas/liquidacao_ativos/ativos/webhook)
- Asset settlement flow (/en/documentation/iaas/liquidacao_ativos/fluxo_liquidacao)
- Asset Settlement (/en/documentation/iaas/liquidacao_ativos/inicio)
- Payment Batch Creation (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
- Close Payment Batch Insertion (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)
- Payment Batch Listing (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem)
- Payment Batch Retrieval (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao)
- Payment Batch Webhooks (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)

---

# CNAB 444 Layout — Settlement

URL: /en/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa

Layout of the **settlement remittance file** accepted by QI DTVM. The structure is the same as the [assignment file](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444): 444 positions, header `0`, details `1` and trailer `9`. What changes is the **occurrence code**, the **paid value** and the **settlement date**.

:::tip Reuse the assignment line

The safest way to assemble the settlement file is to start from the line sent in the assignment and change only three fields: occurrence (109–110), paid value (083–092) and settlement date (095–100). The identifier of the asset — the participant's control number — **must be exactly the same** used in the assignment.

:::

## What changes in relation to the assignment file

| Position | Field | In the assignment | In the settlement |
|---|---|---|---|
| 083–092 | Paid value | Zeros | **Value actually paid**, 2 decimals |
| 095–100 | Settlement date | Zeros | **Payment date**, `DDMMYY` |
| 109–110 | Occurrence identification | `01` | `04`, `06`, `14`, `75` or `77` |
| 150–150 | Identification | Free | Blank or `0` |
| 157–158 | 1st instruction | Free | `00` |
| 159–159 | 2nd instruction | Free | `0` |
| 381–394 | Assignor's CNPJ | The name is checked | **CNPJ checked with the check digit** |

All the other fields follow the same filling rules, domains and requirements as the [assignment detail record table](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444#detail-record).

## Accepted occurrences

| Code | Meaning | Effect on the portfolio | Source of the funds |
|---|---|---|---|
| `77` | **Settlement by the drawee's deposit** | Full settlement (`asset_settlement` / `installment_settlement`) | Drawee |
| `14` | **Partial payment** | Amortization (`asset_amortization` / `installment_amortization`) | Drawee |
| `75` | **Settlement by the assignor's deposit** | Full settlement (`asset_settlement` / `installment_settlement`) | Assignor |
| `04` | **Rebate** | Amortization by the rebate amount (positions 206–218, greater than zero) | Assignor |
| `06` | **Maturity change** | Maturity extension (`asset_extension`). Only duplicatas and other credit rights | Drawee |

:::caution Only these five

Any other occurrence code refuses the file with the message *"This field only allows one of this values: ['04', '06', '14', '75', '77']"*. Acquisition occurrences (`01`, `80`, `81`, `84`) belong to the [assignment file](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444).

:::

## How the asset is identified

| Asset type | Field used as the identifier | Complement |
|---|---|---|
| Duplicatas, CT-e and contracts | **Participant's control number** (038–062) | — |
| CCB and other credit operations | **Participant's control number** (038–062), the same as in the assignment | The installment is identified by the **maturity date** (121–126) |

:::caution The identifier must match the one in the assignment

If the participant's control number does not correspond to an asset held in the fund's portfolio, that settlement fails individually in the processing — the batch continues, but it ends as `processed_with_failures`.

:::

## Commented example

Settlement of two instruments assigned in the assignment example: the first settled in full by the drawee, the second with a partial payment.

```text title="CB101001.REM"
01REMESSA01COBRANCA       00000011222333000181INDUSTRIA EXEMPLO S/A         ...MX...000001
1...0CTRL000001...0000151000  101025        77000100001101025...COMERCIO EXEMPLO ALFA LTDA...000002
1...0CTRL000002...0000050000  101025        14000200002101025...COMERCIO EXEMPLO BETA LTDA...000003
9                                                                              ...000004
```

| Line | Reading |
|---|---|
| Detail 1 | Asset `CTRL000001` settled on 10/10/2025 — occurrence `77`, paid value R$ 1,510.00 (in full) |
| Detail 2 | Asset `CTRL000002` amortized on 10/10/2025 — occurrence `14`, paid value R$ 500.00 (partial) |

### Example files

| File | Instrument kind | What it carries |
|---|---|---|
| [Settlement of duplicatas](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) | `01` | One full settlement (`77`) and one partial payment (`14`), identified by the participant's control number |
| [Settlement of CCB](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) | `41` | Two installments identified by the participant's control number and by the maturity date |

## Checklist before sending

- [ ] All the lines with exactly 444 characters
- [ ] Occurrence `04`, `06`, `14`, `75` or `77` in positions 109–110
- [ ] Paid value filled in positions 083–092, with 2 decimals and without a comma
- [ ] Settlement date filled in positions 095–100, in the `DDMMYY` format
- [ ] Participant's control number identical to the one sent in the assignment
- [ ] Assignor's CNPJ (381–394) and drawee's CPF/CNPJ (221–234) with a valid check digit
- [ ] 1st instruction `00`, 2nd instruction `0` and identification (150) blank
- [ ] No accents, `Ç` or special characters
- [ ] Trailer closing the file with the sequential number of the last line

---

# Settlement by File

URL: /en/documentation/iaas/liquidacao_ativos/arquivo/inicio

The settlement (write-off) of assets already held in the fund's portfolio can be done in two ways: **sending a file** with all the settlements of the day, through the manager/consultant portal, or **inserting settlement by settlement through the API**. Both produce the same payment batch and go through the same reconciliation.

| | Sending by file | Insertion through the API |
|---|---|---|
| **How it works** | One file with all the settlements | One request per settlement |
| **Formats** | CNAB 444 and CSV | JSON |
| **Available in** | Manager and consultant portal | [Asset Settlement API](/documentation/iaas/liquidacao_ativos/inicio) |
| **Suitable for** | Daily routine of high-volume settlements, from the bank return file | One-off settlements and real-time integrations |

:::info Settlement by file is a screen flow

Today, sending a settlement file is available in the **portal**. Through the integration API, the settlement is done through the [payment batch + settlements](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) flow, without a file.

:::

## Accepted formats

| Format | Extension | Suitable for | Template |
|---|---|---|---|
| **CNAB 444** — duplicatas and CT-e | `.rem` · `.txt` | Those who already receive a CNAB return file from the collecting bank. Layout in [CNAB 444 Layout — Settlement](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa) | [Example](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) |
| **CNAB 444** — CCB and credit operations | `.rem` · `.txt` | The same layout, with the asset identified by the contract number | [Example](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) |
| **CSV** | `.csv` | A simple spreadsheet, with one line per settlement, for any asset type. Layout in the [Settlement CSV](#settlement-csv) section | [Example](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv) |

## Step by step through the screen

1. Go to **Assets › Settlements** and click **New batch by file**.
2. Provide a **description** to identify the batch.
3. Select the **fund account** that will receive the credit of the settlements.
4. Drag the file (`.rem`, `.txt` or `.csv`) and confirm.

The portal creates the payment batch, sends the file and triggers the validation. The screen then shows the batch with the progress — total settlements, processed and failed.

## What happens after sending

| Batch stage | What it means |
|---|---|
| Awaiting file | Batch created, file not sent yet |
| Validation in progress | File received, being checked line by line |
| Creating the batch | File valid, payment batch being created |
| Inserting the settlements | Each line is becoming a settlement |
| Completed | All the settlements processed |
| Completed with failures | Batch processed, but with settlements that failed individually |
| Refused | File refused in the validation — nothing was processed |

:::caution Validation is all or nothing

One invalid line refuses the whole file. The portal reports the line number and the description of the error. Fix it and send a new batch, with a new identifier.

:::

After the batch is closed and the payment confirmed, each settlement is reconciled individually in the fund's portfolio — the same behavior described in the [Settlement flow](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). A settlement can fail on its own (for example, an asset not found in the portfolio) without bringing down the others.

## Settlement CSV

A file with a header on the first line, separated by `;` or `,`. Limit of 850,000 lines.

```csv title="exemplo_baixa_liquidacoes.csv"
asset_type;total_value;settlement_type;external_id;installment_number;collection_origin_type
duplicata_mercantil;1510.00;asset_settlement;CTRL000001;;borrower
duplicata_mercantil;500.00;asset_amortization;CTRL000002;;borrower
ccb;350.75;installment_settlement;CONTRATO-0001;3;borrower
```

### Columns

| Column | Required | Description |
|---|---|---|
| `asset_type` | required | Asset type. See [accepted values](#accepted-asset-types) |
| `total_value` | required | Value of the settlement. Accepts `.` or `,` as the decimal separator |
| `settlement_type` | required | Settlement type. See [settlement types](#settlement-types) |
| `installment_number` | required (column) | Installment number. Fill it in for assets with installments (CCB); leave it empty for duplicatas; for contracts, use `installment_number` or `installment_external_id` |
| `external_id` **or** `contract_number` | required | Identifier of the asset. Use `external_id` for duplicatas/contracts (the same control number sent in the assignment) and `contract_number` for CCBs |
| `collection_origin_type` | optional | Who paid: `borrower` (drawee), `assignor` (assignor) or `collection_agent` (collection agent) |
| `remaining_face_value` | optional | Remaining balance of the face value. Accepted **only** with `settlement_type: installment_amortization` |
| `new_maturity_date` | conditional | New maturity date, in the `YYYY-MM-DD` format. Required in `asset_extension` and rejected in the other types |
| `installment_external_id` | optional | For contracts, an alternative to `installment_number` |

:::caution The identification column defines the whole batch

The same file uses `external_id` **or** `contract_number` — not both. If neither column exists, the file is refused.

:::

### Settlement types

| Value | Meaning |
|---|---|
| `asset_settlement` | Full settlement of the asset |
| `asset_amortization` | Partial payment of the asset |
| `installment_settlement` | Full settlement of an installment |
| `installment_amortization` | Partial payment of an installment |
| `installment_partial_refund` / `asset_partial_refund` | Partial refund |
| `installment_refund` / `asset_refund` | Full refund |
| `fine_payment` / `installment_fine_payment` | Fine payment |
| `gloss` | Gloss |
| `canceled` | Cancellation |
| `rco_revenue` | RCO revenue |
| `asset_extension` | Maturity extension (credit rights only; requires the `external_id` column and `new_maturity_date`) |

### Accepted asset types

`ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte` · `commercial_paper` · `check` · `promissory_note` · `debt_acknowledgment` · `financing_contract` · `contract`

**[📄 Download the example CSV](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv)**

## Most common errors

| Error | Cause |
|---|---|
| `missing_fields: [...]` | A required column is missing from the CSV header |
| `invalid asset_type: ...` | Asset type outside the accepted list |
| `invalid settlement_type: ...` | Settlement type outside the accepted list |
| `invalid total_value: ...` | Value with an unexpected character or empty |
| `invalid external_id` / `contract_number` | Blank identifier |
| `remaining_face_value is only allowed for settlement_type installment_amortization` | Remaining balance provided with the wrong type |
| `unmapped cnab layout` | CNAB file with lines outside 444 or 500 positions |

---

# Settlement Insertion

URL: /en/documentation/iaas/liquidacao_ativos/ativos/

Endpoint to insert individual settlements into a previously created payment batch. Each settlement represents a payment (full or partial) for an asset in the fund's portfolio — such as installment settlement, amortization, repurchase or interest payment.

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Write               |
| Consultant | `consultant-api` | Create Batches      |
| Assignor   | `assignor-api`   | Write               |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

:::info Settlement, repurchase and pass-through

Settlement and repurchase use this same endpoint. The `collection_origin_type` field indicates who paid:

- `borrower` — **settlement** paid by the drawee/debtor.
- `assignor` — **repurchase** paid by the assignor.
- `collection_agent` — payment passed through by a collection agent. Requires `counter_party_document_number`.
- `bankslip` — payment received by bankslip.

:::

:::tip Where am I in the flow?

This is the **2nd step** of the settlement flow. Before this step, you must have [created the payment batch](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). The batch must be in `pending_settlements_insertion`.

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
METHOD POST

### Path params

| Parameter | Type | Description |
|---|---|---|
| `external_id` | string | The `external_id` of the payment batch where the settlement will be inserted. |

```json title="Request Body"
{
    "asset_type": "ccb",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "settlement_type": "installment_settlement",
    "contract_number": "0123456789/ABC",
    "installment_number": 1,
    "collection_date": "2025-01-01",
    "collection_origin_type": "borrower"
}
```

### Body attributes

| Field | Type | Required | Description |
|---|---|---|---|
| `asset_type` | string | required | Asset type. See [`asset_type` enumerators](#asset_type-enumerators). Maximum 255 characters. |
| `total_value` | number | required | Total payment amount, with at most two decimal places. Can be `0` only in `installment_settlement`, `asset_settlement`, `asset_refund` and `asset_extension`. |
| `external_id` | string | required | Unique key of this settlement within the batch, in the integrating partner's system. Maximum 50 characters. |
| `settlement_type` | string | required | Settlement type. See [`settlement_type` enumerators](#settlement_type-enumerators). Maximum 50 characters. |
| `collection_origin_type` | string | optional | Who paid. See [`collection_origin_type` enumerators](#collection_origin_type-enumerators). When omitted, the default from the fund's settlement configuration applies, if any. |
| `counter_party_document_number` | string | conditional | CPF or CNPJ of who paid, with punctuation (14 to 18 characters). **Required** when `collection_origin_type` is `collection_agent` and the fund's settlement configuration does not define a default document. With `borrower`, `bankslip` or `assignor`, when omitted, it is filled in with the document of the asset's drawee or assignor. |
| `contract_number` | string | optional | Contract number of the asset. Maximum 50 characters. |
| `asset_external_id` | string | optional | Unique asset identification key, provided in the assignment. Maximum 50 characters. |
| `asset_key` | string | optional | Internal asset key at QI Tech (UUID, 36 characters). |
| `if_code` | string | optional | Financial instrument code (B3). Maximum 36 characters. |
| `participant_control_number` | string | optional | Participant control number provided in the assignment. Maximum 50 characters. |
| `installment_number` | integer | conditional | Installment number. See [installment identification](#asset-and-installment-identification). |
| `installment_maturity_date` | string | conditional | Installment maturity date in `YYYY-MM-DD` format. |
| `installment_external_id` | string | conditional | External identifier of the installment. Maximum 50 characters. |
| `collection_date` | string | optional | Payment date in `YYYY-MM-DD` format. Field intended for the integrator's own control. |
| `remaining_face_value` | number | optional | Face value balance remaining in the installment after the payment. Accepted only in `installment_amortization` and when the settlement affects a single asset. |
| `asset_reduction_value` | number | optional | Amount to deduct from the asset, when different from the amount paid. Accepted only in `installment_amortization` and `installment_partial_refund`. Cannot be greater than `total_value`. |
| `new_maturity_date` | string | conditional | New maturity date, in `YYYY-MM-DD` format. **Required** in `asset_extension` and rejected in the other types. |
| `reversed_settlement_external_id` | string | conditional | `external_id` of the settlement being reversed. **Required** in `installment_payment_reversal` and rejected in the other types. |

:::info Difference between external_id fields

The `external_id` field in the request body refers to the **settlement** identifier. The `external_id` field in the URL refers to the **payment batch** identifier.

:::

### Asset and installment identification

- Provide **exactly one** asset identifier: `contract_number`, `asset_external_id`, `asset_key`, `if_code` or `participant_control_number`. None or more than one returns an error. Duplicatas and other credit rights do not accept `contract_number` or `if_code`; CCBs and other credit operations do not accept `participant_control_number`.
- In installment-based settlement types (`installment_*` and `gloss`), provide **exactly one** installment identifier: `installment_number`, `installment_maturity_date` or `installment_external_id`. For CCBs and contracts, `installment_external_id` alone also identifies the asset.

#### `asset_type` enumerators

| Value | Description |
|---|---|
| `ccb` | Bank Credit Note (Cédula de Crédito Bancário) |
| `cce` | Export Credit Note (Cédula de Crédito à Exportação) |
| `structured_ccb` | Structured Bank Credit Note |
| `structured_cce` | Structured Export Credit Note |
| `structured_nce` | Structured Export Credit Certificate (Nota de Crédito à Exportação) |
| `structured_cci` | Structured Real Estate Credit Note |
| `duplicata_mercantil` | Commercial duplicata (Duplicata Mercantil) |
| `duplicata_servicos` | Service duplicata (Duplicata de Serviços) |
| `discounted_contract` | Discounted contract |
| `cte` | Electronic Bill of Lading (Conhecimento de Transporte Eletrônico) |
| `check` | Check |
| `promissory_note` | Promissory note |
| `legal_fees` | Legal fees |
| `debt_acknowledgment` | Debt acknowledgment |
| `financing_contract` | Financing contract |
| `contract` | Contract |

#### `settlement_type` enumerators

| Value | Description |
|---|---|
| `asset_settlement` | Full settlement of the asset. |
| `asset_amortization` | Amortization of the asset. |
| `fine_payment` | Payment of interest or late charges on the asset. |
| `asset_refund` | Full refund of the asset. |
| `asset_partial_refund` | Partial refund of the asset. |
| `asset_gloss` | Gloss (deduction) of the asset. |
| `asset_extension` | Maturity extension of duplicatas and other credit rights. Requires `new_maturity_date` and a single asset. |
| `installment_settlement` | Installment settlement. |
| `installment_amortization` | Installment amortization. |
| `installment_fine_payment` | Payment of interest or late charges on an installment. |
| `installment_refund` | Full refund of an installment. |
| `installment_partial_refund` | Partial refund of an installment. |
| `installment_payment_reversal` | Reversal of the payment of an installment of a CCB or credit operation. Requires `reversed_settlement_external_id` and `installment_number`; `total_value` must equal that of the reversed settlement. |
| `gloss` | Gloss (deduction) of an installment. |
| `rco_revenue` | RCO revenue. |

Contracts (`debt_acknowledgment`, `financing_contract`, `contract`) accept only `asset_settlement`, `asset_amortization`, `installment_settlement` and `installment_amortization`.

#### `collection_origin_type` enumerators

| Value | Description |
|---|---|
| `borrower` | Settlement — payment made by the drawee/debtor. |
| `assignor` | Repurchase — payment made by the assignor. |
| `collection_agent` | Pass-through from a collection agent. Requires `counter_party_document_number` (or a default document in the fund configuration). |
| `bankslip` | Payment received by bankslip. |

## Response

STATUS 201

The response echoes the fields sent in the body and adds the data computed by QI Tech.

```json title="Response Body"
{
    "asset_type": "ccb",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "settlement_type": "installment_settlement",
    "contract_number": "0123456789/ABC",
    "installment_number": 1,
    "collection_date": "2025-01-01",
    "collection_origin_type": "borrower",
    "asset_external_id": "CCB-0001",
    "assignor_document_number": "33.444.555/0001-81",
    "borrower_document_number": "969.698.790-03",
    "status": "validated",
    "type": "installment_settlement",
    "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890",
    "total_number_of_units": 1,
    "settlement_result": 0.0,
    "next_execution_datetime": "2025-01-01 13:00:00.000000",
    "counter_party_document_number": "969.698.790-03",
    "assets": [
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value": 130.50
        }
    ]
}
```

### Response attributes

In addition to the fields sent in the body:

| Field | Type | Description |
|---|---|---|
| `status` | string | Settlement status after insertion: `validated` or `pending_validation`. See below. |
| `type` | string | Settlement type (same value as `settlement_type`). |
| `settlement_key` | string | Unique settlement identifier generated by QI Tech (UUID). |
| `total_value` | number | Total payment amount. Negative in `gloss`, `asset_gloss` and `installment_payment_reversal`. |
| `total_number_of_units` | integer | Total number of asset units affected by the settlement. |
| `installment_number` | integer | Number of the installment found. Present when applicable. |
| `settlement_result` | number | Difference between the amount paid and the expected amount of the asset or installment. Present when calculated. |
| `contract_number`, `asset_external_id` | string | Identifiers of the asset found in the portfolio (CCBs and contracts). |
| `assignor_document_number`, `borrower_document_number` | string | Document of the asset's assignor and drawee. |
| `counter_party_document_number` | string | Document of who paid. Present when provided or filled in automatically. |
| `collection_origin_type` | string | Payment origin. Present when provided or defined by the fund configuration. |
| `next_execution_datetime` | string | QI Tech processing control. Can be ignored. |
| `denial_reason` | string | Discard reason. Present only in discarded settlements. |
| `assets` | array | Assets affected by the settlement. See [`assets` attributes](#assets-attributes). |

**Status in the response:**

- `validated` — the amount paid is within the tolerance relative to the expected amount of the asset or installment. The settlement will be processed when the batch is paid.
- `pending_validation` — the amount paid differs from the expected amount beyond the tolerance and the settlement awaits review by QI Tech. At the end of the review it moves to `validated` or `discarded`, and you receive the corresponding [settlement webhook](/documentation/iaas/liquidacao_ativos/ativos/webhook). Depending on the fund's settlement configuration, the difference may instead reject the insertion with `SET000066`.

#### `assets` attributes

| Field | Type | Description |
|---|---|---|
| `asset_key` | string | Unique asset identifier (UUID). |
| `number_of_units` | integer | Number of asset units. |
| `present_value` | number | Present value of the asset in BRL. |
| `installment_face_value` | number | Installment face value. Present when applicable. |
| `installment_post_maturity_interest_value` | number | Post-maturity interest value of the installment. Present when applicable. |
| `installment_delay_interest_value` | number | Late interest value of the installment. Present when applicable. |
| `installment_delay_fine_value` | number | Late fine value of the installment. Present when applicable. |
| `total_purchase_value` | number | Acquisition value of the asset. Present when applicable. |
| `maturity_date` | string | Maturity of the asset. Present when applicable. |
| `contract_number` | string | Contract number of the asset. Present when applicable. |
| `external_id` | string | External identifier of the asset. Present when applicable. |

## Retry and duplicates {#reenvio-e-duplicidade}

If an error occurs, resend the request. A duplicate (`SET000013`) means the settlement already exists in this batch: look it up through the [settlement retrieval](/documentation/iaas/liquidacao_ativos/ativos/recuperacao) instead of recreating it. See [Retry and duplicates](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).

## Next steps

After inserting all desired settlements, the flow continues with:

1. **[Batch closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — signal that all settlements have been inserted so that processing can begin.

There is no endpoint to remove an individual settlement. If a settlement was inserted by mistake, discard the batch at [closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`) and create a new batch with the correct settlements.

## Errors

| Status | Code | When it happens |
|---|---|---|
| 404 | `SET000010` | The batch given in the URL does not exist in this fund. |
| 403 | `SET000028` | The fund does not belong to your profile. |
| 400 | `SET000026` | The batch is not in `pending_settlements_insertion` (it has already been closed or discarded). |
| 400 | `SET000013` | A settlement with this `external_id` already exists in the batch. Look it up instead of recreating it. |
| 409 | `SET000053` | Two simultaneous requests with the same `external_id`; one of them was saved. |
| 400 | `SET000012` | Invalid `asset_type`. |
| 400 | `SET000025` | Invalid `settlement_type`. |
| 400 | `SET000014` | `total_value` with more than two decimal places, or zero in a type that does not accept zero. |
| 400 | `SET000019` | No asset identifier was provided. |
| 400 | `SET000020` | More than one asset identifier, or more than one installment identifier. |
| 400 | `SET000029` | Installment-based settlement type without installment identification. |
| 400 | `SET000040` / `SET000041` | Settlement type or identifier not accepted for this `asset_type`. |
| 400 | `SET000022` / `SET000023` / `SET000047` | The asset is not active or does not accept this settlement type in its current status. |
| 400 | `SET000086` / `SET000087` / `SET000088` | `remaining_face_value` outside `installment_amortization`, with more than two decimal places, or with the settlement affecting more than one asset. |
| 400 | `SET000092` / `SET000093` / `SET000094` | `asset_extension` without `new_maturity_date`, `new_maturity_date` in another type, or an extension affecting more than one asset. |
| 400 | `SET000112` / `SET000113` / `SET000114` | `asset_reduction_value` outside `installment_amortization`/`installment_partial_refund`, with more than two decimal places, or greater than `total_value`. |
| 400 | `SET000104` / `SET000105` | `installment_payment_reversal` without `reversed_settlement_external_id`/`installment_number`, or `reversed_settlement_external_id` in another type. |
| 400 / 404 / 409 | `SET000106` to `SET000111`, `SET000115` | The reversed settlement does not exist, is not `settled`, is of another type, installment or asset, has already been reversed, or the amount differs. |
| 404 | `SET000015` | No asset found in the fund's portfolio with the identifier provided. |
| 400 | `SET000035` / `SET000042` / `SET000052` / `SET000060` | The installment provided does not exist or has no balance in the asset. |
| 400 | `SET000046` | Another settlement of the same group for the same asset/installment already exists in the same batch. |
| 400 | `SET000080` | Full settlement of an asset that is already settled (present value zero). |
| 400 | `SET000066` | Amount paid outside the tolerance and the fund is configured to reject automatically. |
| 400 | `SET000067` | Invalid `collection_origin_type`. |
| 400 | `SET000078` | `collection_origin_type` is `collection_agent` without `counter_party_document_number`. |
| 400 | `SET000001` | `counter_party_document_number` is not a valid CPF/CNPJ. |
| 400 | `QIT000001` | Invalid body (missing required field, wrong type or field not accepted). |

Authentication, permission and host errors: see [API errors](/documentation/iaas/introducao/erros).

---

# Settlement Retrieval

URL: /en/documentation/iaas/liquidacao_ativos/ativos/recuperacao

Returns a settlement of a payment batch by the `external_id` provided at insertion. Use it to check the settlement status or when the insertion returns a duplicate (`SET000013`).

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Read                |
| Consultant | `consultant-api` | View Batches        |
| Assignor   | `assignor-api`   | Read                |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}
METHOD GET

### Path params

| Parameter | Type | Description |
|---|---|---|
| `fund_class_key` | string | Fund key (UUID). |
| `external_id` | string | The `external_id` of the payment batch. |
| `settlement_external_id` | string | The `external_id` of the settlement, provided in the body of the [insertion](/documentation/iaas/liquidacao_ativos/ativos). |

## Response

STATUS 200

The object is the same one returned by the [settlement insertion](/documentation/iaas/liquidacao_ativos/ativos#response-attributes): the fields sent in the insertion body plus the data computed by QI Tech, with the current `status`.

```json title="Response Body"
{
    "asset_type": "ccb",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "settlement_type": "installment_settlement",
    "contract_number": "0123456789/ABC",
    "installment_number": 1,
    "collection_date": "2025-01-01",
    "collection_origin_type": "borrower",
    "asset_external_id": "CCB-0001",
    "assignor_document_number": "33.444.555/0001-81",
    "borrower_document_number": "969.698.790-03",
    "status": "settled",
    "type": "installment_settlement",
    "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890",
    "total_number_of_units": 1,
    "settlement_result": 0.0,
    "next_execution_datetime": "2025-01-01 13:00:00.000000",
    "counter_party_document_number": "969.698.790-03",
    "assets": [
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value": 130.50
        }
    ]
}
```

### Settlement status

| Status | Meaning |
|---|---|
| `validated` | Inserted and approved; awaiting payment of the batch. |
| `pending_validation` | Amount paid outside the tolerance; awaiting review by QI Tech. |
| `waiting_send_to_queue` / `on_queue` | Batch paid; settlement being processed in the fund's portfolio. |
| `settled` | Completed and reconciled in the portfolio. Final status. |
| `discarded` | Discarded, with no financial movement. Final status. The `denial_reason` field carries the reason, when there is one. |
| `inconsistent_asset` | The portfolio refused the payment due to an inconsistency in the asset. QI Tech handles the case; the batch does not reach `completed` while there is a settlement in this status. |

The complete map, with the statuses that trigger a webhook, is in [Settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook).

## Errors

| Status | Code | When it happens |
|---|---|---|
| 404 | `SET000011` | There is no settlement with this `settlement_external_id` in the given batch (or the batch does not exist in this fund). |
| 404 | `SET000005` | The `fund_class_key` does not exist. |
| 403 | `SET000028` | The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor). |

Authentication, permission and host errors: see [API Errors](/documentation/iaas/introducao/erros).

---

# Settlement Webhooks

URL: /en/documentation/iaas/liquidacao_ativos/ativos/webhook

Throughout settlement processing, the system sends webhooks to notify the integrating partner about status changes of each individual settlement. All webhooks have the type `settlement.settlement_status_change` and identify the settlement by the `settlement_external_id` provided at creation.

:::info Webhook configuration

To receive webhooks, you must have a callback URL configured with QI Tech. Contact [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) to set it up. The fund's manager and consultant receive the webhooks for all settlements; the assignor receives only those for settlements of assets it assigned.

:::

## Settlement status flow

Not every status change generates a webhook. Only three situations notify: completion (`settled`) and the outcome of a QI Tech review (`validated` or `discarded`). For the other statuses, use the [settlement retrieval](/documentation/iaas/liquidacao_ativos/ativos/recuperacao).

![Settlement status flow, highlighting the statuses that generate a webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook-en.svg)

_Reading the diagram: **dashed outline** = status without a webhook · **blue** = progress webhook · **green** = successful completion · **red** = notified discard._

| Status | When it happens | Webhook? |
|---|---|---|
| `validated` | At [insertion](/documentation/iaas/liquidacao_ativos/ativos), when the amount paid is within the tolerance. | No — it is the response of the insertion itself. |
| `pending_validation` | At insertion, when the amount paid differs from the expected amount beyond the tolerance. The settlement awaits review by QI Tech. | No — it is the response of the insertion itself. |
| `validated` (after review) | QI Tech approves a settlement that was in `pending_validation`. | **Yes** |
| `discarded` (after review) | QI Tech discards a settlement that was in `pending_validation` or `validated`, with the batch still open. | **Yes** |
| `waiting_send_to_queue` / `on_queue` | The batch was paid and the settlement is being sent to the fund's portfolio. | No |
| `settled` | The settlement was reconciled in the portfolio. Final success status. | **Yes** |
| `inconsistent_asset` | The portfolio rejected the payment due to an inconsistency in the asset. QI Tech handles the case and reprocesses it; the batch does not reach `completed` while any settlement is in this status. | No |
| `discarded` (without notice) | The batch was discarded (open settlements are discarded along with it), or the portfolio definitively rejected a zero-value settlement. | No — when the batch is discarded, the notice is the [batch webhook](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) with `discarded`. |

## Webhook structure

All settlement webhooks follow the same base structure:

| Field | Type | Description |
|---|---|---|
| `webhook_type` | string | Always `settlement.settlement_status_change`. |
| `webhook_datetime` | string | Event date and time in ISO 8601 format. |
| `data` | array | List with the event data. See the table below. |

#### Attributes of each object in `data`

Conditional fields are echoed directly from what was sent at settlement creation. The payload varies according to the `settlement_type` and the asset identification method used.

**Always present fields:**

| Field | Type | Description |
|---|---|---|
| `payment_batch_external_id` | string | The `external_id` of the payment batch. |
| `settlement_external_id` | string | The `external_id` of the settlement. |
| `settlement_status` | string | New settlement status. |
| `settlement_type` | string | Settlement type. |
| `total_value` | number | Total settlement amount in BRL. |
| `fund_class_document_number` | string | CNPJ of the associated fund. |
| `fund_class_key` | string | Fund key at QI Tech (UUID). |
| `asset_key` | string | Internal asset key at QI Tech (UUID). If the settlement affects more than one asset, it carries the first one. |

**Asset identification:**

| Field | Type | Description |
|---|---|---|
| `contract_number` | string | Contract number. Present if provided at creation; for CCBs and contracts, it is filled in from the portfolio even when not provided. |
| `asset_external_id` | string | Asset `external_id` in the partner's system. Present if provided at creation; for CCBs and contracts, it is filled in from the portfolio even when not provided. |

**Other fields echoed when provided:**

| Field | Type | Description |
|---|---|---|
| `if_code` | string | Financial instrument code (B3). Present if provided at settlement creation. |
| `participant_control_number` | string | Participant control number. Present if provided at settlement creation. |
| `source_document_number` | string | CPF or CNPJ of the financial counterparty. Present if provided at [batch creation](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). |
| `new_maturity_date` | string | New maturity date. Present in `asset_extension`. |

**Installment fields — present only for installment-based settlement types (`installment_*` and `gloss`):**

| Field | Type | Description |
|---|---|---|
| `installment_number` | integer | Installment number. |
| `installment_maturity_date` | string | Installment maturity date in `YYYY-MM-DD` format. Present when provided at creation. |
| `installment_external_id` | string | Installment `external_id`. Present when provided at creation. |

```json title="Standard webhook structure"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "STATUS",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "11.222.333/0001-81",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Events by status

### Settlement Completed

STATUS settled

Sent when the settlement is successfully processed and the amount has been properly reconciled in the fund's portfolio. This is the final status of a successful settlement — from this moment on, the financial movement is effective.

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "settled",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "11.222.333/0001-81",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Settlement Approved after Review

STATUS validated

Sent when QI Tech approves a settlement that was in `pending_validation`. The settlement proceeds to normal processing when the batch is paid. The payload has the same structure, with `settlement_status` equal to `validated`.

---

### Settlement Discarded

STATUS discarded

Sent when QI Tech discards a settlement after review — for example, a settlement in `pending_validation` whose amount is not confirmed. Discarded settlements do not generate financial movement.

Discards that happen along with the batch discard, or due to a definitive rejection by the portfolio for zero-value settlements, do **not** generate this webhook. See the [status map](#settlement-status-flow).

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "discarded",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "11.222.333/0001-81",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

---

# Asset settlement flow

URL: /en/documentation/iaas/liquidacao_ativos/fluxo_liquidacao

This page provides a holistic view of the settlement flow for assets already in the fund's portfolio: from payment batch creation to settlement completion and the portfolio update. Follow the evolution of the **batch statuses**, the **status of each settlement**, and the **webhooks** at each step.

:::tip How to use this flowchart

Hover over each step to see the endpoint details and access the full documentation. The colored tracks show simultaneously what happens to the batch, to each settlement, and which webhooks you will receive after processing.

:::

{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}

.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}

.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}

.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-num-ges{background:#d946ef}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}

.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}

.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}

.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}

.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}

html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9}
`}

## Legend

Integrating Agent
QI Tech (automatic)
Batch Status
Settlement Status
Webhook

## Flowchart

1
Payment batch creation
Integrating Agent
Creates a batch with a unique identifier ( external_id ) per fund, containing an optional credit account and other metadata.
Batch: pending_settlements_insertion
POST /settlement/fund_class/{fund_class_key}/payment_batch
The batch is ready to receive settlements.
View full documentation →

2
Settlement insertion
Integrating Agent
Inserts each settlement (installment, amortization, full settlement, etc.) into the batch. Repeat for every operation you need.
Batch: pending_settlements_insertion
Settlement: validated / pending_validation
POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
Each settlement receives validated or, if the amount paid differs from the expected amount beyond the tolerance, pending_validation (review by QI Tech; the result arrives by webhook). There is no way to remove an individual settlement: if needed, discard the batch and create another one.
View full documentation →

3
Batch closure
Integrating Agent
Signals that all settlements have been inserted and that processing can start — or discards the entire batch.
Batch: pending_payment / pending_validation / pending_discard
Settlement: validated
Process batch
pending_payment
The batch must contain at least one settlement. If any settlement is under review, the batch stays in pending_validation and moves on to pending_payment by itself when the review ends.
Discard batch
pending_discard → discarded
No settlement will be processed. The batch webhook with discarded confirms the end of the flow.
PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
Send {"batch_status": "pending_payment"} to close and process the batch, or {"batch_status": "discarded"} to discard it.
View full documentation →

4
Batch payment
QI Tech
QI Tech confirms the batch payment. The individual settlements are then processed and the settlement webhooks are sent.
Batch: paid
Webhook: payment_batch_status_change
Webhook settlement.payment_batch_status_change with status paid . Optionally, use the batch retrieval to track the batch.
GET /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
Optional query of the current batch status.
Batch webhooks →

5
Settlement completion
QI Tech
Each successfully processed settlement is reconciled in the fund's portfolio. This is the final success status per settlement. If the portfolio rejects the asset, the settlement stays in inconsistent_asset (no webhook) until QI Tech handles it.
Settlement: settled
Webhook: settlement_status_change
Webhook settlement.settlement_status_change with settlement_status settled for each completed settlement (after the batch payment).
View settlement webhooks documentation →

---

## Webhook Summary

The table below consolidates all webhooks of the settlement API:

| # | Webhook type | Status field | Value | Moment in the flow | Expected action |
|---|---|---|---|---|---|
| 1 | `settlement.payment_batch_status_change` | `status` | `paid` | After the batch payment is confirmed (step 4) | From this event on, the settlements are processed and the per-settlement webhooks start being sent. |
| 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Per settlement, after successful processing (step 5) | Settlement completed and reconciled in the portfolio. |
| 3 | `settlement.settlement_status_change` | `settlement_status` | `validated` | Per settlement, when QI Tech approves a settlement that was in `pending_validation` | None: the settlement follows the normal flow. |
| 4 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Per settlement, when QI Tech discards it after review | The settlement will not be processed. No financial movement is generated. |
| 5 | `settlement.payment_batch_status_change` | `status` | `completed` | After all settlements in the batch reach a final status (`settled` or `discarded`) | The batch cycle is closed. All settlements have been processed. |
| 6 | `settlement.payment_batch_status_change` | `status` | `discarded` | When the batch discard is completed (at the partner's request or by automatic discard of open batches) | No settlement in the batch will be processed. Open settlements are discarded without a webhook of their own. |

:::info Settlement webhook payload

The payload of the `settlement_status_change` webhook varies according to the data sent when the settlement was created:

- **Asset identification:** `contract_number` and `asset_external_id` appear when provided at creation; for CCBs and contracts, both are filled in from the portfolio.
- **Installment fields** (`installment_number`, `installment_maturity_date`, `installment_external_id`): present only for installment-based settlement types (`installment_*` and `gloss`).

For the full payload structure, see [Payment batch webhooks](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) and [Settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook).

:::

---

# Asset Settlement

URL: /en/documentation/iaas/liquidacao_ativos/inicio

This section documents the APIs that enable the Asset Settlement process for Investment Funds administered by QI DTVM. Through these APIs, you can record installment payments, amortizations, repurchases, and other settlement events for the assets in the fund's portfolio.

:::tip Context

The asset settlement described in this section applies exclusively to credit rights (CCBs, duplicatas, contracts, etc.) already included in the fund's portfolio. Treasury Bills, Debentures, and other fixed-income assets do not apply to this flow.

:::

:::info Prerequisites

- To access these services, contact [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) to enable the Sandbox and Production environments.
- You will need the `fund_class_key` (fund key), which is part of the base URL of every endpoint in this API:

```text
/settlement/fund_class/{fund_class_key}
```

:::

## How to submit the settlements

| Path | How it works | Where |
|---|---|---|
| **Through the API, settlement by settlement** | Payment batch creation, one request per settlement, and closing the batch. This is the flow detailed in this section | Integration API |
| **By file** | A single file with every settlement: **CNAB 444** or **CSV** | Manager/consultant portal |

:::tip Settlement by file

If you already receive the CNAB return file from the collecting bank, you can submit it directly. See [Settlement by File](/documentation/iaas/liquidacao_ativos/arquivo/inicio) and the [CNAB 444 Layout — Settlement](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa).

:::

## Settlement flow

The diagram below shows the main path, the branches and the resulting status of each step. Hover a node to see the endpoint and click to open its documentation.

<FlowDiagram
  columns={3}
  labels={{ you: 'Integrator', qitech: 'QI Tech', manager: 'Fund manager', docs: 'View documentation' }}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Payment Batch Creation',
      status: 'pending_settlements_insertion',
      desc: 'Container for all settlements that will be processed together, identified by a unique external_id.',
      endpoint: { method: 'POST', path: '/settlement/fund_class/{fund_class_key}/payment_batch' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao' },

    { id: 'insercao', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Settlement Insertion',
      status: 'settlement: validated or pending_validation',
      desc: 'One request per settlement, specifying asset type, amount, settlement type and identifiers.',
      endpoint: { method: 'POST', path: '.../payment_batch/{external_id}/settlement' },
      href: '/documentation/iaas/liquidacao_ativos/ativos' },

    { id: 'encerramento', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Batch Closure',
      desc: 'Sets batch_status. At least one settlement must have been inserted.',
      endpoint: { method: 'PUT', path: '.../payment_batch/{external_id}' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento' },

    { id: 'descartado', row: 4, col: 1, actor: 'you', tone: 'end',
      title: 'Batch discarded',
      status: 'discarded',
      desc: 'No settlement is processed and no financial movement is generated. Flow terminated.' },

    { id: 'pago', row: 4, col: 2, actor: 'qitech',
      title: 'Batch payment confirmed',
      status: 'paid',
      desc: 'QI Tech confirms the payment. From this event onwards the individual settlements start being processed.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },

    { id: 'processa', row: 5, col: 2, actor: 'qitech',
      title: 'Processing of each settlement',
      status: 'settlement: settled',
      desc: "Each settlement is reconciled in the fund's portfolio and notified individually via webhook.",
      href: '/documentation/iaas/liquidacao_ativos/ativos/webhook' },

    { id: 'conciliada', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Fund portfolio reconciled',
      status: 'completed',
      desc: 'All settlements reached a final status and the batch cycle is closed.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },
  ]}
  edges={[
    { from: 'criacao', to: 'insercao' },
    { from: 'insercao', to: 'encerramento' },
    { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' },
    { from: 'encerramento', to: 'pago', label: 'pending_payment', tone: 'ok' },
    { from: 'pago', to: 'processa', label: 'webhook' },
    { from: 'processa', to: 'conciliada', label: 'webhook' },
  ]}
/>

:::tip Full flow

For every status transition, the webhook payloads and the exception paths, see the [Asset Settlement Flow](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao).

:::

## Step by step

### 1. Payment Batch Creation

Create a payment batch with a unique identifier (`external_id`). The batch is the container for all settlements that will be processed together.

**[Access payment batch creation documentation](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)**

To check a batch that has already been created, use the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao).

### 2. Settlement Insertion

Add settlements to the created batch. Each settlement must be inserted individually, specifying the asset type, amount, settlement type, and required identifiers.

**[Access settlement insertion documentation](/documentation/iaas/liquidacao_ativos/ativos)**

There is no endpoint to remove an individual settlement. If a settlement was inserted by mistake, discard the batch at closure and create a new one. To check a settlement that has already been inserted, use the [settlement retrieval](/documentation/iaas/liquidacao_ativos/ativos/recuperacao).

### 3. Batch Closure

After inserting all settlements, close the batch to start internal processing. Cash reconciliation and the asset portfolio update are performed automatically. Alternatively, the same endpoint allows you to discard the entire batch — in that case no settlement is processed.

**[Access batch closure documentation](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)**

### 4. Tracking via Webhooks

Track progress through webhooks:
- **[Payment batch webhooks](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notifications about batch status.
- **[Settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notifications about the individual status of each settlement.

:::info Automatic processing

Cash reconciliation and the asset portfolio update are performed automatically by the API after batch closure.

:::

---

# Payment Batch Creation

URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao

This is the **first step** of the asset settlement flow. Creating the payment batch reserves a grouping into which the settlements to be processed will be inserted in the following steps.

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Write               |
| Consultant | `consultant-api` | Create Batches      |
| Assignor   | `assignor-api`   | Write               |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

:::info Prerequisites

Before creating a batch, you need the `fund_class_key` — the unique key of the fund in which the assets will be settled. This key is part of the endpoint used throughout this API:

```text
/settlement/fund_class/{fund_class_key}
```

For more details about the complete flow, see the [introduction page](/documentation/iaas/liquidacao_ativos/inicio).

:::

:::caution Attention

Each batch must have a **unique** `external_id` per fund.

If an error occurs, resend the request. A duplicate (`SET000009`) means the batch already exists: look it up through the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao) instead of recreating it. See [Retry and duplicates](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch
METHOD POST

```json title="Request Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    }
}
```

### Body attributes

| Field | Type | Required | Description |
|---|---|---|---|
| `external_id` | string | required | Unique identifier of this batch in the integrating partner's system. Maximum 50 characters. |
| `description` | string | optional | Settlement batch description. Maximum 255 characters. |
| `account` | object | optional | Data of the account where the settlement will be credited. When not provided, the settlement will be generated in the fund's main account. See [`account` attributes](#account-attributes). |
| `account_key` | string | optional | Key of the account where the settlement will be credited (UUID, 36 characters). Alternative to the `account` field. |
| `reference_date` | string | optional | Batch reference date in `YYYY-MM-DD` format. When omitted, the current date (Brasília time) applies. It cannot be earlier than the fund's current accounting date. |
| `end_to_end_id` | string | optional | End-to-end Pix identifier of the settlement's financial counterparty (32 characters, starting with `E`). |
| `source_document_number` | string | optional | CPF or CNPJ of the settlement's financial counterparty, with punctuation (e.g., `11.222.333/0001-81` or `969.698.790-03`). When omitted, it may be filled in with the default document from the fund's settlement configuration. |
| `settlement_expenses` | array | optional | Settlement expenses deducted in the batch, at most one per type. See [`settlement_expenses` attributes](#settlement_expenses-attributes). |

:::caution Attention

The `account` and `account_key` fields must not be sent together (`SET000034`). If neither is provided, the settlement will be generated in the fund's main account. The account must belong to the fund or have it as an authorized agent (`SET000032`).

:::

#### `account` attributes

| Field | Type | Required | Description |
|---|---|---|---|
| `account_number` | string | required | Account number. Maximum 20 characters. |
| `account_digit` | string | required | Account check digit. 1 character. |
| `account_branch` | string | required | Account branch. Maximum 4 characters. |
| `financial_institution_code` | string | required | Financial institution code. Maximum 20 characters. |

#### `settlement_expenses` attributes

| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | number | required | Expense amount. |
| `expense_type` | string | required | `bank_account` (bank expense) or `collection_agent_fee` (collection agent fee). |
| `description` | string | optional | Expense description. Maximum 255 characters. |

## Response

STATUS 201

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "payment_batch_automatic_discard": false
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_settlements_insertion",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}
```

### Response attributes

| Field | Type | Description |
|---|---|---|
| `external_id` | string | The same external key provided in the request. |
| `description` | string | Batch description. |
| `fund_class` | object | Data of the fund associated with the batch. See [`fund_class` attributes](#fund_class-attributes). |
| `payment_batch_key` | string | Unique batch identifier generated by QI Tech (UUID). |
| `status` | string | Initial batch status. Always returns `pending_settlements_insertion`, indicating that the batch is ready to receive settlements. |
| `reference_date` | string | Batch reference date in `YYYY-MM-DD` format. |
| `account_key` | string | Key of the account associated with the batch (UUID). |
| `settlement_expenses` | array | Settlement expenses created, with `settlement_expense_key`, `amount`, `status`, `description` and `type`. Present only when provided. |

The response also echoes the other fields sent in the body (for example `account`, `source_document_number`, `end_to_end_id`).

#### `fund_class` attributes

| Field | Type | Description |
|---|---|---|
| `name` | string | Fund name. |
| `manager` | object | Fund manager data. See [`manager` attributes](#manager-attributes). |
| `fund_class_key` | string | Unique fund key (UUID). |
| `document_number` | string | Fund CNPJ. |
| `accounting_date` | string | Current accounting date of the fund, in `YYYY-MM-DD` format. |
| `payment_batch_automatic_discard` | boolean | Indicates whether the fund automatically discards batches left open. |

#### `manager` attributes

| Field | Type | Description |
|---|---|---|
| `name` | string | Manager name. |
| `manager_key` | string | Unique manager key (UUID). |
| `document_number` | string | Manager CNPJ. |

## Next steps

After creating the batch, the flow continues with:

1. **[Settlement insertion](/documentation/iaas/liquidacao_ativos/ativos)** — add the settlements (installment payments, amortizations, etc.) to the batch.
2. **[Batch closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — signal that all settlements have been inserted so that processing can begin.

## Errors

| Status | Code | When it happens |
|---|---|---|
| 409 | `SET000009` | A batch with this `external_id` already exists in the fund. Look it up instead of recreating it. |
| 404 | `SET000005` | The `fund_class_key` does not exist. |
| 403 | `SET000028` | The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor). |
| 400 | `SET000044` | `reference_date` is earlier than the fund's current accounting date. |
| 404 | `SET000031` | The account provided (`account_key` or `account`) was not found. |
| 400 | `SET000032` | The account provided does not belong to the fund. |
| 400 | `SET000034` | `account` and `account_key` sent together. |
| 403 | `SET000085` | Escrow account not authorized to operate for this fund. |
| 400 | `SET000001` | `source_document_number` is not a valid CPF/CNPJ. |
| 400 | `SET000050` / `SET000051` | Invalid `expense_type`, or more than one expense of the same type. |
| 400 | `QIT000001` | Invalid body (missing required field, invalid format or field not accepted). |

Authentication, permission and host errors: see [API errors](/documentation/iaas/introducao/erros).

---

# Close Payment Batch Insertion

URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento

After inserting all desired settlements into the batch, use this endpoint to signal that insertion is complete and processing can begin. You can also discard the entire batch.

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Write               |
| Consultant | `consultant-api` | Create Batches      |
| Assignor   | `assignor-api`   | Write               |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

:::tip Where am I in the flow?

This is the **3rd step** of the settlement flow. Before this step, you must have:

1. [Created the payment batch](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
2. [Inserted the settlements](/documentation/iaas/liquidacao_ativos/ativos)

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
METHOD PUT

### Path params

| Parameter | Type | Description |
|---|---|---|
| `external_id` | string | The `external_id` provided when creating the batch. |

```json title="Request Body"
{
    "batch_status": "pending_payment"
}
```

### Body attributes

| Field | Type | Required | Description |
|---|---|---|---|
| `batch_status` | string | required | Status to which the batch will be updated. See the [enumerators](#batch_status-enumerators) below. |

#### `batch_status` enumerators

| Value | Description |
|---|---|
| `pending_payment` | Closes insertion and starts batch processing. Accepted only with the batch in `pending_settlements_insertion` and at least one settlement in `validated` or `pending_validation`. |
| `discarded` | Discards the entire batch. No settlement will be processed. Accepted with the batch in `pending_settlements_insertion`, `pending_validation` or `pending_payment`. |

## Response

STATUS 200

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_payment"
}
```

### Response attributes

| Field | Type | Description |
|---|---|---|
| `external_id` | string | External batch key provided by the partner. |
| `status` | string | New batch status. See below. |

**Returned status:**

| You sent | Returned status | What it means |
|---|---|---|
| `pending_payment` | `pending_payment` | Batch closed; awaiting payment confirmation. |
| `pending_payment` | `pending_validation` | There are settlements under review by QI Tech. When the review ends, the batch moves on to `pending_payment` by itself. |
| `discarded` | `pending_discard` or `pending_discard_on_cash_account` | Discard in progress. The final status `discarded` arrives through the [batch webhook](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook). |

## Next steps

After closing the batch, processing starts automatically. Track the result through webhooks or the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao):

1. **[Payment batch webhooks](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notification when the batch is paid, completed or discarded.
2. **[Settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — individual notification for each processed settlement.

## Errors

| Status | Code | When it happens |
|---|---|---|
| 404 | `SET000005` | The `fund_class_key` does not exist. |
| 403 | `SET000028` | The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor). |
| 404 | `SET000010` | The batch given in the URL does not exist in this fund. |
| 400 | `SET000026` | `batch_status` other than `pending_payment` or `discarded`. |
| 400 | `SET000049` | Closure request for a batch already in `pending_payment`, `paid` or `completed`. |
| 400 | `SET000016` | Closure request for a batch outside `pending_settlements_insertion` (for example, in `pending_validation` or being discarded). |
| 400 | `SET000017` | The batch has no settlement in `validated` or `pending_validation`. |
| 400 | `SET000069` | Discard request for a batch already in a final status (`paid`, `completed` or `discarded`). |

Authentication, permission and host errors: see [API errors](/documentation/iaas/introducao/erros).

---

# Payment Batch Listing

URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem

Paginated query endpoint that returns the payment batches of a given fund class. Use the available filters to search batches by status or reference date. To look up a specific batch by its `external_id`, use the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao).

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Read                |
| Consultant | `consultant-api` | View Batches        |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches
METHOD GET

### Query params

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | optional | Filters by a specific batch status. See the [status enumerators](#batch-status-enumerators). |
| `reference_date` | string | optional | Filters by reference date in `YYYY-MM-DD` format. |
| `page` | integer | optional | Page number (starts at 0). Default: `0`. |
| `limit` | integer | optional | Number of records per page. Default: `10`. Maximum: `50`. |

```text title="Example call"
GET /settlement/fund_class/{fund_class_key}/payment_batches?status=completed&reference_date=2025-01-01&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "description": "LOTE DE LIQUIDAÇÃO 08/08",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                "manager": {
                    "name": "EXEMPLO CAPITAL",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "22.333.444/0001-81"
                },
                "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451",
                "document_number": "11.222.333/0001-81",
                "accounting_date": "2025-08-08",
                "payment_batch_automatic_discard": false
            },
            "payment_batch_key": "50859e88-544c-4c79-a7aa-d373d90aa571",
            "status": "completed",
            "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434",
            "reference_date": "2025-08-08",
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
            "total_value": 143.18
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": false
}
```

### Response attributes

| Field | Type | Description |
|---|---|---|
| `data` | array | List of payment batch objects. See the table below. |
| `page` | integer | Current page number. |
| `limit` | integer | Number of records per page. |
| `is_last_page` | boolean | Indicates whether this is the last page of results. |

#### Attributes of each batch (objects within `data`)

| Field | Type | Description |
|---|---|---|
| `description` | string | Batch description. |
| `fund_class` | object | Data of the fund associated with the batch. See the [`fund_class` attributes](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao#fund_class-attributes) on the Creation page. |
| `payment_batch_key` | string | Unique batch identifier (UUID). |
| `status` | string | Current batch status. See the [status enumerators](#batch-status-enumerators) below. |
| `external_id` | string | External key provided by the partner. |
| `reference_date` | string | Reference date in `YYYY-MM-DD` format. |
| `account_key` | string | Key of the account associated with the batch (UUID). |
| `total_value` | number | Total value of the batch settlements in BRL. May not be present if the batch has not been processed yet. |

## Batch status enumerators

| Status | Description |
|---|---|
| `pending_settlements_insertion` | Batch created, awaiting settlement insertion. |
| `pending_validation` | Batch closed with settlements under review by QI Tech. |
| `pending_payment` | Batch closed, awaiting payment processing. |
| `paid` | Batch payment made; settlements being processed. |
| `completed` | All settlements reached `settled` or `discarded`. |
| `pending_discard` | Discard requested, in progress. |
| `pending_discard_on_cash_account` | Discard requested, awaiting cancellation in the cash account. |
| `discarded` | Batch discarded. |

Batches also include `settlement_expenses` when there are settlement expenses, and echo the fields sent at creation. See the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao#atributos-da-resposta).

## Errors

| Status | Code | When it happens |
|---|---|---|
| 404 | `SET000005` | The `fund_class_key` does not exist. |
| 403 | `SET000028` | The fund does not belong to your profile. |

Authentication, permission and host errors: see [API errors](/documentation/iaas/introducao/erros).

---

# Payment Batch Retrieval

URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao

Returns a payment batch by the `external_id` provided at creation. Use it to track the batch status or when the creation returns a duplicate (`SET000009`).

:::info Available on

| Profile    | Host             | Required permission |
| ---------- | ---------------- | ------------------- |
| Manager    | `manager-api`    | Read                |
| Consultant | `consultant-api` | View Batches        |
| Assignor   | `assignor-api`   | Read                |

Base URL for each host: [Environments (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
METHOD GET

### Path params

| Parameter | Type | Description |
|---|---|---|
| `fund_class_key` | string | Fund key (UUID). |
| `external_id` | string | The `external_id` provided at the [batch creation](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). Also accepts the `payment_batch_key` returned by QI Tech. |

## Response

STATUS 200

The response echoes the fields sent at batch creation (for example `account`, `source_document_number`, `end_to_end_id`) and adds the data below.

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    },
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "payment_batch_automatic_discard": false
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_payment",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
    "total_value": 4520.75,
    "settlement_expenses": [
        {
            "settlement_expense_key": "0b6f3c1e-8f0a-4c55-9a4e-2f1d7c9e3b10",
            "amount": 15.00,
            "status": "pending_submission",
            "description": "Despesa de Liquidação - Despesa Bancária",
            "type": "bank_account"
        }
    ]
}
```

### Response attributes {#atributos-da-resposta}

| Field | Type | Description |
|---|---|---|
| `external_id` | string | External key of the batch provided by the partner. |
| `description` | string | Batch description. When not provided at creation, it is generated as `Lote de Pagamento - {reference_date} - {external_id}`. |
| `fund_class` | object | Fund data: `name`, `manager` (`name`, `manager_key`, `document_number`), `fund_class_key`, `document_number`, `accounting_date` (the fund's current accounting date) and `payment_batch_automatic_discard`. |
| `payment_batch_key` | string | Unique batch identifier generated by QI Tech (UUID). |
| `status` | string | Current batch status. See below. |
| `reference_date` | string | Reference date of the batch, in `YYYY-MM-DD` format. |
| `account_key` | string | Key of the account associated with the batch (UUID). |
| `total_value` | number | Total value of the batch. Present once the total has been computed. |
| `settlement_expenses` | array | Settlement expenses provided at creation, with `settlement_expense_key`, `amount`, `status`, `description` and `type`. Present only when there are expenses. |

### Batch status

| Status | Meaning |
|---|---|
| `pending_settlements_insertion` | Batch created, accepting settlements. |
| `pending_validation` | Batch closed with settlements under review by QI Tech. At the end of the review, it moves to `pending_payment`. |
| `pending_payment` | Batch closed, awaiting payment confirmation. |
| `paid` | Payment confirmed; the settlements are being processed. |
| `completed` | All settlements reached `settled` or `discarded`. Final status. |
| `pending_discard` / `pending_discard_on_cash_account` | Discard requested, in progress. |
| `discarded` | Batch discarded. Final status. |

## Errors

| Status | Code | When it happens |
|---|---|---|
| 404 | `SET000010` | There is no batch with this `external_id` (nor with this `payment_batch_key`) in the fund. |
| 404 | `SET000005` | The `fund_class_key` does not exist. |
| 403 | `SET000028` | The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor). |

Authentication, permission and host errors: see [API Errors](/documentation/iaas/introducao/erros).

---

# Payment Batch Webhooks

URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook

Throughout the settlement flow, the system sends webhooks to notify the integrating partner about payment batch status changes. All webhooks have the type `settlement.payment_batch_status_change` and identify the batch by the `external_id` provided at creation.

:::info Webhook configuration

To receive webhooks, you must have a callback URL configured with QI Tech. Contact [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) to set it up.

:::

## Payment batch status flow

The batch moves through the statuses below until it closes. Only three generate a webhook: `paid`, `completed` and `discarded`. The others — `pending_settlements_insertion`, `pending_validation`, `pending_payment`, `pending_discard` and `pending_discard_on_cash_account` — result from your [creation](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) and [closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) calls, or from internal steps, and do **not** trigger a notification. To track them, use the [batch retrieval](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao).

![Payment batch status flow, highlighting the three statuses that generate a webhook](/img/diagrams/iaas-liquidacao-ativos-lote-pagamento-webhook-en.svg)

_Reading the diagram: **dashed outline** = status without a webhook · **blue** = progress webhook · **green** = successful closing · **red** = closed without processing._

| Status | When it happens | Webhook? |
|---|---|---|
| `pending_settlements_insertion` | Batch created, accepting settlements. | No |
| `pending_validation` | Batch closed with settlements under review by QI Tech. When the review ends, it moves on to `pending_payment` by itself. | No |
| `pending_payment` | Batch closed, awaiting payment confirmation. | No |
| `paid` | Payment confirmed; the settlements start being processed. | **Yes** |
| `completed` | All settlements reached `settled` or `discarded`. A settlement in `inconsistent_asset` holds the batch in `paid` until it is handled. | **Yes** |
| `pending_discard` / `pending_discard_on_cash_account` | Requested (or automatic) discard in progress. | No |
| `discarded` | Batch discarded. | **Yes** |

## Webhook structure

All payment batch webhooks follow the same structure:

| Field | Type | Description |
|---|---|---|
| `webhook_type` | string | Always `settlement.payment_batch_status_change`. |
| `webhook_datetime` | string | Event date and time in ISO 8601 format. |
| `data` | object | Event data. See the table below. |

#### `data` attributes

| Field | Type | Description |
|---|---|---|
| `external_id` | string | Batch identifier. See [How the `external_id` is formed](#how-the-external_id-is-formed). |
| `status` | string | New batch status. |
| `fund_class_document_number` | string | CNPJ of the fund associated with the batch. |
| `fund_class_key` | string | Fund key at QI Tech (UUID). |
| `payment_batch_key` | string | Unique batch identifier generated by QI Tech (UUID). |
| `reference_date` | string | Batch reference date, in `YYYY-MM-DD` format. |
| `total_value` | number | Total batch value in BRL. Present once the total is computed, at batch closure — that is, in the `paid` and `completed` webhooks. |
| `description` | string | Batch description. Present when the batch has a description. |

```json title="Standard webhook structure"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "11.222.333/0001-81",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## How the `external_id` is formed

The `external_id` is the correlation key between the batch at QI DTVM and your own records. Where the value comes from depends on how the batch was created:

| Batch origin | `external_id` value |
|---|---|
| [Creation via API](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) | Exactly the `external_id` you provided in the request body. |
| Settlement file sent via SFTP | The file name **without the extension**. |

:::info Batches created from a settlement file

The webhook **does not carry a field with the file name**. To correlate the event with the file you sent, compare the `external_id` with the file name without its extension:

| File sent | Batch `external_id` |
|---|---|
| `liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |
| `CNAB_BAIXAS_liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |

As the second row shows, the `CNAB_BAIXAS_` prefix, when present, is also removed.

The return file listing the inconsistencies found during processing, when generated, follows the same convention — `retorno_liquidacoes_20260811_001.csv`.

:::

---

## Events by status

### Batch Paid

STATUS paid

Sent when the batch payment is confirmed by QI Tech. From this point on, the individual settlements are processed in sequence and the respective [settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook) are sent as each one is completed.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "paid",
        "fund_class_document_number": "11.222.333/0001-81",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Batch Completed

STATUS completed

Sent when all batch settlements have reached a final status (`settled` or `discarded`). This is the terminal status of the batch after the successful completion of the settlement cycle. Upon receiving this event, the integrating partner can consider the batch fully processed.

To identify which batch the event refers to, use the `external_id` — see [How the `external_id` is formed](#how-the-external_id-is-formed).

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "completed",
        "fund_class_document_number": "11.222.333/0001-81",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Batch Discarded

STATUS discarded

Sent when the batch discard is completed. This happens:

- at the integrating partner's request at [batch closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`); or
- by automatic discard, in funds configured for it: batches still in `pending_settlements_insertion`, `pending_validation` or `pending_payment` when the fund's accounting date advances are discarded.

When the batch was already in `pending_payment` with a computed value, the discard first goes through cancelling the expected entry in the cash account (`pending_discard_on_cash_account`). No settlement associated with the batch will be processed after this status, and open settlements are discarded without a webhook of their own.

When the batch is discarded before closure, the total value is never computed and the `total_value` field is not included in the payload.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "discarded",
        "fund_class_document_number": "11.222.333/0001-81",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```