Skip to main content

Modelling Example: Secured Auto Loan

This document shows how to map a secured amortized loan — vehicle finance — onto the platform. The client described here ("AutoCredi") is fictional. Companion examples: BNPL, Personal Loan, Recurring Invoices, Debt Buyer, Revolving Credit, B2B Invoices.

An auto loan is financially a personal loan (amortized instalments, acceleration, accrual — the personal loan example applies wholesale) with two twists:

  1. Collateral exists but is not a platform entity. There is no "asset" or "security" in the Account/Product/Claim model — the vehicle, its valuation, and the repossession process live in meta and in client-side policy. This is a modelling limitation to communicate, not to work around.
  2. Auto lenders lean on curative servicing treatments — "skip a payment", "extend the term" — because keeping the loan alive beats repossessing a depreciating asset. The platform has no dedicated deferral or restructuring service; both treatments are built from claim-level operations (update_claims on due dates, typed claim relations) plus the Receive Instalment Plan, with the offer/approval policy living in the client's core.

Curative treatments without dedicated services​

  • Payment deferral ("skip a payment") — a due-date shift via update_claims on currentDueDate for the affected claims. If the deferral is priced, the fee is placed as its own claim that declares a DEFERS relation to the claims it postpones, and the client applies the date shift when the fee claim resolves (consumable via the claim events). If the client defers for free in hardship cases, the whole treatment is a single update_claims call.
  • Term change / new schedule — a Receive Instalment Plan spanning the open claims: the plan consolidates them for payment, the new schedule stretches the arrears, and a missed plan payment invalidates the plan and reinstates the claims. Alternatively, if the client executes the term extension in its own core, it places the result as a new claim declaring relatedClaims: [{ "type": "RESTRUCTURES", ... }] against the claims it re-schedules — so forborne exposure stays distinguishable from consolidation (REPLACES) and from cure-by-new-agreement (REFINANCES) in reporting.

The trade-off to communicate in discovery: the platform executes the mechanics (date shifts, plan schedules, relations); the policy (who qualifies, how often, fee-gating) is the client's logic, driven by claim events.

Entity mapping​

Auto-loan conceptPlatform entity / mechanism
BorrowerAccount
Financed vehicle + contractProduct (type: "AUTO_LOAN"; meta: VIN, model, valuation)
Overdue instalmentClaim (one per missed instalment, grouped by productReference)
Accelerated balanceClaim for the enforceable balance (as personal loan Phase 2)
Payment deferralupdate_claims on currentDueDate (+ optional DEFERS fee claim)
Term change / new scheduleReceive Instalment Plan over the open claims, or a new claim with a RESTRUCTURES relation
Repossession status/valuationProduct.meta / Claim.meta (no collateral entity)
Repossession sale proceedscredit_claims
Deficiency balanceThe remaining claim amount after the proceeds credit
Co-signer / guarantoradditionalDebtors vs linked claims — see the personal loan example

Fictional client: "AutoCredi"​

Assumed policies:

  • Used-car loans, €8,000–€35,000, 36–72 months, vehicle as security.
  • Curative-first: up to two deferrals per year (deferral fee €45), and one restructuring (term extension) per loan lifetime, offered before any acceleration.
  • Acceleration after 3 missed instalments → demand for the outstanding balance; if unpaid in 30 days, repossession.
  • After repossession: vehicle sold at auction, proceeds credited, the deficiency balance (loan minus proceeds minus costs, plus repossession costs) is collected as unsecured debt.

AutoCredi's core system remains the source of truth for the loan schedule: each instalment that falls due unpaid is placed as a claim.

Worked example: Diego's car loan​

Diego finances €18,000 over 60 months (~€350/month) for a 2022 SUV.

  • Account = Diego. Product = AC-LOAN-7742, type: "AUTO_LOAN", meta: { "vin": "WVWZZZ...", "vehicle": "SUV 2022", "originalValuation": 21000 }.

Months 14–15 — hardship, curative path. Diego misses two instalments; AutoCredi's core places them as claims (AC-LOAN-7742-INST-14, -INST-15, €350 each). Diego requests a deferral. AutoCredi places the €45 deferral fee as its own claim:

// POST /v1/{clientId}/create_claims
{
  "AC-LOAN-7742-DEFER-01": {
    "amount": 4500,
    "currency": "EUR",
    "originalDueDate": "2026-08-01",
    "currentDueDate": "2026-08-01",
    "productReference": "AC-LOAN-7742",
    "relatedClaims": [
      { "type": "DEFERS", "claimReference": "AC-LOAN-7742-INST-14" },
      { "type": "DEFERS", "claimReference": "AC-LOAN-7742-INST-15" },
    ],
    "meta": { "shiftDays": 60 },
  },
}

When the fee claim resolves (Diego pays it), AutoCredi applies the shift:

// POST /v1/{clientId}/update_claims
{
  "AC-LOAN-7742-INST-14": { "currentDueDate": "2026-09-15" },
  "AC-LOAN-7742-INST-15": { "currentDueDate": "2026-10-15" },
}

The fee-gating — "the deferral only takes effect once the fee is paid" — is AutoCredi's logic, triggered by the fee claim's resolution event.

Month 20 — deeper hardship. Deferral wasn't enough. AutoCredi offers a term change: a Receive Instalment Plan spanning the open instalment claims — the plan consolidates them for payment, the new schedule stretches the arrears over 12 months, and a missed plan payment invalidates the plan and reinstates the claims. (Had AutoCredi executed the extension in its own core instead, it would place the result as a new claim with RESTRUCTURES relations to the claims it replaces.)

Month 26 — default and acceleration. Diego stops paying the plan. AutoCredi accelerates: outstanding balance ≈ €13,200 becomes due. From here the flow is the personal-loan Phase 2 — one claim for the enforceable balance (principal in amount, accrued interest and fees named in fees), the vehicle's current valuation snapshotted in meta for settlement-offer calibration.

Repossession and deficiency. The SUV sells at auction for €9,000; repossession and auction costs are €800:

// Proceeds reduce the debt:
// POST /v1/{clientId}/credit_claims
{ "AC-LOAN-7742-ACCEL": { "amount": 900000, "fees": 0 } }

// Costs are added (contractually recoverable):
// POST /v1/{clientId}/debit_claims
{ "AC-LOAN-7742-ACCEL": { "amount": 0, "fees": [{ "name": "repossessionCosts", "amount": 80000 }] } }

The remaining ~€5,000 deficiency balance is now ordinary unsecured debt — standard strategies, settlement offers, or a Receive Instalment Plan apply. Note the platform never "knew" about the car: the entire secured dimension was client policy plus meta context, and the sale entered the model as a credit like any other payment.

Discovery questions for a real auto-loan client​

  1. How much of the deferral logic can live in the client's core? The fee-gating and the date arithmetic are client-side, driven by claim events. If their core cannot react to claim-resolution events, deferrals can still be offered fee-free (a single update_claims call) — confirm which variant matches their product terms.
  2. Does a restructuring need to cover future, not-yet-due instalments? The Receive Instalment Plan restructures what has been placed; instalments still in the client's core are re-scheduled there (and, if placed later as a new agreement, related via RESTRUCTURES). Agree where that boundary sits.
  3. Who runs the repossession process and what must the platform reflect? Timeline flags (notice sent, vehicle recovered, sold) are meta/journey concerns; the financial effects are just credits and debits. Ensure the pause of dunning during legally mandated repossession windows is mapped to pause_journeys.
  4. How is the deficiency computed and evidenced? Sale proceeds, costs, valuation reports — agree what lands in meta at each step, since deficiency claims get challenged and the audit trail must be reconstructable.
  5. Accrual, acceleration composition, co-signers — inherit questions 1–4 from the personal loan example; they apply unchanged.

This example focuses on what to model; the step-by-step mechanics of each API call are covered by the generic use cases: