Skip to main content

Modelling Example: BNPL

This document shows how to map a Buy-Now-Pay-Later (BNPL) client onto the platform's Account / Product / Claim model. The client described here ("PagaLuego") is fictional and deliberately configured with the richest possible policy set, so the example exercises every mechanism the model offers: individual instalment claims, claim consolidation, and instalment plans as a collections treatment. A real BNPL client will almost always be a subset of this example — the discovery questions at the end tell you which phases apply.

Guiding principles​

  1. Model what is legally collectible at placement time, not what is elegant. A claim's amount must be the enforceable debt at the moment it is placed — never the full product price if part of it has been paid or is not yet due. Overstating debt in dunning communication is a legal/compliance risk.
  2. The Receive Instalment Plan is a collections treatment, not an origination schedule. Instalment plans (event.instalmentsPlan.*, event.instalment.*) represent a repayment agreement negotiated on top of debt already in collection (via strategy or landing page). The original BNPL payment schedule is the origination contract — do not model it as a Receive instalment plan. Keep the plan free for its natural role: offering the debtor a way to repay a defaulted claim in parts.

Entity mapping​

BNPL conceptPlatform entity
Debtor / shopperAccount (one per debtor, groups all their purchases)
Purchase / financed orderProduct (productReference on each related claim)
Missed instalmentClaim (one per overdue instalment, pre-acceleration)
Accelerated balanceClaim (one new claim for the enforceable balance)
Original payment scheduleProduct.meta (context data, no business logic)
Negotiated repayment planReceive Instalment Plan (collections treatment on the claim)

Schema support (see the API reference):

  • Claim.productReference / Claim.product — ties any number of claims to the purchase. This is the grouping mechanism for "all instalments of one order".
  • Claim.repaymentsHistory — optional record of payments made to the client before placement.
  • Product.meta — free-form context (total price, instalment count, purchase date).
  • Claim.meta — free-form context per claim (e.g. which original instalments an accelerated claim replaces).

compoundClaimRefs is internal — not a client-facing consolidation mechanism. It is not exposed in the ClientApi schema. The platform sets it when creating an instalment plan: it creates a synthetic claim representing the plan (externalClaimRef = plan id, amount = plan total, dueDate = last instalment due date, compoundClaimRefs = the source claims' references), and instalment payments are booked against it. The rest of the platform deliberately ignores compound claims: they are excluded from account creation, search, strategy assignment, and account-claims queries. Do not model client-side debt consolidation with it.

Do NOT use linkGroupId to group instalments. Linked claims (set_link_claims / cmd.linkClaims.set) are mirrors of the same debt: whenever one claim in a link group changes, cmd.linkedClaims.sync overwrites amount, totalFees, and fees on every other claim in the group. It exists for shared-liability scenarios — the same debt reflected on several accounts (co-debtors, guarantors) — where a payment on one must propagate to all. Linking BNPL instalments would make every instalment's amount overwrite the others'.

Fictional client: "PagaLuego"​

Assumed policies (chosen to cover the full hybrid case):

  • Sells products in 6 monthly instalments, interest-free.
  • At the 1st missed instalment, places that instalment in collection but keeps servicing the rest of the credit (the debtor can still pay future instalments to the client directly).
  • At the 3rd consecutive missed instalment, exercises the acceleration clause: the entire remaining balance becomes due.
  • Charges a fixed late fee per overdue instalment.

Worked example: Maria buys a sofa​

Sofa for €900 in 6 instalments of €150. Maria pays the first two, then stops paying.

  • Account = Maria.
  • Product = the sofa: productReference: "PL-ORD-4711", with meta holding the total price, instalment count, and purchase date.

Phase 1 — early arrears (instalments 3 and 4 overdue)​

One claim per missed instalment, all grouped by pointing at the same product:

{
  "externalClaimRef": "PL-ORD-4711-INST-03",
  "amount": 15000, // cents
  "currency": "EUR",
  "dueDate": "2026-05-01",
  "externalDueDate": "2026-05-01",
  "productReference": "PL-ORD-4711",
  "fees": [
    {
      /* late fee for this instalment */
    },
  ],
}

// likewise PL-ORD-4711-INST-04, dueDate 2026-06-01

Each instalment keeps its own dueDate, aging, and fees — correct, because each fell due on a different date. If Maria pays one instalment, that claim resolves individually while the others stay in collection.

Phase 2 — acceleration (instalment 5 falls due unpaid)​

PagaLuego cancels/credits the open instalment claims and places one ordinary claim for the accelerated balance (instalments 3–6 = €600). Consolidation is a client-side operation — credit the old claims, create a new one — and the lineage is declared with typed claim relations (relatedClaims), which keeps the consolidation history queryable through get_account_claims:

{
  "externalClaimRef": "PL-ORD-4711-ACCEL",
  "amount": 60000, // the enforceable accelerated balance — never the product price
  "currency": "EUR",
  "dueDate": "2026-07-01", // acceleration date
  "externalDueDate": "2026-07-01",
  "productReference": "PL-ORD-4711",
  "relatedClaims": [
    { "type": "REPLACES", "claimReference": "PL-ORD-4711-INST-03" },
    { "type": "REPLACES", "claimReference": "PL-ORD-4711-INST-04" },
    { "type": "REPLACES", "claimReference": "PL-ORD-4711-INST-05" },
  ],
}

Payments Maria already made to the client (instalments 1–2) stay on the client's side, or go into repaymentsHistory if the full history is wanted for context.

Phase 3 — collections treatment​

On the consolidated claim, the strategy offers Maria a Receive Instalment Plan (e.g. 4 payments of €150 via the landing page). Internally, the platform creates a compound claim spanning the source claim(s) — this is where compoundClaimRefs comes into play, managed entirely by the platform. If Maria misses a plan payment, the plan is invalidated and the full claim becomes enforceable again — the platform's plan-invalidation semantics mirror the acceleration clause exactly, now managed inside Receive.

Note: an instalment plan can span multiple source claims. So even in Phase 1 (several open instalment claims, no acceleration), the debtor can be offered a single plan covering all of them — the platform consolidates them for payment purposes via the internal compound claim, without the client having to consolidate anything on their side.

Multiple purchases​

If Maria also financed a bicycle, that is a second Product with its own claims, all under the same Account. Account-level strategy decides whether she is contacted once about her total debt or per product.

Discovery questions for a real BNPL client​

Each answer switches a phase of this example on or off:

  1. Is there an acceleration clause, and when is it exercised (first missed instalment, third, at placement)? → No acceleration: Phase 1 only. Accelerates before placement: Phases 2–3 only. Accelerates after placement: full hybrid.
  2. Does the debtor keep paying future instalments to the client directly while we collect the overdue ones? → If yes, per-instalment claims (Phase 1) are mandatory; a single full-balance claim would overstate the enforceable debt.
  3. Are late interest/fees calculated per instalment or on the outstanding balance? → Decides whether fees lives on the individual instalment claims or on the consolidated one.
  4. Should a debtor with several purchases be treated as one case? → Account-level grouping already handles this at the strategy layer, independent of how the claims are modelled.

See also​

  • Personal Loan — interest-bearing amortized loan (accrual after placement, principal/interest split, co-signers).
  • Recurring Invoices — telco/utility subscriptions (ledger-managed integration, ACCOUNT_INVOICE claims, payment matching).
  • Debt Buyer — purchased portfolios (import_claims, portfolioReference, scores-driven segmentation, settlements).
  • Revolving Credit — credit cards (rolling claim via debit_claims/credit_claims, fraud write-offs).
  • B2B Invoices — commercial invoices (legal debtors, disputes, promises to pay).
  • Secured Auto Loan — secured lending (payment deferrals, restructuring, deficiency balance after repossession).

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