Settlement by File
The settlement (write-off) of assets already held in the fund's portfolio can be done in two ways: sending a file with all the settlements of the day, through the manager/consultant portal, or inserting settlement by settlement through the API. Both produce the same payment batch and go through the same reconciliation.
| Sending by file | Insertion through the API | |
|---|---|---|
| How it works | One file with all the settlements | One request per settlement |
| Formats | CNAB 444 and CSV | JSON |
| Available in | Manager and consultant portal | Asset Settlement API |
| Suitable for | Daily routine of high-volume settlements, from the bank return file | One-off settlements and real-time integrations |
Today, sending a settlement file is available in the portal. Through the integration API, the settlement is done through the payment batch + settlements flow, without a file.
Accepted formats
| Format | Extension | Suitable for | Template |
|---|---|---|---|
| CNAB 444 — duplicatas and CT-e | .rem · .txt | Those who already receive a CNAB return file from the collecting bank. Layout in CNAB 444 Layout — Settlement | Example |
| CNAB 444 — CCB and credit operations | .rem · .txt | The same layout, with the asset identified by the contract number | Example |
| CSV | .csv | A simple spreadsheet, with one line per settlement, for any asset type. Layout in the Settlement CSV section | Example |
Step by step through the screen
- Go to Assets › Settlements and click New batch by file.
- Provide a description to identify the batch.
- Select the fund account that will receive the credit of the settlements.
- Drag the file (
.rem,.txtor.csv) and confirm.
The portal creates the payment batch, sends the file and triggers the validation. The screen then shows the batch with the progress — total settlements, processed and failed.
What happens after sending
| Batch stage | What it means |
|---|---|
| Awaiting file | Batch created, file not sent yet |
| Validation in progress | File received, being checked line by line |
| Creating the batch | File valid, payment batch being created |
| Inserting the settlements | Each line is becoming a settlement |
| Completed | All the settlements processed |
| Completed with failures | Batch processed, but with settlements that failed individually |
| Refused | File refused in the validation — nothing was processed |
One invalid line refuses the whole file. The portal reports the line number and the description of the error. Fix it and send a new batch, with a new identifier.
After the batch is closed and the payment confirmed, each settlement is reconciled individually in the fund's portfolio — the same behavior described in the Settlement flow. A settlement can fail on its own (for example, an asset not found in the portfolio) without bringing down the others.
Settlement CSV
A file with a header on the first line, separated by ; or ,. Limit of 850,000 lines.
asset_type;total_value;settlement_type;external_id;installment_number;collection_origin_type
duplicata_mercantil;1510.00;asset_settlement;CTRL000001;;borrower
duplicata_mercantil;500.00;asset_amortization;CTRL000002;;borrower
ccb;350.75;installment_settlement;CONTRATO-0001;3;borrower
Columns
| Column | Required | Description |
|---|---|---|
asset_type | required | Asset type. See accepted values |
total_value | required | Value of the settlement. Accepts . or , as the decimal separator |
settlement_type | required | Settlement type. See settlement types |
installment_number | required (column) | Installment number. Fill it in for assets with installments (CCB); leave it empty for duplicatas; for contracts, use installment_number or installment_external_id |
external_id or contract_number | required | Identifier of the asset. Use external_id for duplicatas/contracts (the same control number sent in the assignment) and contract_number for CCBs |
collection_origin_type | optional | Who paid: borrower (drawee), assignor (assignor) or collection_agent (collection agent) |
remaining_face_value | optional | Remaining balance of the face value. Accepted only with settlement_type: installment_amortization |
new_maturity_date | conditional | New maturity date, in the YYYY-MM-DD format. Required in asset_extension and rejected in the other types |
installment_external_id | optional | For contracts, an alternative to installment_number |
The same file uses external_id or contract_number — not both. If neither column exists, the file is refused.
Settlement types
| Value | Meaning |
|---|---|
asset_settlement | Full settlement of the asset |
asset_amortization | Partial payment of the asset |
installment_settlement | Full settlement of an installment |
installment_amortization | Partial payment of an installment |
installment_partial_refund / asset_partial_refund | Partial refund |
installment_refund / asset_refund | Full refund |
fine_payment / installment_fine_payment | Fine payment |
gloss | Gloss |
canceled | Cancellation |
rco_revenue | RCO revenue |
asset_extension | Maturity extension (credit rights only; requires the external_id column and new_maturity_date) |
Accepted asset types
ccb · cce · structured_ccb · structured_cce · structured_nce · structured_cci · duplicata_mercantil · duplicata_servicos · discounted_contract · cte · commercial_paper · check · promissory_note · debt_acknowledgment · financing_contract · contract
Most common errors
| Error | Cause |
|---|---|
missing_fields: [...] | A required column is missing from the CSV header |
invalid asset_type: ... | Asset type outside the accepted list |
invalid settlement_type: ... | Settlement type outside the accepted list |
invalid total_value: ... | Value with an unexpected character or empty |
invalid external_id / contract_number | Blank identifier |
remaining_face_value is only allowed for settlement_type installment_amortization | Remaining balance provided with the wrong type |
unmapped cnab layout | CNAB file with lines outside 444 or 500 positions |