Map your chart of accounts

Lender books every money event of a product in the 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 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 covers how a posting reaches the ledger.

Before you start

Create the loan product and a version first. See Define a loan product.
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. 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.

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

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

Record the change

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

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.

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.

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

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.

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.

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.

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.

Mark the per-contract legs

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

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 for receipts, journal references, and parked postings.

Next steps

Accounting and accrual runs

See how a posting reaches the ledger, and how accrual runs book interest.

Define a loan product

Create the product and the version that the chart serves.

Credit in the Console

Configure the chart and run chart changes in the Console.

Brazil regulatory pack

Layer CET, IOF, and PDD staging on top of the accounting model.

Overview

Getting started

Concepts

Guides

Integration

Operations

Console

Map your chart of accounts

Before you start

The product ledger

Anatomy of a posting rule

Per-contract positions

Example

The accounting events

Required events

Optional events

Events you do not configure

Checks Lender runs on your chart

Read a chart back

Change the chart

Suspense accounts

In the Console

Reconcile with Midaz

Next steps

Accounting and accrual runs

Define a loan product

Credit in the Console

Brazil regulatory pack

​Before you start

​The product ledger

​Anatomy of a posting rule

​Per-contract positions

​Example

​The accounting events

​Required events

​Optional events

​Events you do not configure

​Checks Lender runs on your chart

​Read a chart back

​Change the chart

​Suspense accounts

​In the Console

​Reconcile with Midaz

​Next steps

Accounting and accrual runs

Define a loan product

Credit in the Console

Brazil regulatory pack

Before you start

The product ledger

Anatomy of a posting rule

Per-contract positions

Example

The accounting events

Required events

Optional events

Events you do not configure

Checks Lender runs on your chart

Read a chart back

Change the chart

Suspense accounts

In the Console

Reconcile with Midaz

Next steps