How accrual works

Lender does not recognize interest continuously. It recognizes interest in an accrual run. One run covers one business date, and for every loan it selects it recognizes exactly one accounting month.

​

One month per loan, on the loan’s own anniversary

---

A loan’s accounting month is its competência. The disbursement date anchors it, not the calendar. A loan disbursed on the 12th closes each competência on the 12th of the months that follow. A disbursement late in the month clamps onto the last day of a shorter month. The business date you pass to a run selects the competência. A loan recognizes only when the business date is one of its own anniversaries. A run on the 12th therefore recognizes the loans with a 12th disbursement date, and passes over the rest. Plan the calendar around this. To cover a whole book across a month, start a run on every business date.

​

What a run does

---

POST /api/v1/accrual-runs takes the business date and the run mode, and, optionally, up to 100 loan product ids that scope the run. Both businessDate and mode are required. The scheduled driver sends monthly.

​

The amount Lender recognizes

---

Recognition follows the effective interest method. The amortized cost starts at the principal the schedule amortizes, less the origination fee. Withholding taxes stay outside it: in Brazil, IOF is a pass-through and never enters the amortized cost. Lender solves the rate from the schedule itself, so the recognized interest reproduces the contract instead of a separate rate you maintain. Where the jurisdiction taxes interest revenue, the run recognizes that tax too. The tax is a second amount on the same loan and the same competência, with its own balanced posting. Interest and tax never share a transaction.

​

Once per loan, per month, per amount

---

A recognition is unique on three things: the loan account, the competência, and the kind of amount. A second run for the same business date recognizes nothing new for a loan already recognized. It does not double the interest and it does not enqueue a second posting. That uniqueness is the money-path guarantee. It also makes a run safe to repeat after an interruption.

​

What a run produces

---

A run answers with:

• The run identifier and the status of the run.
• A journal reference — the accounting identifier of the run.
• The correlation id Lender derives from the mode, the business date, and the products in scope.

Behind that answer, the run stores one item for each recognition: the loan account, the competência, the kind of amount, and the amount. Those items are what Lender builds the postings from. Use the journal reference id to tie the run to your own accounting records: it identifies one run exactly. The reference record also stores the correlation id, and because Lender derives that id from the mode, the business date, and the products in scope, a read by correlation id returns the most recent run that shares it. Accounting and accrual runs covers the two operations that read it back.

​

The run does not write the ledger entry

---

This boundary matters. A run recognizes interest and enqueues a posting intent. It does not call Midaz, and it does not wait for a booking. The relay posts afterwards, and the ledger books the transaction. A successful run means the recognition and its intent are durable — not that the ledger already shows the entry. Configure two things before a posting can book:

• Give the product version’s accounting profile a rule for the accrual event, with balanced legs. Where the jurisdiction taxes interest revenue, add the optional accrual_tax rule as well, so the tax has legs of its own.
• Enable the outbox and configure the connection to the ledger. See Configuration and deploy.

Configure the profile before the first run. Without an accrual rule, Lender has no legs to build a posting from, and the run leaves that loan out.

​

Loans a run passes over

---

A selected loan can still recognize nothing:

• The jurisdiction suspends its accrual. In Brazil, the two deepest stages of the provisioning ladder suspend accrual — see Brazil regulatory pack.
• The business date is not one of its anniversaries.
• Its interest for that competência is zero.

None of these fails the run. A run recognizes what it can and reports what it recognized.

​

Running accrual on a schedule

---

The run also has a scheduled driver inside the service. It stays off until you enable it, and you set its cron expression, which defaults to the first day of each month. Give it a daily expression: each loan recognizes on its own anniversary, so only a daily driver covers the whole book over a month. Under multi-tenancy the driver runs once for each active tenant, against that tenant’s own data. The scheduled path and the API path use the same code. A run from cron and a run from a call behave identically.

​

Next steps

---