Settlement Insertion

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.

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).

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.

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.

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. 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. Maximum 50 characters.
collection_origin_type	string	optional	Determines whether the operation is a settlement (borrower) or repurchase (assignor). See 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.

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.

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

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

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.

{
  "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.

{
  "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 — signal that all settlements have been inserted so that processing can begin.