One closed civil month, the same one for every loan
A loan’s accounting month is its competência, and the calendar anchors it, not the disbursement date. A run recognizes the last civil month that had fully ended before its business date. It recognizes that same month for every loan it selects. A run on any day of April closes March. The mapping is total. Every business date names exactly one competência, and that competência is always a month that is over. No run can recognize a month still in progress. Which month a run closes is a property of the service, not of the day you happened to start it. A loan disbursed mid-month is not left out of its first month. Interest spreads across the days of each schedule interval, and a competência collects whatever falls inside it. A loan disbursed on the 12th therefore recognizes that first part-month inside the month it was contracted in.
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. mode labels the run for your own reporting, with one reservation. The heartbeat mode belongs to the scheduled driver, and Lender refuses a call that sends it.
1
Lender selects the loans
You do not send a list. Lender reads its own book and takes each loan account in a disbursed or active application, within the products you scoped. A loan account that already settled drops out. One run covers the whole book. It walks the candidates page by page until they run out, so no contract misses a competência because the book grew.
2
Lender recognizes the interest
For each loan, Lender solves the effective interest rate of the contractual schedule and takes the line for that competência. Recognition works on the contractual cash flows. What the borrower paid does not change it.
3
Lender writes the recognition and the posting intent
One database transaction stores the run, one item per recognition, and the balanced posting intent behind each item. Either all of it is durable, or none of it is.
4
The relay delivers the posting
After the run commits, the outbox relay posts the balanced transaction to Midaz, and Midaz books it.
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.
The run does not write the ledger entry
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. A posting that never reached the ledger is not lost work. Retry the run. Lender rebuilds the intent behind every item the ledger has not acknowledged and enqueues it again under the same deterministic key. As a result, the relay delivers it, and a duplicate stays a duplicate. Accounting and accrual runs covers what a retry answers back. Configure two things before a posting can book:
- Give the product version’s accounting profile a rule for the
accrualevent, with balanced legs. Where the jurisdiction taxes interest revenue, add the optionalaccrual_taxrule as well, so the tax has legs of its own. - Lender always initializes the outbox. Configure the connection to the ledger so the relay can deliver the durable intent. See Configuration and deploy.
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). A suspended contract still books its retained origination fee; the interest is what it withholds.
- An earlier run already decided that competência for it.
- Its interest for that competência is zero.
Running accrual on a schedule
The run also has a scheduled driver inside the service, and it ships on. It fires every day at 06:00 UTC until you give it another cron expression. Daily does not mean a competência a day. Every fire closes the same month, the first one that succeeds decides it, and every later fire that month finds the work already done. The daily cadence is a retry. A service that is down on the 1st closes the month on the 2nd. A once-a-month expression would have lost that competência for good. 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
Accounting and accrual runs
Accounting profiles, posting rules, and the journal-reference operations.
Lender architecture
The domains, the jurisdiction seam, and the outbox that carries money out.
Define a loan product
Products, versions, and the accounting profile a run depends on.
Brazil regulatory pack
Provisioning stages, taxes, and the disclosures the Brazilian profile adds.