Skip to main content

Asset Settlement

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.

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.

Prerequisites
  • To access these services, contact 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.

IntegratorQI Tech
1Payment Batch Creation
pending_settlements_insertion
Integrator

Container for all settlements that will be processed together, identified by a unique external_id.

POST/settlement/fund_class/{fund_class_key}/payment_batch
View documentation →
2Settlement Insertion
settlement: validated
Integrator

One request per settlement, specifying asset type, amount, settlement type and identifiers.

POST.../payment_batch/{external_id}/settlement
View documentation →
Removal of a settlement
Optional
settlement: discarded
Integrator

Discards a settlement inserted by mistake. Only possible while the batch has not been closed.

PUT.../settlement/{settlement_external_id}
View documentation →
3Batch Closure
Integrator

Sets batch_status. At least one settlement must have been inserted.

PUT.../payment_batch/{external_id}
View documentation →
Batch discarded
discarded
Integrator

No settlement is processed and no financial movement is generated. Flow terminated.

Batch payment confirmed
paid
QI Tech

QI Tech confirms the payment. From this event onwards the individual settlements start being processed.

View documentation →
Processing of each settlement
settlement: settled
QI Tech

Each settlement is reconciled in the fund's portfolio and notified individually via webhook.

View documentation →
Fund portfolio reconciled
completed
QI Tech

All settlements reached a final status and the batch cycle is closed.

View documentation →
Full flow

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

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

While the batch has not been closed, a settlement inserted by mistake can be removed.

Access settlement removal documentation

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

4. Tracking via Webhooks​

Track progress through webhooks:

Automatic Processing

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