Settlement Insertion

Endpoint to insert individual settlements into a previously created payment batch. Each settlement represents a payment (full or partial) for an asset in the fund's portfolio — such as installment settlement, amortization, repurchase or interest payment.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Create Batches
Assignor	assignor-api	Write

Base URL for each host: Environments (Hosts).

Settlement, repurchase and pass-through

Settlement and repurchase use this same endpoint. The collection_origin_type field indicates who paid:

• borrower — settlement paid by the drawee/debtor.
• assignor — repurchase paid by the assignor.
• collection_agent — payment passed through by a collection agent. Requires counter_party_document_number.
• bankslip — payment received by bankslip.

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. The batch must be in pending_settlements_insertion.

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, with at most two decimal places. Can be 0 only in installment_settlement, asset_settlement, asset_refund and asset_extension.
external_id	string	required	Unique key of this settlement within the batch, 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	Who paid. See collection_origin_type enumerators. When omitted, the default from the fund's settlement configuration applies, if any.
counter_party_document_number	string	conditional	CPF or CNPJ of who paid, with punctuation (14 to 18 characters). Required when collection_origin_type is collection_agent and the fund's settlement configuration does not define a default document. With borrower, bankslip or assignor, when omitted, it is filled in with the document of the asset's drawee or assignor.
contract_number	string	optional	Contract number of the asset. Maximum 50 characters.
asset_external_id	string	optional	Unique asset identification key, provided in the 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 in the assignment. Maximum 50 characters.
installment_number	integer	conditional	Installment number. See installment identification.
installment_maturity_date	string	conditional	Installment maturity date in YYYY-MM-DD format.
installment_external_id	string	conditional	External identifier of the installment. Maximum 50 characters.
collection_date	string	optional	Payment date in YYYY-MM-DD format. Field intended for the integrator's own control.
remaining_face_value	number	optional	Face value balance remaining in the installment after the payment. Accepted only in installment_amortization and when the settlement affects a single asset.
asset_reduction_value	number	optional	Amount to deduct from the asset, when different from the amount paid. Accepted only in installment_amortization and installment_partial_refund. Cannot be greater than total_value.
new_maturity_date	string	conditional	New maturity date, in YYYY-MM-DD format. Required in asset_extension and rejected in the other types.
reversed_settlement_external_id	string	conditional	external_id of the settlement being reversed. Required in installment_payment_reversal and rejected in the other types.

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 and installment identification

• Provide exactly one asset identifier: contract_number, asset_external_id, asset_key, if_code or participant_control_number. None or more than one returns an error. Duplicatas and other credit rights do not accept contract_number or if_code; CCBs and other credit operations do not accept participant_control_number.
• In installment-based settlement types (installment_* and gloss), provide exactly one installment identifier: installment_number, installment_maturity_date or installment_external_id. For CCBs and contracts, installment_external_id alone also identifies the asset.

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 (Nota de Crédito à Exportação)
structured_cci	Structured Real Estate Credit Note
duplicata_mercantil	Commercial duplicata (Duplicata Mercantil)
duplicata_servicos	Service duplicata (Duplicata de Serviços)
discounted_contract	Discounted contract
cte	Electronic Bill of Lading (Conhecimento de Transporte Eletrônico)
check	Check
promissory_note	Promissory note
legal_fees	Legal fees
debt_acknowledgment	Debt acknowledgment
financing_contract	Financing contract
contract	Contract

settlement_type enumerators

Value	Description
asset_settlement	Full settlement of the asset.
asset_amortization	Amortization of the asset.
fine_payment	Payment of interest or late charges on the asset.
asset_refund	Full refund of the asset.
asset_partial_refund	Partial refund of the asset.
asset_gloss	Gloss (deduction) of the asset.
asset_extension	Maturity extension of duplicatas and other credit rights. Requires new_maturity_date and a single asset.
installment_settlement	Installment settlement.
installment_amortization	Installment amortization.
installment_fine_payment	Payment of interest or late charges on an installment.
installment_refund	Full refund of an installment.
installment_partial_refund	Partial refund of an installment.
installment_payment_reversal	Reversal of the payment of an installment of a CCB or credit operation. Requires reversed_settlement_external_id and installment_number; total_value must equal that of the reversed settlement.
gloss	Gloss (deduction) of an installment.
rco_revenue	RCO revenue.

Contracts (debt_acknowledgment, financing_contract, contract) accept only asset_settlement, asset_amortization, installment_settlement and installment_amortization.

collection_origin_type enumerators

Value	Description
borrower	Settlement — payment made by the drawee/debtor.
assignor	Repurchase — payment made by the assignor.
collection_agent	Pass-through from a collection agent. Requires counter_party_document_number (or a default document in the fund configuration).
bankslip	Payment received by bankslip.

Response

STATUS

201

The response echoes the fields sent in the body and adds the data computed by QI Tech.

Response 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",
    "asset_external_id": "CCB-0001",
    "assignor_document_number": "33.444.555/0001-81",
    "borrower_document_number": "969.698.790-03",
    "status": "validated",
    "type": "installment_settlement",
    "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890",
    "total_number_of_units": 1,
    "settlement_result": 0.0,
    "next_execution_datetime": "2025-01-01 13:00:00.000000",
    "counter_party_document_number": "969.698.790-03",
    "assets": [
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value": 130.50
        }
    ]
}

Response attributes

In addition to the fields sent in the body:

Field	Type	Description
status	string	Settlement status after insertion: validated or pending_validation. See below.
type	string	Settlement type (same value as settlement_type).
settlement_key	string	Unique settlement identifier generated by QI Tech (UUID).
total_value	number	Total payment amount. Negative in gloss, asset_gloss and installment_payment_reversal.
total_number_of_units	integer	Total number of asset units affected by the settlement.
installment_number	integer	Number of the installment found. Present when applicable.
settlement_result	number	Difference between the amount paid and the expected amount of the asset or installment. Present when calculated.
contract_number, asset_external_id	string	Identifiers of the asset found in the portfolio (CCBs and contracts).
assignor_document_number, borrower_document_number	string	Document of the asset's assignor and drawee.
counter_party_document_number	string	Document of who paid. Present when provided or filled in automatically.
collection_origin_type	string	Payment origin. Present when provided or defined by the fund configuration.
next_execution_datetime	string	QI Tech processing control. Can be ignored.
denial_reason	string	Discard reason. Present only in discarded settlements.
assets	array	Assets affected by the settlement. See assets attributes.

Status in the response:

• validated — the amount paid is within the tolerance relative to the expected amount of the asset or installment. The settlement will be processed when the batch is paid.
• pending_validation — the amount paid differs from the expected amount beyond the tolerance and the settlement awaits review by QI Tech. At the end of the review it moves to validated or discarded, and you receive the corresponding settlement webhook. Depending on the fund's settlement configuration, the difference may instead reject the insertion with SET000066.

assets attributes

Field	Type	Description
asset_key	string	Unique asset identifier (UUID).
number_of_units	integer	Number of asset units.
present_value	number	Present value of the asset in BRL.
installment_face_value	number	Installment face value. Present when applicable.
installment_post_maturity_interest_value	number	Post-maturity interest value of the installment. Present when applicable.
installment_delay_interest_value	number	Late interest value of the installment. Present when applicable.
installment_delay_fine_value	number	Late fine value of the installment. Present when applicable.
total_purchase_value	number	Acquisition value of the asset. Present when applicable.
maturity_date	string	Maturity of the asset. Present when applicable.
contract_number	string	Contract number of the asset. Present when applicable.
external_id	string	External identifier of the asset. Present when applicable.

Retry and duplicates

If an error occurs, resend the request. A duplicate (SET000013) means the settlement already exists in this batch: look it up through the settlement retrieval instead of recreating it. See Retry and duplicates.

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.

There is no endpoint to remove an individual settlement. If a settlement was inserted by mistake, discard the batch at closure (batch_status: discarded) and create a new batch with the correct settlements.

Errors

Status	Code	When it happens
404	SET000010	The batch given in the URL does not exist in this fund.
403	SET000028	The fund does not belong to your profile.
400	SET000026	The batch is not in pending_settlements_insertion (it has already been closed or discarded).
400	SET000013	A settlement with this external_id already exists in the batch. Look it up instead of recreating it.
409	SET000053	Two simultaneous requests with the same external_id; one of them was saved.
400	SET000012	Invalid asset_type.
400	SET000025	Invalid settlement_type.
400	SET000014	total_value with more than two decimal places, or zero in a type that does not accept zero.
400	SET000019	No asset identifier was provided.
400	SET000020	More than one asset identifier, or more than one installment identifier.
400	SET000029	Installment-based settlement type without installment identification.
400	SET000040 / SET000041	Settlement type or identifier not accepted for this asset_type.
400	SET000022 / SET000023 / SET000047	The asset is not active or does not accept this settlement type in its current status.
400	SET000086 / SET000087 / SET000088	remaining_face_value outside installment_amortization, with more than two decimal places, or with the settlement affecting more than one asset.
400	SET000092 / SET000093 / SET000094	asset_extension without new_maturity_date, new_maturity_date in another type, or an extension affecting more than one asset.
400	SET000112 / SET000113 / SET000114	asset_reduction_value outside installment_amortization/installment_partial_refund, with more than two decimal places, or greater than total_value.
400	SET000104 / SET000105	installment_payment_reversal without reversed_settlement_external_id/installment_number, or reversed_settlement_external_id in another type.
400 / 404 / 409	SET000106 to SET000111, SET000115	The reversed settlement does not exist, is not settled, is of another type, installment or asset, has already been reversed, or the amount differs.
404	SET000015	No asset found in the fund's portfolio with the identifier provided.
400	SET000035 / SET000042 / SET000052 / SET000060	The installment provided does not exist or has no balance in the asset.
400	SET000046	Another settlement of the same group for the same asset/installment already exists in the same batch.
400	SET000080	Full settlement of an asset that is already settled (present value zero).
400	SET000066	Amount paid outside the tolerance and the fund is configured to reject automatically.
400	SET000067	Invalid collection_origin_type.
400	SET000078	collection_origin_type is collection_agent without counter_party_document_number.
400	SET000001	counter_party_document_number is not a valid CPF/CNPJ.
400	QIT000001	Invalid body (missing required field, wrong type or field not accepted).

Authentication, permission and host errors: see API errors.