# 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 9 página(s). Índice: - Settlement Insertion (/en/documentation/iaas/liquidacao_ativos/ativos/) - Settlement Removal (/en/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) - 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 Webhooks (/en/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) --- # 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 (total or partial) for an asset in the fund's portfolio — such as installment settlement, amortization, repurchase, or interest payment. :::info Settlement vs Repurchase Both asset settlement and repurchase are performed through this endpoint. The `collection_origin_type` field differentiates the two operations: - `borrower` — for **settlements** (payment made by the drawer/debtor). - `assignor` — for **repurchases** (payment made by the assignor). ::: :::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). ::: ## 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 (two decimal places). | | `external_id` | string | required | Unique identifier for this settlement 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 | Determines whether the operation is a settlement (`borrower`) or repurchase (`assignor`). See [`collection_origin_type` enumerators](#collection_origin_type-enumerators). | | `contract_number` | string | optional | Contract number associated with the asset. Maximum 50 characters. | | `asset_external_id` | string | optional | Unique identifier for the asset in the system, provided during 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 during assignment. Maximum 50 characters. | | `installment_number` | integer | optional | Installment number to be paid. Required for installment-based settlement types. | | `installment_maturity_date` | string | optional | Installment maturity date in `YYYY-MM-DD` format. | | `installment_external_id` | string | optional | External identifier for the installment. Maximum 50 characters. | | `collection_date` | string | optional | Payment date in `YYYY-MM-DD` format. Field intended for integrator control. | :::caution Attention The fields `asset_external_id`, `contract_number`, and `asset_key` are alternative ways to identify the asset in the system. Provide **only one** of them — do not send multiple simultaneously. ::: :::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_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 | | `structured_cci` | Structured Real Estate Credit Note | | `duplicata_mercantil` | Commercial Invoice | | `duplicata_servicos` | Service Invoice | | `discounted_contract` | Contract | **`settlement_type` enumerators:** | Value | Description | |---|---| | `asset_settlement` | Full asset settlement. | | `asset_amortization` | Asset amortization (grace period). | | `fine_payment` | Asset interest or late fee payment. | | `installment_settlement` | Installment settlement. `installment_number` required. | | `installment_amortization` | Installment amortization. `installment_number` required. | | `installment_fine_payment` | Installment interest or late fee payment. `installment_number` required. | | `gloss` | Installment write-off. `installment_number` required. | **`collection_origin_type` enumerators:** | Value | Description | |---|---| | `borrower` | Settlement — payment made by the drawer/debtor. | | `assignor` | Repurchase — payment made by the assignor. | ## Response STATUS 201 ```json title="Response Body" { "status": "validated", "total_value": 130.50, "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "installment_number": 1, "settlement_result": 0.0, "total_number_of_units": 1, "collection_origin_type": "borrower", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Response attributes | Field | Type | Description | |---|---|---| | `status` | string | Settlement status. After successful insertion, returns `validated`. | | `total_value` | number | Total payment amount. | | `external_id` | string | External settlement key provided by the partner. | | `type` | string | Settlement type. | | `settlement_key` | string | Unique settlement identifier generated by QI Tech (UUID). | | `installment_number` | integer | Installment number. Present when applicable. | | `settlement_result` | number | Settlement result. Present when calculated. | | `total_number_of_units` | integer | Total number of asset units affected by the settlement. | | `collection_origin_type` | string | Collection origin type (`borrower` or `assignor`). Present when provided in the request. | | `assets` | array | List of assets affected by the settlement. See [Assets attributes](#assets-attributes). | #### Assets attributes | Field | Type | Description | |---|---|---| | `asset_key` | string | Unique asset identifier (UUID). | | `number_of_units` | integer | Number of asset units. | | `present_value` | number | Current asset value in BRL. | | `installment_face_value` | number | Installment face value. Present when applicable. | | `installment_post_maturity_interest_value` | number | Post-maturity interest value for the installment. Present when applicable. | | `installment_delay_interest_value` | number | Late interest value for the installment. Present when applicable. | | `installment_delay_fine_value` | number | Late fine value for the installment. Present when applicable. | ## Possible errors STATUS 404 **Payment batch not found** The `external_id` of the batch provided in the URL does not match any batch registered for this fund. Verify that the identifier is correct. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Duplicate external_id settlement** A settlement with the provided `external_id` already exists in this batch. Each settlement must have a unique identifier. Generate a new `external_id` and try again. ```json { "title": "Already Exists Settlement With External Id", "description": "The settlement with external_id {settlement_external_id} in payment batch with external id {payment_batch_external_id} already exists", "translation": "a liquidação com identificador {settlement_external_id} no lote de identificador {payment_batch_external_id} já existe", "code": "SET000013" } ``` ## 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. --- # Settlement Removal URL: /en/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes Endpoint to discard an individual settlement previously inserted into a payment batch. Only settlements in batches that have not yet been closed can be removed. :::tip When to use Use this endpoint when you need to remove an incorrect or unwanted settlement before [closing the batch](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento). After the batch is closed, individual settlements cannot be removed. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} METHOD PUT ### Path params | Parameter | Type | Description | |---|---|---| | `external_id` | string | The `external_id` of the payment batch. | | `settlement_external_id` | string | The `external_id` of the settlement to be discarded. | ```json title="Request Body" { "status": "discarded" } ``` ### Body attributes | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | New settlement status. To discard, send `discarded`. | ## Response STATUS 200 ```json title="Response Body" { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "discarded" } ``` ### Response attributes | Field | Type | Description | |---|---|---| | `external_id` | string | External settlement key provided by the partner. | | `status` | string | New settlement status: `discarded`. | ## Possible errors STATUS 404 **Settlement not found** The `settlement_external_id` provided in the URL does not match any settlement registered in this batch. Verify that the batch and settlement identifiers are correct. ```json { "title": "Settlement not found", "description": "The Settlement with external_id {external_id} was not found", "translation": "A Liquidação com identificador externo {external_id} não foi encontrada", "code": "SET000011" } ``` STATUS 400 **Invalid status** The value provided in the `status` field is not valid. For removal, use only `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Batch already closed** The payment batch has already been closed and no longer allows changes to settlements. It is not possible to remove settlements from batches that have passed the `pending_settlements_insertion` status. ```json { "title": "Payment Batch Status mismatch", "description": "Payment batch of key: {payment_batch_key} with status: {current} was expected to be: {expected}", "translation": "O lote de pagamento com chave: {payment_batch_key} e com status: {current} não passou, era esperado que fosse: {expected}", "code": "SET000016" } ``` STATUS 400 **Incompatible settlement status** The settlement is in a status that does not allow it to be discarded. Only settlements with `validated` status can be removed. ```json { "title": "Settlement type mismatch", "description": "The settlement given has the status: {current_status} and was expected: {expected_status}", "translation": "A liquidação com status: {current_status} era esperado ter: {expected_status}", "code": "SET000024" } ``` --- # Settlement Webhooks URL: /en/documentation/iaas/liquidacao_ativos/ativos/webhook Throughout the settlement processing, the system sends webhooks to notify the integrating partner about status changes for 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 configure. ::: ## Statuses with webhook The diagram below shows the three statuses that generate webhooks to the integrating partner: ```mermaid graph LR A([validated]) -->|Successfully processed| B([settled]) A -->|Discarded| C([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 event data. See table below. | #### Attributes of each object in `data` Conditional fields are echoed directly from what was sent during 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. | | `asset_key` | string | Internal asset key at QI Tech (UUID). | **Asset identification — only one of the fields below will be present, according to what was provided at creation:** | Field | Type | Description | |---|---|---| | `contract_number` | string | Contract number. Present if provided at creation. | | `asset_external_id` | string | Asset `external_id` in the partner's system. Present if provided at creation. | **Installment fields — present only for installment-based settlement types (`installment_settlement`, `installment_amortization`, `installment_fine_payment`, `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": "60.910.091/0001-24", "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, 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": "60.910.091/0001-24", "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 Discarded STATUS discarded Sent when the settlement is discarded from the processing flow. Discarded settlements do not generate financial movement. There are three situations that cause this status: 1. **Manual removal before batch closure** — the integrating partner removes the settlement via the [settlement removal](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) endpoint while the batch is still open. 2. **Internal discard after review** — the QI Tech team discards a settlement that was under manual review (`pending_validation`), for example due to data inconsistency. 3. **Rejection** — during processing, the fund's portfolio returns a definitive rejection for a settlement with zero value. In these cases, the system determines that reprocessing the settlement would produce the same result and discards it. ```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": "60.910.091/0001-24", "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 asset settlement flow for assets already in the fund's portfolio: from payment batch creation to settlement completion and portfolio update. Follow the evolution of **batch statuses**, **individual settlement statuses**, and **webhooks** at each step. :::tip How to use this flowchart Hover over each step to see endpoint details and access the full documentation. The colored tracks show simultaneously what happens to the batch, 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 Integration Agent QI Tech (automatic) Batch Status Settlement Status Webhook ## Flowchart 1 Payment batch creation Integration Agent Creates a batch with a unique identifier ( external_id ) per fund, with 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 Integration Agent Inserts each settlement (installment, amortization, full settlement, etc.) into the batch. Repeat for all desired operations. Batch: pending_settlements_insertion Settlement: validated POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement Each settlement receives status validated after successful insertion. No webhook is sent at this point; webhooks are sent after closure and processing. View full documentation → 3 Settlement removal (optional) Integration Agent Before closing the batch, you can discard a settlement inserted by mistake. Only settlements with validated status can be removed. Batch: pending_settlements_insertion Settlement: validated Removed a settlement discarded The settlement will not be included in processing. Not applicable Skip this step if you do not need to remove any settlement. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} Body: {"status": "discarded"} . After batch closure, individual settlements cannot be removed. View full documentation → 4 Batch closure Integration Agent Signals that all settlements have been inserted (and adjusted) and that processing can begin — or discards the entire batch. Batch: pending_payment / discarded Settlement: validated (or discarded) Process batch pending_payment At least one settlement must be in the batch. Discard batch discarded No settlements will be processed. Flow ended. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} Send {"batch_status": "pending_payment"} to close and process, or {"batch_status": "discarded"} to discard the batch. View full documentation → 5 Batch payment QI Tech QI Tech confirms the batch payment. Individual settlements are then processed and settlement webhooks are triggered. Batch: paid Webhook: payment_batch_status_change Webhook settlement.payment_batch_status_change with status paid . Optionally, use the batch listing to monitor the batch. GET /settlement/fund_class/{fund_class_key}/payment_batches Optional query to track the batch by status or reference date. Batch webhooks → 6 Settlement completion QI Tech Each successfully processed settlement is reconciled in the fund's portfolio. This is the final success status per settlement. Settlement: settled Webhook: settlement_status_change Webhook settlement.settlement_status_change with settlement_status settled for each completed settlement (after batch payment). View settlement webhook documentation → --- ## Webhook Summary The table below consolidates all webhooks from the settlement API: | # | Webhook Type | Status Field | Value | Point in Flow | Expected Action | |---|---|---|---|---|---| | 1 | `settlement.payment_batch_status_change` | `status` | `paid` | After batch payment confirmation (step 5) | From this event onward, settlements are processed and per-settlement webhooks begin to be sent. | | 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Per settlement, after successful processing (step 6) | Settlement completed and reconciled in the portfolio. | | 3 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Per settlement, when discarded by manual removal, internal discard, or permanent portfolio rejection | Settlement will not be processed. No financial movement is generated. | | 4 | `settlement.payment_batch_status_change` | `status` | `completed` | After all batch settlements reach a final status (`settled` or `discarded`) | The batch cycle is closed. All settlements have been processed. | | 5 | `settlement.payment_batch_status_change` | `status` | `discarded` | When the batch is discarded (by partner request, automatic discard, or cash account cancellation failure) | No settlements in the batch will be processed. | :::info Settlement Webhook Payload The `settlement_status_change` webhook payload varies according to the data sent when creating the settlement: - **Asset identification:** only one of the fields `contract_number` or `asset_external_id` will be present, depending on the identification method used during creation. Never both simultaneously. - **Installment fields** (`installment_number`, `installment_maturity_date`, `installment_external_id`): present only for installment-based settlement types — `installment_settlement`, `installment_amortization`, `installment_fine_payment`, and `gloss`. Absent for full asset types (`asset_settlement`, `asset_amortization`, `fine_payment`). For the complete 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 CTVM. Through these APIs, it is possible to record installment payments, amortizations, repurchases, and other settlement events for assets in the fund's portfolio. :::tip Context The asset settlement described in this section applies exclusively to credit rights (CCBs, invoices, 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 access to the Sandbox (Staging) and Production environments. - You will need the `fund_class_key` (fund key), which is part of the base URL for all endpoints in this API: ``` /settlement/fund_class/{fund_class_key} ``` ::: ## 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. :::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)** ### 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)** While the batch has not been closed, a settlement inserted by mistake can be removed. **[Access settlement removal documentation](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)** ### 3. Batch Closure After inserting all settlements, close the batch to start internal processing. Cash reconciliation and portfolio update will be 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)** — individual status notifications for each settlement. :::info Automatic Processing Cash reconciliation and 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 where the settlements to be processed will be inserted in subsequent steps. :::info Prerequisites Before creating a batch, you need the `fund_class_key` — the unique fund key in which assets will be settled. This key is part of the endpoint used throughout this API: ``` /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. The system will not allow the creation of two batches with the same identifier. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch METHOD POST ```json title="Request Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAYMENTS - 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 for 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 | Settlement reference date in `YYYY-MM-DD` format. | | `end_to_end_id` | string | optional | End-to-end PIX identifier of the financial counterpart of the settlement. Maximum 32 characters. | | `source_document_number` | string | optional | CPF or CNPJ of the financial counterpart of the settlement, with punctuation (e.g., `12.345.678/0001-90` or `123.456.789-00`). | :::caution Attention The `account` and `account_key` fields must not be passed simultaneously. If neither is provided, the settlement will be generated in the fund's main account. Account information must refer to an account belonging to the fund. ::: #### 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. | ## Response STATUS 201 ```json title="Response Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAYMENTS - ABC - 2025-01-01", "fund_class": { "name": "CREDIT RIGHTS INVESTMENT FUND", "manager": { "name": "EXAMPLE CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "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 the batch is ready to receive settlements. | | `reference_date` | string | Settlement reference date in `YYYY-MM-DD` format. | | `account_key` | string | Key of the account associated with the batch (UUID). | #### 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. | #### manager attributes | Field | Type | Description | |---|---|---| | `name` | string | Manager name. | | `manager_key` | string | Unique manager key (UUID). | | `document_number` | string | Manager CNPJ. | ## Possible errors STATUS 404 **Fund not found** The `fund_class_key` provided in the URL does not match any registered fund. Verify that the key is correct. ```json { "title": "Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.", "code": "SET000005" } ``` STATUS 409 **Duplicate External ID** A batch with the provided `external_id` already exists. Each batch must have a unique identifier. Generate a new `external_id` and try again. ```json { "title": "Payment batch external id already exists", "description": "The Payment Batch with external id {payment_batch_external_id} already exists", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe", "code": "SET000009" } ``` STATUS 400 **Accounting date mismatch** The batch is being created on a date different from the fund's current accounting date. Verify the fund's accounting date and try again. ```json { "title": "Bad Request", "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}", "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}", "code": "SET000044" } ``` STATUS 404 **Account not found** The `account_key` provided does not match any registered account. Verify that the key is correct and that the account belongs to the fund. ```json { "title": "Account not found", "description": "The account with key ({account_key}) was not found.", "translation": "A conta com chave({account_key}) não foi encontrada.", "code": "SET000009" } ``` ## Next steps After creating the batch, the flow continues with: 1. **[Settlement insertion](/documentation/iaas/liquidacao_ativos/ativos)** — add 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. --- # 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. :::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 [enumerators](#batch_status-enumerators) below. | **`batch_status` enumerators:** | Value | Description | |---|---| | `pending_payment` | Closes insertion and starts batch processing. | | `discarded` | Discards the entire batch. No settlements will be processed. | ## 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. | ## Possible errors STATUS 404 **Batch not found** The `external_id` provided in the URL does not match any batch registered for this fund. Verify that the identifier is correct. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Invalid status** The value provided in the `batch_status` field is not valid. Use only `pending_payment` or `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Batch with no settlements** You attempted to close the batch, but it has no settlements inserted yet. You must [insert at least one settlement](/documentation/iaas/liquidacao_ativos/ativos) before closing the batch. ```json { "title": "Payment Batch with no settlement", "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled", "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações", "code": "SET000017" } ``` ## Next steps After closing the batch, processing starts automatically. Track the result through webhooks: 1. **[Payment batch webhooks](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notification when the batch is paid. 2. **[Settlement webhooks](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — individual notification for each processed settlement. --- # Payment Batch Listing URL: /en/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem Paginated query endpoint that returns payment batches for a given fund class. Use the available filters to search batches by status or reference date. ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches METHOD GET ### Query params | Parameter | Type | Required | Description | |---|---|---|---| | `status` | string | optional | Filter by a specific batch status. See [status enumerators](#batch-status-enumerators). | | `reference_date` | string | optional | Filter 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`. | ```python 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": "SETTLEMENT BATCH 08/08", "fund_class": { "name": "CREDIT RIGHTS INVESTMENT FUND", "manager": { "name": "EXAMPLE CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451", "document_number": "60.910.091/0001-24" }, "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 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 [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 [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 batch settlements in BRL. May not be present if the batch has not yet been processed. | ## Batch status enumerators | Status | Description | |---|---| | `pending_settlements_insertion` | Batch created, awaiting settlement insertion. | | `pending_payment` | Batch closed, awaiting payment processing. | | `paid` | Batch payment completed. | | `completed` | Batch processing completed successfully. | | `discarded` | Batch discarded. | --- # 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 configure. ::: ## Statuses with webhook The diagram below shows the three statuses that generate webhooks to the integrating partner: ```mermaid graph LR A([paid]) -->|All settlements completed| B([completed]) C([discarded]) ``` ## 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 table below. | #### `data` attributes | Field | Type | Description | |---|---|---| | `external_id` | string | The batch `external_id` provided at creation. | | `status` | string | New batch status. | | `fund_class_document_number` | string | CNPJ of the fund associated with the batch. | ```json title="Standard webhook structure" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "STATUS", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Events by status ### Batch Paid STATUS paid Sent when the batch payment is confirmed by QI Tech. From this point, 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": "60.910.091/0001-24" }, "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. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "completed", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Batch Discarded STATUS discarded Sent when the batch is discarded. This can occur by explicit request from the integrating partner at [batch closure](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), by automatic discard of open batches by QI Tech, or after cancellation with the cash account. No settlements associated with the batch will be processed after this status. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "discarded", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ```