Skip to main content
Lender’s REST API is the whole client surface. Products, applications, loan accounts, accrual runs, and the Brazilian regulatory records are all HTTP calls under /api/v1. Nothing exists only inside a client library. Call Lender with the HTTP client your stack already has. There is no Lender client library to install, so the API is the contract you write against. This page covers what your client must handle and what to keep on your own side. It then covers how to place Lender behind a product your users already talk to. Read Lender REST API for the operations themselves.
The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for client or SDK generation.

​
What your client must handle

Four rules cover most of the code you write against Lender.

​
Money travels as a decimal string

Money amounts are JSON decimal strings, normally with two decimal places. Decimal rates such as requestedInterestRate are strings with eight decimal places; fixedAnnualRateBps, floatingSpreadBps, and annualRateBps are integer basis points:
Send the string, and parse the string with your language’s decimal type. A binary float loses cents, and a JSON number invites one. Timestamps are RFC 3339 in UTC.

​
Errors answer problem+json

Most operation and fallback errors answer application/problem+json; do not assume that for lib-auth 401/403 responses. Branch on status and content type. A schema-validation 422 can include an errors array with field details, while handler or domain validation can return only top-level detail. Treat detail as text for a person, not as a key your code matches on. A server-side failure answers with a generic detail on purpose, so no internal cause reaches a client. Log the status and your own correlation identifier, and let Lender’s traces carry the rest.

​
Retry the money writes with your own key

Disbursement, product charges, prepayment, Brazil-pack prepayment, reschedule, repayment, and reversal each accept an idempotency key that you generate. Derive it from your own request identifier, and a retry costs nothing while the idempotency store is available. The five operations that require X-Idempotency replay a completed call with X-Idempotency-Replayed: true on the response. They answer 409 while the first call is still in flight. Repayment and reversal key on X-Request-ID instead, and fall back to X-Idempotency when it is absent: a retry with the same facts replays, and the same id with different facts answers 409. So branch on the response body, never on the presence of the replay header. The middleware fails open during an idempotency-store outage, so an ambiguous failure may already have executed the operation; confirm the outcome before you retry a money write in that window. Lender REST API lists which header each of those operations takes, and how long a key lives.

​
Page with filters, not with deep offsets

Paging is per operation. The product list reads take limit and offset. The audit history takes limit alone. A value outside the declared range answers 422 rather than a quietly reduced page. Read the reference page for the operation you call, and narrow the query instead of walking a long offset.

​
Keep the identifiers your writes return

The origination operations are commands: create, approve, reject, withdraw, and disburse. Each one answers with the full application body. Its id identifies the loan application; after disbursement, disbursementEvent.loanAccountId identifies the loan account. Store both on your side as you go. Your own record then links your borrower to the loan account. Every servicing read starts from an identifier you already hold, because the schedule, the transactions, the charges, and the audit history all key on the loan account.

​
Embedding Lender behind your own product

Lender is a service you deploy, not a library you link. To put it behind an application your customers already use, keep the credentials on your side and call Lender server to server. Four rules keep that boundary clean. Never hand a Lender token to a browser or a mobile app. Your service authenticates your user and decides whether that user may act. It then calls Lender with a token of its own. Mint the token for the person who acts. Lender derives the HTTP actor from the token subject, never from a request field. In the generic human flow, the assigned officer approves and rejects; either the borrower or assigned officer may withdraw. The pinned jurisdiction’s actor policy governs approval and disbursement, so do not assume one human subject performs every transition. Hold one credential per tenant. In single-tenant mode Lender uses DEFAULT_TENANT_ID. In multi-tenant mode the tenant comes from the validated identity, never from a header, a query parameter, or a body field: each token carries a tenantId claim, so your service holds one credential for every tenant it serves. Read Multi-tenancy. Learn about state changes from events. When streaming is enabled and a broker is configured, Lender publishes business events through its outbox. When streaming is disabled, it uses a no-op emitter; when streaming is enabled with no broker configured, Lender refuses to start rather than fall back to the no-op emitter. Enable and configure streaming before treating event delivery as an integration contract. Read Lender events.
A disbursement records its posting intent in the same database transaction that moves the application to disbursed. Lender relays it to Midaz only when the ledger relay is configured; otherwise the intent remains in the outbox. Do not treat a 200 on disburse as proof that the ledger already carries the entry. Read Accounting and accrual runs.

​
Next steps

Lender REST API

The base path, authentication, idempotency, and the operations by job.

Lender events

The wire contract and the events you can subscribe to.

Quick start

Six calls from an empty database to a disbursed loan.

Prerequisites

The services, migrations, and configuration a first call needs.