Prerequisites

Lender needs a small set of things in place before its first API call. This page lists them in the order you set them up. When every item here is true, follow the Quick start to originate a loan.

​

Services Lender depends on

---

PostgreSQL, Valkey, and RedPanda are required: Lender does not start without the event backbone. An identity provider is required when route authorization is enabled, which is the default. Production requires it. A first loan needs no Midaz. Read Ledger postings below for what waits.

​

Run Lender locally

---

Lender is a single Go service. A local run needs the Go toolchain at 1.26 or later, Docker with Compose, and Make.

​

Apply the migrations

---

Lender does not migrate the database when it starts. You apply migrations out of band, from one set in the migrations directory. The container image carries a /migrate binary that applies it. The set also seeds the jurisdiction registry: two active jurisdictions, BR for Brazil and XX, the generic base. No API creates a jurisdiction. The deployed binary carries each profile’s behavior, and the table records which codes that binary knows. Read Jurisdictions for what a profile decides.

​

Required configuration

---

The PostgreSQL outbox is mandatory and is initialized automatically. Configure authentication when your deployment enables route authorization.

​

An authenticated subject: PLUGIN_AUTH_ENABLED=true, the default

Lender records who acted on every loan application. It reads the assigned officer from the bearer token’s subject, not from the request body. Every loan-application call therefore needs an authenticated identity. PLUGIN_AUTH_ENABLED defaults to true. Set PLUGIN_AUTH_HOST to the address of your identity provider. Then send a bearer token on every call. The token needs a non-empty subject claim, and the same subject must create, approve, and disburse the application. Lender defines its roles and permissions in a seed file. Load that seed into your identity provider. The officer’s role needs these permissions:

​

A durable posting sink: always present

A disbursed loan records its posting intent durably. Lender initializes its transactional PostgreSQL outbox on every deployment, in the same database transaction that moves the application to disbursed. OUTBOX_ENABLED does not exist. The dispatcher relays each intent afterwards, on the cadence OUTBOX_DISPATCH_INTERVAL_SEC sets. Read Accounting and accrual runs for what the ledger receives.

​

Ledger postings

---

Point Lender at Midaz when you want postings to land in the ledger: The loan originates with or without these. Until you configure a ledger endpoint, posting intents stay durable in the outbox and the ledger entry waits. Configure the ledger before you expect bookings.

​

Tenant defaults

---

DEFAULT_TENANT_ID identifies the tenant, and it must be a valid UUID. The migrations bind the default tenant, 11111111-1111-1111-1111-111111111111, to BR. If you set another DEFAULT_TENANT_ID, add its row to public.tenant_jurisdictions, or Lender refuses its requests with 403.

​

Event streaming

---

Lender does not start without the event backbone. Set STREAMING_ENABLED=true, point STREAMING_BROKERS at RedPanda, and set STREAMING_CLOUDEVENTS_SOURCE=lender. Lender validates these values when it starts.

​

Checklist

---

• PostgreSQL 17, Valkey 8, and RedPanda reachable.
• Migrations applied.
• STREAMING_ENABLED=true and STREAMING_BROKERS set.
• When route authorization is enabled, ensure the identity provider is reachable, and use a bearer token with a subject and every permission in the table above.
• DEFAULT_TENANT_ID a valid UUID.

​

Next steps

---