Asset settlement flow

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.

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.

Legend

Integrating Agent

QI Tech (automatic)

Batch Status

Settlement Status

Webhook

Flowchart

1

Payment batch creationIntegrating 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 insertionIntegrating Agent

Inserts each settlement (installment, amortization, full settlement, etc.) into the batch. Repeat for every operation you need.

Batch: pending_settlements_insertionSettlement: 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 closureIntegrating Agent

Signals that all settlements have been inserted and that processing can start — or discards the entire batch.

Batch: pending_payment / pending_validation / pending_discardSettlement: 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 paymentQI Tech

QI Tech confirms the batch payment. The individual settlements are then processed and the settlement webhooks are sent.

Batch: paidWebhook: 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 completionQI 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: settledWebhook: 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.

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 and Settlement webhooks.