Asset Settlement Flow

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.

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.

Legend

Integration Agent

QI Tech (automatic)

Batch Status

Settlement Status

Webhook

Flowchart

1

Payment batch creationIntegration 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 insertionIntegration Agent

Inserts each settlement (installment, amortization, full settlement, etc.) into the batch. Repeat for all desired operations.

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

Signals that all settlements have been inserted (and adjusted) and that processing can begin — or discards the entire batch.

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

QI Tech confirms the batch payment. Individual settlements are then processed and settlement webhooks are triggered.

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

Each successfully processed settlement is reconciled in the fund's portfolio. This is the final success status per settlement.

Settlement: settledWebhook: 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.

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