Pulling per-borrower loan and repayment data out of Iustus

₦5,000 to ₦100,000 per borrower, 91 to 180 days per loan, a 10% one-time processing fee, and rate bands at 0.013% to 0.05% interest with a 14–20% APR ceiling — those are the numbers an integrator inherits from the Iustus product, per the Play Store listing. The data of interest is not marketing copy; it is the per-borrower loan ledger the app keeps for each user: principal, processing fee, accrued interest, repayment schedule, repayment events, and the default-flag state. That ledger drives a credit decision somewhere upstream, and a third party plugging Iustus into a wider lending or risk stack needs it in a stable JSON shape, with events arriving fast enough to be acted on.

Our recommendation, before anything else: build the ingester on the event side, not the polling side. A short-tenor product with a 10% one-time processing fee and a 91-day floor sees most of its risk-relevant state changes within the first repayment cycle. A polled snapshot misses that. A normalised webhook channel that fires on disbursement, each repayment, and the default flag captures it.

Routes in

There are three honest ways to reach a borrower's Iustus state, and one of them is the spine.

1. Authorized interface integration of the authenticated session

This is the spine. With the borrower's consent (or in a sponsor sandbox arranged with you during onboarding), we map the app's login, token refresh, and the calls that drive the home dashboard, the application screen, and the repayment screen. The ledger fields we care about — loan_id, principal, fee, interest accrued, due_date, repayment_status — are read from the same surfaces the app uses to render itself. Effort is moderate; durability is good for as long as the operator does not rewrite that surface, and we wire a re-validation job that catches drift.

2. Bank-side reads under the CBN Open Banking framework

Where the integration cares about whether the repayment actually cleared on the borrower's bank account, the CBN's 2023 Operational Guidelines for Open Banking are the lawful route — Nigeria's model is API Consumer / API Provider rather than the UK's AISP/PISP split. We pair the in-app loan-state read with a consent-based bank read (commonly via a Mono or Okra style aggregator) so the integration sees both sides of the rail. Effort is light if the bank is a registered API Provider; freshness is whatever the provider supports.

3. NIBSS iGree BVN-attached identity, only where needed

For any flow that pivots on the borrower's BVN — KYC checks, credit-history pulls against CRC or FirstCentral — the NIBSS iGree consent layer is the lawful gate. We never copy a BVN around without iGree; the integration captures the consent, records it, and passes the resulting token through the chain. This route is narrow on purpose — most of the loan-state work does not need it.

The spine carries the work; the other two are layered on where the integration genuinely needs them.

Reachable data

Sample call

This is the shape of the call your code would make against our hosted side once the integration is live. The wire details against Iustus itself are confirmed during the build; the outward-facing surface is stable.

# Read a borrower's open Iustus loan ledger + the next repayment slot
GET /v1/iustus/borrowers/{borrower_ref}/loans?status=open
Authorization: Bearer ${OFL_TOKEN}
X-Consent-Id:  ${IGREE_OR_SESSION_CONSENT_ID}
X-Idempotency: ${UUID_PER_LOGICAL_READ}

200 OK
{
  "borrower_ref": "ofl_brw_8e0c...",
  "loans": [{
    "loan_id":        "iustus_ln_4f21a9",
    "principal_ngn":   25000,
    "processing_fee":   2500,        // 10% one-time, captured at disbursement
    "interest_rate":    0.035,       // 91-day example, per listing
    "apr_band":        "14-20%",
    "term_days":         91,
    "disbursed_at":    "2026-05-04T09:11:22+01:00",
    "due_at":          "2026-08-03T23:59:59+01:00",
    "outstanding_ngn": 23150,
    "state":           "current",     // current | due | partial | overdue | closed
    "next_repayment": {
      "amount_ngn":     11575,
      "scheduled_for": "2026-06-04T23:59:59+01:00"
    }
  }],
  "as_of": "2026-05-27T07:00:00Z",
  "source": "session-mirror+bank-confirm"
}

# Subscribe to repayment-state webhooks
POST /v1/iustus/webhooks
{ "target": "https://your-app.example/hooks/iustus",
  "events": ["loan.disbursed","repayment.partial","repayment.full",
             "loan.overdue","loan.closed"] }

The X-Consent-Id header is the audit anchor — every read is bound to a specific borrower grant or, for BVN-attached reads, an iGree consent token. If a read lands without it, the gateway refuses it.

What lands on your side

The drop list is biased toward runnable code over paperwork. In rough order:

• A Python ingester (and a parallel Node.js worker where you want Node on the receiver) that opens an authenticated session against Iustus, normalises the ledger fields into the JSON shape above, and writes the events.
• A webhook handler skeleton on your side that verifies our signature, accepts the five repayment-state events, and replays missed events from the reconciliation pull on demand.
• A test harness with recorded HTTP fixtures from the build session, so regression catches the operator silently renaming a field; runs in CI without touching the live app.
• A short batch-vs-realtime sync design note that says, for this product specifically, why the nightly reconciliation pull stays on even after the webhooks are live.
• The OpenAPI spec for the hosted side, with the auth-flow report covering the borrower-session login, token refresh, and the iGree handover when BVN reads are in scope.
• A short compliance memo: where each field came from, what consent record it sits behind, what the retention default is, what NDPC notification posture we used.

Build-side decisions for Iustus

A few app-specific things that shape the build, written as how we handle them:

• SMS-permission posture. The Play Store listing states the app requests SMS access on install to verify identity and build a credit score. Our ingester does not replicate that path; we read the loan-state surfaces the borrower already sees inside the app, under their consent. The SMS-derived credit-score field stays on the operator's side and is not exfiltrated.
• Short-tenor reconciliation. With a 91-day floor and a 10% one-time processing fee captured up front, the early ledger window is the noisy one. We snapshot the disbursement state once, then re-read on every webhook event; the nightly job exists to repair a missed webhook, not to discover the loan in the first place.
• FCCPC DEON conduct rules. The 2025 DEON regulations restrict contact-list scraping and unauthorised borrower contact. The integration does not touch contacts; we keep the consent record alongside the data so any audit can trace a read back to a specific grant.
• Rate-band drift. The 0.013%–0.05% interest and 14%–20% APR ranges quoted by the listing are bands, not fixed values, and the operator can move within them. We persist the per-loan pricing at acceptance time so a later rate change does not silently rewrite history in your store.
• Operator contact channel. The Play Store listing publishes a Lagos address at 23 Adeniyi Jones, Ikeja, a service e-mail, and a hotline. Where the integration needs an out-of-band reconciliation step, we route it through those channels rather than fabricating one.

Consent and Nigerian rules

The lawful basis for the integration is the borrower's own consent — captured at the point we open the session, recorded with timestamp and scope, and revocable. That is the dependable basis. Layered on top, for this market specifically:

• The FCCPC's Digital, Electronic, Online or Non-Traditional Consumer Lending Regulations 2025 (DEON) govern how a Nigerian lender like Iustus may behave toward borrowers. They are a conduct framework; they shape what we are willing to ingest (no contact lists, no harassment-adjacent telemetry) more than they shape the read mechanics.
• The Nigeria Data Protection Regulation, supervised by the Nigeria Data Protection Commission, sets the data-protection floor. Our default is data-minimised reads, encrypted at rest, with retention scoped to the integration's purpose and a documented deletion path.
• Where the integration crosses into BVN territory, the NIBSS iGree consent layer is the gate, the same layer Mono's BVN Lookup and similar providers use.
• The CBN's 2023 Operational Guidelines for Open Banking apply when the integration also reads the borrower's bank account directly — the API Consumer / API Provider model rather than the UK AISP/PISP split.

NDAs are routine where the build sees operator-side traffic. The compliance posture is professional, not gatekeeping; access arrangements are part of the engagement.

Ingestion reliability

Three things will go wrong over a year of running this integration, and the build accounts for each:

• Field renames. The recorded-fixture test harness fails loudly the first time a ledger field changes shape; the re-validation job re-runs it nightly.
• Missed webhooks. The nightly reconciliation pull writes a "gap" event when its computed state differs from the last webhook-derived state, and your side can replay events from a chosen cursor.
• Consent expiry. The borrower's grant is held against a clock; the ingester refuses to read past expiry, and we surface a re-consent prompt back through the borrower channel rather than silently failing.

Adjacent lenders

If your stack already integrates one of these or plans to, the Iustus ingester slots beside it without re-modelling the loan ledger schema; each holds a similar shape of per-borrower loan state, with operator-specific quirks.

• FairMoney — broader Nigerian digital lender with quick personal and business loans; its ledger carries longer-tenor lines than Iustus.
• Carbon — the long-running Nigerian digital lender with loan amounts up to roughly ₦1,000,000 and tenures up to twelve months; richer surrounding banking surface.
• Branch — phone-usage and repayment-history driven scoring; loan ledger plus a wallet surface.
• Renmoney — larger principals and longer tenors; the schedule rows have more rows than a 91-day Iustus loan.
• EaseMoni — small, frequent loans; close in shape to Iustus' short-tenor product.
• NewCredit — longer repayment plans, up to roughly a year; useful contrast row in the ledger.
• Aella Credit — salary-tilted product; identity surface is heavier.
• QuickBucks — Access Bank's own loan app, which means the bank-side rail is the same operator as the lender.
• Okash — Opera's lending product on OPay; product surface looks similar from outside.
• NairaPlus — short-cycle emergency-cash product; closest cousin to Iustus by tenor.

Sources we read

Pages opened while writing this, alongside the app's own Play Store listing for the product-side numbers (principal band, fees, term, APR band, contact details):

• Iustus on Google Play — the operator-published product description and contact block.
• FCCPC DEON Consumer Lending Regulations 2025 (PDF) — the conduct framework for Nigerian digital lenders.
• CBN Operational Guidelines for Open Banking in Nigeria (2023, PDF) — the API Consumer / API Provider model used for bank-side reads.
• Mono BVN iGree Lookup documentation — concrete reference for the NIBSS iGree consent handover where BVN reads are in scope.

Reviewed by the OpenFinance Lab integration desk on 2026-05-27.

Questions integrators tend to ask

What is the ingestion cadence we would target for Iustus loan and repayment data?

For a short-tenor product like Iustus (91 to 180 days) we usually run two cadences in parallel: a near-real-time webhook channel for disbursement and repayment events, and a slower nightly reconciliation pull that re-reads the borrower ledger from the app's authenticated session. The two channels cross-check each other so a missed push never leaves the ingester silently behind.

Do we need NIBSS iGree consent to read BVN-linked identity during the build?

Where the integration touches BVN-attached identity (rather than just the in-app loan ledger), yes — the NIBSS iGree consent layer is the route used by Mono and similar providers in Nigeria, and we wire the same consent capture into the build so each BVN read is traceable to a specific user grant. Loan-state fields that do not require BVN are read through the borrower's authenticated session under their own consent.

How would the webhook surface for repayment events be structured?

We build the webhook surface on our side. The ingester reads the authenticated session, normalises each state transition (disbursed, partial repayment, default flagged, closed) into a stable JSON shape, signs it, and POSTs it to a URL you control. From your code's point of view the integration looks like a webhook subscriber; the upstream cadence is hidden behind the normaliser.

How does the FCCPC DEON 2025 framework affect what we can extract on a Nigerian lender like Iustus?

The DEON regulations published by the FCCPC in 2025 constrain how a lender behaves toward borrowers — contact-list scraping, harassment, opaque pricing — more than they constrain how an authorized integrator reads loan-state data with the borrower's consent. Our extraction stays within authorized, logged, data-minimised reads of fields the borrower has agreed to share, and we keep the consent record alongside the data.

An Iustus ingester is roughly a one-to-two-week build on our side. Source-code delivery starts from $300 — runnable code, OpenAPI spec, tests and interface documentation — paid after delivery once you have the code in hand and are satisfied with it. The alternative is calling our hosted endpoints and paying per call, with no upfront fee. Start a scoping conversation

Mapping reviewed 2026-05-27.