> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Map your chart of accounts

> Choose the ledger Lender books into, map each accounting event to your own accounts, read the chart back, and change it later.

Lender books every money event of a product in the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) of the product, in Midaz. You map those events to your accounts once, in a chart. You own the accounts. Lender owns the shape of each double-entry (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.) posting, and it refuses a chart that cannot balance.

This guide is for the back office and the accountant of the client. It covers the ledger, the accounting events, and the accounts you define. [Accounting and accrual runs](https://docs.lerian.studio/en/products/lender/accounting-and-accrual-runs.md) covers how a posting reaches the ledger.

## Before you start

***

* Create the loan product and a version first. See [Define a loan product](https://docs.lerian.studio/en/products/lender/define-a-loan-product.md).
* To configure a chart, your role needs `loan_product` `write` and `accounting` `write`. The operator, editor, and admin roles hold both.
* To change a chart, or to designate a suspense account, your role needs `accounting` `supersede`. Only the admin role holds it.

## The product ledger

***

A chart names the Midaz organization and the Midaz ledger that the postings of the product book into.

* Under multi-tenant mode, the organization is required. Under single-tenant mode, a chart with no target falls back to the default of the environment.
* Name only the organization, and Lender reuses the ledger that the product already books into there. If the product has none, Lender finds or creates a ledger named `lender-product-<loan product id>`. The response names the ledger it chose.
* Every version of a product books into the ledger that the first configured version chose (`LENDER-0453`). Several products can share one ledger.
* Lender refuses a ledger that has route validation turned on (`LENDER-0452`). Lender sends no accounting route to Midaz.
* Lender refuses an organization or a ledger that Midaz does not know (`LENDER-0442`). If Midaz does not answer, Lender answers `503` with `LENDER-0441`. Repeat the request.

`MIDAZ_LEDGER_ACCOUNT_PROVISIONING_ENABLED` is `true` by default. See [Configuration and deploy](https://docs.lerian.studio/en/products/lender/configuration-and-deploy.md). Lender then adopts the asset by code or creates it. It creates each account before the first posting to that account.

* The nature of a leg sets the account type. A credit nature creates a `deposit` account. A debit nature creates a `lender_debit` account.
* The direction of an account is fixed when the account is created.
* Lender adopts an account that already exists. It checks the direction of the account against the nature of the leg, and it refuses the posting if they differ.

A per-contract account has the alias `<prefix>:<id>`. The prefix is yours, with at most 17 characters. The id is the 32 hex digits of the loan account id. Lender creates a per-contract account for a borrower position with the CRM holder of the contract as its owner.

## Anatomy of a posting rule

***

A **posting rule** maps one accounting event to 2 to 16 legs. A rule can also carry `metadata`, a map of text values. Each leg moves money on one account.

| Field | What it means |
| - | - |
| `account` | The account, as its Midaz alias. It has at most 50 letters, digits, `:`, `_`, and `-`, with an optional leading `@`. It can also be `@external/<ASSET>`. Lender refuses anything else (`LENDER-0429`). |
| `role` | The reserved economic role of the leg: `principal`, `interest`, `iof`, `tax`, `cash`, `unapplied_cash`, `counterparty`, or `suspense`. |
| `component` | An open code, such as `iof`, for a leg that has no reserved role. Set `role` or `component`, never both. |
| `side` | `debit` or `credit`. |
| `nature` | The nature of the account, not the side of the leg. Use `debit` for an asset or an expense. Use `credit` for a liability, equity, or revenue. A contra account takes its own nature: rendas a apropriar, each provision allowance and the art. 22 adjustment take credit. Every leg that names one account declares the same nature. |
| `optional` | Lets Lender omit the amount of a component leg, or post it as zero. Only a component leg can be optional. |
| `perOperation` | Books the leg in one account for each contract. `account` is then a prefix of at most 17 characters. |

### Per-contract positions

A leg that books what one borrower owes must be per contract (`LENDER-0408`). These are the amount codes: `principal`, `interest`, `fees`, `penalties`, `unapplied_cash`, `assignment_retained`, and `returned_payment`. Two kinds of leg are the exception:

* A revenue or expense leg.
* The credit of `accrual_withholding` to rendas a apropriar.

The retained origination fee is per contract on both ends, on one account: the `origination_fee` credit on `disbursement` and the `accrual_fee_amortization` debit. A shared fee account is accepted, but it blocks every write-off (`LENDER-0411`), and no chart change can fix it.

Some accounts are never per contract:

* The revenue tax account, because it is a liability of the institution to the tax authority (`LENDER-0419`).
* A revenue or an expense account (`LENDER-0987`).
* The counterparty account of `renegotiation_derecognition` and `renegotiation_recognition`. This bridge account is one account for the product.

### Example

This is the `disbursement` rule of a chart. The account codes are only an illustration.

```json theme={null}
{
  "eventType": "disbursement",
  "legs": [
    { "account": "1100-10-001", "role": "principal", "side": "debit", "nature": "debit", "perOperation": true },
    { "account": "@external/BRL", "role": "cash", "side": "credit", "nature": "debit" },
    { "account": "2300-40-001", "component": "iof", "side": "credit", "nature": "credit", "optional": true },
    { "account": "2400-10-001", "component": "origination_fee", "side": "credit", "nature": "credit", "optional": true, "perOperation": true }
  ]
}
```

`@external/<ASSET>` is the account that Midaz creates for each asset. It records money that enters the ledger or leaves it. See [Accounts](https://docs.lerian.studio/en/products/midaz/accounts.md).

Your treasury account can live in the same ledger. Then the `cash` leg can name it. Lender turns on negative balance only for the credit accounts it lists for that, and never for the `cash` account. See [Balance overdraft](https://docs.lerian.studio/en/products/midaz/balance-overdraft.md). Midaz therefore refuses a disbursement that is larger than the balance of that account. The posting parks as a case (`LENDER-0458`). Keep the cash in the account.

## The accounting events

***

A chart can carry three kinds of event: events every chart needs, optional events, and events that Lender derives.

### Required events

Lender refuses a chart that lacks one of these events.

| Event | Lender posts it when | What the legs book |
| - | - | - |
| `disbursement` | Lender releases a loan. | A debit of the principal per contract. A credit of the net cash. A credit of each tax the jurisdiction withholds, such as IOF, and of the origination fee that a version retains. |
| `repayment` | A payment settles an instalment. | A debit of cash. A credit of the principal and the interest the payment clears, per contract. The interest account is the one that `accrual` debits (`LENDER-0440`). |
| `prepayment` | A borrower pays a loan ahead of schedule, in whole or in part. | Five legs in this order: `cash` debit, optional `charge_rebate` debit, optional `iof_refund` debit, `principal` credit, optional `iof_due` credit. |
| `accrual` | An accrual run recognizes the interest of a month. | One debit of the interest receivable, per contract. One credit of the interest revenue. |
| `accrual_withholding` | Interest is withheld on a problem asset (Res. CMN 4.966 art. 17). | A debit of the same interest receivable that `accrual` debits. A credit of rendas a apropriar, on one shared account that is not the revenue of `accrual`. |
| `renegotiation_gain` | A non-substantial renegotiation (Res. CMN 4.966 art. 22) leaves a gain. | A debit of the adjustment account of the contract. A credit of the gain. |
| `renegotiation_loss` | A non-substantial renegotiation (Res. CMN 4.966 art. 22) leaves a loss. | A debit of the loss. A credit of the adjustment account of the contract. |
| `collection_unapplied` | A payment arrives and the contract holds it as unapplied cash. | A debit of `cash`. A credit of `unapplied_cash`, per contract. |
| `collection_reapply` | Lender applies held cash to a receivable, as the daily settlement does on a due date. | A debit of `unapplied_cash`, its only debit. A credit of each receivable it settles. |
| `collection_refund` | Lender gives held cash back to the borrower. | A debit of `unapplied_cash`. A credit of `cash`. |
| `provision_constitution` | The measurement of a business date raises the additional provision of a contract. | A debit of the expense. A credit of the allowance. The event carries the increase only. |
| `provision_reversal` | The measurement of a business date lowers that provision. | A debit of the allowance. A credit of an expense or reversal-revenue account. |
| `provision_incurred_constitution` | The measurement of a business date raises the incurred loss (Res. BCB 352 art. 76). | A debit of the expense. A credit of the allowance of the incurred loss. |
| `provision_incurred_reversal` | The measurement of a business date lowers the incurred loss. | A debit of that allowance. A credit of an expense or reversal-revenue account. |

The two constitutions credit two different allowance accounts. Lender refuses a chart that credits one account for both (`LENDER-0455`).

### Optional events

The last column says what happens if you leave it out.

| Family | Events | Carry it when | Without it |
| - | - | - | - |
| Revenue tax | `accrual_tax` | The interest revenue bears PIS/COFINS. | The accrual run computes the tax and posts nothing. It counts the tax as recognized and unposted. |
| Retained origination fee | `accrual_fee_amortization`, plus the optional `origination_fee` leg on `disbursement` | The product retains an origination fee at disbursement. Book it per contract, on one account. | Lender refuses every centavo of the fee. |
| Charge applied after the release | `charge_appropriation`, plus a per-contract `fees` credit leg on `repayment` | A version declares a charge template that an operator can apply after the release. The template has a flat amount. | Lender refuses the chart (`LENDER-0989`). |
| Substantial renegotiation | `renegotiation_derecognition`, `renegotiation_recognition` | The product renegotiates substantially under Res. CMN 4.966 art. 22. The old contract ends and a new one starts. | A product must carry both events to be renegotiated substantially. |
| Assignment, risk transferred | `assignment_derecognition`, `assignment_retained_settlement` | You sell receivables to a fund. The second event is needed to sell a receivable in the middle of a cycle. | Lender refuses the acceptance of a sale over a product without `assignment_derecognition`, and it queues an exception case. |
| Assignment, risk retained | `assignment_secured_borrowing`, `assignment_funding_amortization`, `assignment_funding_payoff` | You sell receivables and answer for them. The first two go together. The third is not required yet. | Lender refuses a sale with retained risk over a product that lacks the first two. |
| Assignment repurchase | `assignment_repurchase` | A bancarizador can settle a sold receivable early. | Lender refuses the fund-settlement receipt. |
| Refinance | `refinance_payoff`, `refinance_payoff_reversal` | The product is refinanced. | A product must carry both events to be refinanced. |
| Returned payment | `returned_payment_recognition`, `returned_payment_provision_constitution`, `returned_payment_provision_reversal`, `returned_payment_write_off` | Final payments can be given back after the payroll mandate is gone. | Lender refuses a chart that carries the first event without the other three (`LENDER-0406`). |
| Employer remittance | `payroll_payer_provision_constitution`, `payroll_payer_provision_reversal` | The `repayment` rule carries the `payroll_payer_receivable` leg. | Lender refuses the chart (`LENDER-0423`). |
| Compensation accounts | `compensation_control`, with the controls `written_off_credit` and `guarantee_received` | You keep off-balance controls for written-off credit or for guarantees. | Lender refuses a write-off and writes nothing (`LENDER-0975`). |
| Recovery of written-off credit | `credit_loss_recovery` | A written-off borrower can pay later. | Lender refuses the recovery and writes nothing (`LENDER-0980`). |

For the assignment events, see [Assignment of receivables](https://docs.lerian.studio/en/products/lender/assignment-of-receivables.md).

### Events you do not configure

Lender derives these events from the rules above. A chart cannot carry them. If you send one, Lender answers `422`.

| Event | Books on the accounts of | What it does |
| - | - | - |
| `reversal` | `repayment` | Reverses a repayment. It side-swaps every repayment leg. |
| `accrual_reversal` | `accrual` | Takes interest that a close booked past the contract back out of revenue. |
| `accrual_withholding_reversal` | `accrual_withholding` | Takes interest that a close withheld past the contract out of rendas a apropriar. |
| `accrual_suspension` | `accrual`, `accrual_withholding` | Moves interest of a closed month back out of revenue, when a late characterization makes the contract a problem asset inside that month. |
| `accrual_tax_suspension` | `accrual_tax` | Gives back the PIS/COFINS that a closed month booked on the interest that the suspension moves. |
| `suspended_income_recognition` | `accrual`, `accrual_withholding` | Recognizes withheld interest as revenue when the receipt arrives. |
| `accrual_fee_amortization_reversal` | `accrual_fee_amortization` | Gives back fee released beyond a re-valuation. |
| `interest_capitalization` | `disbursement`, `accrual` | Moves billed interest that a reschedule carried into principal from the interest receivable to the principal receivable. |
| `interest_unapplied` | `repayment`, `collection_unapplied` | Moves interest receipts paid for days after a payoff from the interest receivable to held cash, owed back to the borrower. |
| `modification_tax` | `disbursement` | Finances into principal the tax that a schedule modification levies. |
| `late_charge_recognition` | `repayment`, `accrual` | Recognizes a received late fine and default interest as revenue. |
| `late_charge_recognition_reversal` | `repayment`, `accrual` | Gives that revenue back. |
| `late_charge_capitalization` | `disbursement`, `repayment` | Moves a recognized late charge that a reschedule carried into principal. |
| `late_charge_withholding` | `repayment`, `accrual_withholding` | Keeps out of income the late charge that a reschedule carried on a contract that art. 17 suspends. |
| `late_charge_waiver` | `renegotiation_loss`, `repayment` | Takes the late charge that a reschedule waived into the art. 22 loss. |
| `renegotiation_loss_unwind` | `accrual`, `renegotiation_loss` | Earns an art. 22 adjustment back as the contract runs. |
| `renegotiation_gain_unwind` | `accrual`, `renegotiation_loss` | The mirror of the loss unwind. |
| `renegotiation_gain_reversal` | `renegotiation_gain` | Takes a day-one gain back out of the result while art. 17 holds it. |
| `collection_reapply_reversal` | `collection_reapply` | Gives a due-date settlement back to unapplied cash. |
| `refinance_disbursement_reversal` | `disbursement` | Closes the new contract of a refinance that the rail undid. |
| `returned_payment_collection` | `returned_payment_recognition` | Books the returned-payment debt back when the borrower pays by other means. |
| `charge_assessment` | `repayment`, `charge_appropriation` | Bills an applied charge when Lender applies it, against the fees receivable of the contract. |
| `charge_appropriation_reversal` | `charge_appropriation` | Reverses a charge appropriation. |
| `compensation_control_release` | `compensation_control` | Releases a control. It is the opening rule with its sides swapped. |
| `credit_loss_recovery_reversal` | `credit_loss_recovery` | Gives back a recovery, on the accounts that the recovery booked. |

## Checks Lender runs on your chart

***

Lender checks the chart when you configure it or change it. It writes nothing when a check fails.

| Code | Refused when | Fix |
| - | - | - |
| `LENDER-0406` | The chart carries `returned_payment_recognition` without the three rules that provision and write off the debt. | Add the three rules and resend. |
| `LENDER-0408` | A leg books a borrower position on an account that every contract shares. | Book that leg per contract. |
| `LENDER-0419` | The revenue tax is booked per contract. | Book both tax legs on shared accounts of the institution. |
| `LENDER-0423` | The `repayment` rule carries `payroll_payer_receivable`, and the chart has no provision pair for the employer. | Add both `payroll_payer_provision_*` rules and resend. |
| `LENDER-0426` | A version charges a late fine and default interest, and `repayment` has no per-contract `penalties` credit leg. | Add a credit leg with `component` `penalties` and `perOperation` true. |
| `LENDER-0429` | An account is not a Midaz alias. | Respell the account, for example `1100-10-001`. |
| `LENDER-0430` | The jurisdiction withholds a tax at disbursement, and `disbursement` has no credit leg for it. | Add a credit leg with that `component`, for example `iof`. Mark it `optional` if some versions withhold nothing. |
| `LENDER-0440` | `repayment` has no `interest` credit leg. | Add one on the account that `accrual` debits. |
| `LENDER-0442` | Midaz knows no organization, or no ledger in it, with those ids. | Correct `midazOrganizationId` and `midazLedgerId`. |
| `LENDER-0452` | The ledger has Midaz route validation turned on. | Turn it off on the ledger, or name another ledger. |
| `LENDER-0453` | The product already books into another ledger. | Name the ledger in the detail, or only its organization. |
| `LENDER-0455` | The two provision constitutions credit one allowance account. | Credit a separate allowance for the incurred loss. |
| `LENDER-0987` | A revenue or expense leg is booked per contract. | Book each revenue and expense leg on a shared account. |
| `LENDER-0989` | The chart cannot book a charge applied after the release. | Add the per-contract `fees` credit leg to `repayment`, and the `charge_appropriation` rule, each on an account of its own. |

Configuring a chart for a version that already has one answers `409 Conflict`.

The [Lender error list](https://docs.lerian.studio/en/reference/products/lender/lender-error-list.md) holds the full text of each code.

## Read a chart back

***

| Operation | Purpose |
| - | - |
| `GET /api/v1/accounting-profiles` | List the charts with their coverage. |
| `GET /api/v1/accounting-profiles/{id}` | Read one whole chart. |

The list shows, for each chart, `eventTypes`, `missingEventTypes`, `effectiveFrom`, and `createdAt`. `missingEventTypes` names the required events for which the chart has no rule. It is empty when the chart is complete.

The read by id returns the whole chart. It has `postingRules` with their legs, `midazOrganizationId`, `midazLedgerId`, `effectiveFrom`, and `createdAt`. It has no coverage field. An id that Lender does not know answers `404` with `LENDER-0454`.

## Change the chart

***

You configure a version once. Its first chart governs from `1900-01-01`, and a second configure call answers `409`. Every chart is immutable. A version keeps a chain of dated charts, and a change adds one dated chart to every configured version of the product.

A change belongs to the product, not to a version.

`POST /api/v1/loan-products/{id}/accounting-profiles/supersessions`

The body carries the complete new chart and `effectiveFrom`. `effectiveFrom` is always the first day of a month that has not opened by tomorrow. On the last day of a month, the earliest choice is the first day of the month after next. The new chart books into the same ledger as the old one (`LENDER-0443`).

The new chart keeps every per-contract position of the old chart. A shared balance account keeps its account and its mode: an allowance, a payable, or cash. Revenue and expense accounts can change. Lender refuses a change that sends two positions of one per-contract account to different accounts (`LENDER-0986`).

The chart in force on a day is the chart with the greatest `effectiveFrom` at or below that day. A contract stays on the chart that holds its balance until the balance transfers.

**1. Record the change**

Send the change. Read `movedPositions` in the answer. It lists each position whose balance changes account.

**2. Let the balances move**

The balance of a contract moves inside its first posting after the change. The close of the effective month moves the contracts that had no posting. Nothing else is required.

**3. Optional: sweep the contracts that still wait**

After the close of the month before the effective day, `POST /api/v1/loan-products/{id}/accounting-profiles/supersessions/sweeps` moves them now, with one posting for each contract. It needs an `X-Idempotency` header. Every rerun needs a new key, because the same key replays the earlier answer.

**4. Clear what holds a contract**

`LENDER-0450` lists the possible causes, not the one that applies to a contract, and every contract that was ready did move. Check them in order: the close of the month before the effective day; an earlier change that is still open (sweep that one first); parked postings (see [Accounting and accrual runs](https://docs.lerian.studio/en/products/lender/accounting-and-accrual-runs.md)); an amount that the ledger holds. Then rerun the sweep under a new `X-Idempotency` key. Do not repeat it in a loop.

In the Console, see **Chart of accounts changes** and **Move waiting contracts** in [Credit](https://docs.lerian.studio/en/products/lender/console/credit.md).

## Suspense accounts

***

Some postings need a suspense account. A disbursement in parts and a compensating adjustment use them. You designate one account for each currency and role.

| Role | What it takes | Default account for BRL |
| - | - | - |
| `suspense` | The residual of the CCB, on either side. | `suspensao-brl`, credit nature |
| `below` | What a disbursement in parts still owes the borrower. | `valores-a-liberar-brl`, credit nature |
| `above` | What the borrower paid over the liberated amount. | `pago-a-maior-brl`, debit nature |
| `loss` | The expense of a disbursement excess that the borrower keeps. | `perdas-brl`, debit nature |

`PUT /api/v1/internal/accounting/suspense-accounts/{currency}/{role}` designates the account, with `gl_account` in the body. A designated account must already exist in the ledger. Lender never creates it, unless it has the exact name of the default.

A contract keeps the account that holds its first amount in a role. A new account applies to contracts that have none. When Lender provisions ledger accounts, a BRL role with no designated account books into the default. `GET` on the same path answers `404` with `LENDER-0449` when you designated none. See [Accounting](https://docs.lerian.studio/en/products/lender/console/accounting.md).

## In the Console

***

The screen to configure a chart needs the same two permissions as the API. Open **Credit**, open the product and the version, and choose **Configure accounting profile**. See [Credit](https://docs.lerian.studio/en/products/lender/console/credit.md).

**1. Choose the financial institution**

**Financial institution** names the organization. Lender creates the ledger of the product in it, or reuses the ledger it already created.

**2. Review the sheet**

The sheet starts as a copy of the latest chart of the product, when the screen can edit every rule of it. Review every account before you record.

**3. Mark the per-contract legs**

Mark each leg that books a borrower position as **Per contract**.

**4. Record the chart**

**Record accounting profile** saves the chart for good. Closing the page discards a sheet you did not record.

The screen records these events: the required events, `payroll_payer_provision_constitution`, `payroll_payer_provision_reversal`, `refinance_payoff`, `refinance_payoff_reversal`, `assignment_derecognition`, `assignment_retained_settlement`, `assignment_repurchase`, `credit_loss_recovery`, and `compensation_control`.

The screen does not record these events: `accrual_fee_amortization`, `charge_appropriation`, `renegotiation_derecognition`, `renegotiation_recognition`, `assignment_secured_borrowing`, `assignment_funding_amortization`, `assignment_funding_payoff`, and the four `returned_payment_*` events. To carry one of them, send the chart with `POST /api/v1/loan-products/{id}/accounting-profiles`, with the same two permissions. A product renegotiates substantially only with the pair `renegotiation_derecognition` and `renegotiation_recognition`, so you send that chart through the API.

The screen does not copy a chart that has a rule it cannot edit. The sheet then opens empty, and the notice **This chart has rules this screen cannot edit** names those rules.

## Reconcile with Midaz

***

Each posting is a Midaz transaction. Use these fields to find it.

| Midaz field | What Lender puts there |
| - | - |
| Description | The event, a colon, and the reference of the source: `<eventType>:<reference>`. |
| Metadata `correlationId` | The posting key. |
| Metadata `loanAccountId` | The loan account of the posting, when known. |
| Metadata `requestId` | The API request that caused the posting, when known. |

See [Accounting and accrual runs](https://docs.lerian.studio/en/products/lender/accounting-and-accrual-runs.md) for receipts, journal references, and parked postings.

## Next steps

***

> [card] [Accounting and accrual runs](https://docs.lerian.studio/en/products/lender/accounting-and-accrual-runs.md)
>
> See how a posting reaches the ledger, and how accrual runs book interest.

> [card] [Define a loan product](https://docs.lerian.studio/en/products/lender/define-a-loan-product.md)
>
> Create the product and the version that the chart serves.

> [card] [Credit in the Console](https://docs.lerian.studio/en/products/lender/console/credit.md)
>
> Configure the chart and run chart changes in the Console.

> [card] [Brazil regulatory pack](https://docs.lerian.studio/en/products/lender/brazil-regulatory-pack.md)
>
> Layer CET, IOF, and PDD staging on top of the accounting model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.