Skip to main content
Money events, such as a disbursement, a repayment, or an interest accrual, reach the . Lender’s accounting layer is how they get there. A product declares its posting rules once. From then on, each of those events books automatically and traceably.

Accounting profiles and posting rules


An accounting profile binds a product version to the ledger. It defines the posting rules: the legs that fire for each kind of financial event. It also defines the ledger organization and ledger the resulting transactions book into. You create a profile per product version: POST /api/v1/loan-products/{id}/accounting-profiles Lender validates the posting rules when you create the profile. A product therefore cannot go live with legs that would not balance. A profile needs the ten base rules and the four provision rules, and each leg declares the nature of its account. Define a loan product lists them. Map your chart of accounts walks through the ledger, every event, and the accounts you define.

Posting intents and the relay


Lender does not call the ledger inline. When a financial event happens, Lender persists a durable posting intent. That write happens in the same database transaction that changes domain state. A relay then posts the balanced transaction to Midaz asynchronously. These properties make bookings reliable:
  • The intent commits with the state change: both land in one database transaction, through a transactional outbox.
  • Idempotent: each posting carries a deterministic key, so retries collapse to one ledger transaction.
  • Fails closed: if routing cannot resolve a non-empty ledger target, Lender refuses the post and does not write it to the wrong place.
  • Dated by the accounting date: Midaz receives the date Lender books the posting on. It is the money date for a payment, an exit or a disbursement, and the last day of the closed month for a month-close or correction posting. When Midaz refuses a date in an archived month, Lender posts into the open month.
Lender in the platform describes the full path.

Release a posting parked before Midaz


When the relay runs out of attempts for a posting, the outbox quarantines it. GET /api/v1/internal/accounting/parked-postings lists the quarantined postings that Midaz has not answered for, longest parked first, at most 100. Each line names the contract, the posting, its amount, its fact date, its attempts, its last error, and the posting key to look up in Midaz. POST /api/v1/internal/accounting/parked-postings/{eventId}/release runs the posting through the relay again, and the relay asks Midaz first. If Midaz shows the posting under its posting key, Lender writes the receipt and sends nothing. When Lender sent the posting long ago and its search finds nothing, Lender refuses the release with LENDER-0457. Look the posting key up in Midaz, then repeat the release with midazTransactionId when Midaz holds the transaction, or with ledgerCheckedAbsentSentAt, set to the lastSentAt of the case, when Midaz holds nothing. A transaction that is not the posting’s is refused with LENDER-0463, and an unknown event id with LENDER-0456. If Midaz refuses the posting, the case stays open (LENDER-0458). If Midaz gives no answer, repeat the release (LENDER-0462). Lender writes each attempt to the audit history of the contract. The action is accounting:requeue, and the operator, editor, and admin roles hold it.

Accrual runs


An accrual run recognizes interest and the other time-based amounts. One run closes the last civil month that had fully ended before its business date, for every loan it selects. It also produces the postings for that month. POST /api/v1/accrual-runs starts a run. Lender selects the candidate loan accounts itself, recognizes interest per account, and writes one posting intent per recognition.
Recognition is idempotent per loan account, per accounting month, and per amount kind. A run started twice for the same month recognizes interest once.

Retrying a run


A recognition is durable the moment the run commits. The ledger booking is not. When a posting never arrives, retry the run instead of starting a new one. POST /api/v1/accrual-runs/{id}/retry names the items to re-send, and takes the same X-Idempotency header the run itself takes. It is a second attempt on the same run, so Lender records no second run. For every named item the ledger has not acknowledged, Lender re-sends the posting already enqueued under the deterministic key, and builds one only when none exists. The relay delivers it, and the ledger treats a duplicate as a duplicate rather than as a second booking. Lender leaves alone the items the ledger already acknowledged. The answer names, item by item, what it could not re-send. It also names why: the posting had already been delivered, it was quarantined, the contract behind it is gone, or the product is misconfigured.

Journal references


Each accrual run records a journal reference, the run’s own accounting identifier. The reference record also stores the correlation id that Lender derived for the run. The journal reference id identifies one run exactly. A read by correlation id returns the most recent run that shares that mode, business date, and product scope. A run emits one posting per loan account, per accounting month, per amount kind. Lender therefore records the tie back to the ledger per posting, not per run. Once the ledger acknowledges a posting, Lender stores a receipt under that posting’s own key. A read by that key answers with the ledger transaction that booked it. A run-level reference carries no ledger transaction of its own: it names the run, and the receipts name the bookings.

Next steps


Map your chart of accounts

Choose the ledger, map each accounting event to your accounts, and change the chart later.

Jurisdictions

See how the active jurisdiction shapes disclosures and endpoints.

Brazil regulatory pack

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