Settlement Retrieval

Returns a settlement of a payment batch by the external_id provided at insertion. Use it to check the settlement status or when the insertion returns a duplicate (SET000013).

Available on

Profile	Host	Required permission
Manager	manager-api	Read
Consultant	consultant-api	View Batches
Assignor	assignor-api	Read

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}

METHOD

GET

Path params

Parameter	Type	Description
fund_class_key	string	Fund key (UUID).
external_id	string	The external_id of the payment batch.
settlement_external_id	string	The external_id of the settlement, provided in the body of the insertion.

Response

STATUS

200

The object is the same one returned by the settlement insertion: the fields sent in the insertion body plus the data computed by QI Tech, with the current status.

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": "settled",
    "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
        }
    ]
}

Settlement status

Status	Meaning
validated	Inserted and approved; awaiting payment of the batch.
pending_validation	Amount paid outside the tolerance; awaiting review by QI Tech.
waiting_send_to_queue / on_queue	Batch paid; settlement being processed in the fund's portfolio.
settled	Completed and reconciled in the portfolio. Final status.
discarded	Discarded, with no financial movement. Final status. The denial_reason field carries the reason, when there is one.
inconsistent_asset	The portfolio refused the payment due to an inconsistency in the asset. QI Tech handles the case; the batch does not reach completed while there is a settlement in this status.

The complete map, with the statuses that trigger a webhook, is in Settlement webhooks.

Errors

Status	Code	When it happens
404	SET000011	There is no settlement with this settlement_external_id in the given batch (or the batch does not exist in this fund).
404	SET000005	The fund_class_key does not exist.
403	SET000028	The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor).

Authentication, permission and host errors: see API Errors.