Asset Settlement
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.
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.
- To access these services, contact 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:
/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 |
If you already receive the CNAB return file from the collecting bank, you can submit it directly. See Settlement by File and the CNAB 444 Layout — Settlement.
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.
Container for all settlements that will be processed together, identified by a unique external_id.
/settlement/fund_class/{fund_class_key}/payment_batchOne request per settlement, specifying asset type, amount, settlement type and identifiers.
.../payment_batch/{external_id}/settlementSets batch_status. At least one settlement must have been inserted.
.../payment_batch/{external_id}No settlement is processed and no financial movement is generated. Flow terminated.
QI Tech confirms the payment. From this event onwards the individual settlements start being processed.
View documentation →Each settlement is reconciled in the fund's portfolio and notified individually via webhook.
View documentation →All settlements reached a final status and the batch cycle is closed.
View documentation →For every status transition, the webhook payloads and the exception paths, see the Asset Settlement Flow.
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
To check a batch that has already been created, use the batch retrieval.
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
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.
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
4. Tracking via Webhooks
Track progress through webhooks:
- Payment batch webhooks — notifications about batch status.
- Settlement webhooks — notifications about the individual status of each settlement.
Cash reconciliation and the asset portfolio update are performed automatically by the API after batch closure.