9. Installments / BNPL

← Business Requirements

(a) Business requirements

  • BNPL is offered as an alternative checkout. The decisive, verified model is full-upfront settlement: on approval the BNPL provider pays Balinyaar the full booking amount in one lump, net of the provider's merchant commission, and bears 100% of customer-default risk. The customer's interest-free installment repayment (typically a 4-installment plan) is owned entirely by the provider and is decoupled from Balinyaar's escrow/EVV/payout cycle.
  • Therefore a BNPL order is, in Balinyaar's books, identical to a card payment that lands net-of-fee in one inbound settlement. Balinyaar does NOT track customer installments, per-installment webhooks, or default propagation — that fragile subsystem is intentionally not built.
  • A BNPL order is recorded once as a single inbound settlement in bnpl_transactions (1:1 with a payment transaction), capturing the provider, the merchant-of-record (Balinyaar), the external payment token / transaction id, order_amount_irr, settled_amount_irr (net of provider commission), bnpl_commission_irr, currency (converted at the boundary), an idempotent status state-machine (eligible/token_issued/verified/settled/reverted/cancelled/failed), installment_count (informational, default 4), settled_at, and the revert fields.
  • BNPL refunds flow only customer ↔ provider ↔ Balinyaar — never nurse→customer or Balinyaar→customer directly. Balinyaar initiates the reversal via the provider's revert (full) / cancel/update (partial, new amount strictly lower) API using the stored token; the provider cancels the customer's unpaid installments, restores their credit, and refunds any already-paid installment to the customer's bank in ~7–10 business days (asynchronous, owned by the provider). The refund still decomposes across the platform-fee and nurse-payout legs in Balinyaar's ledger.
  • The nurse's payout is unchanged by BNPL: computed from gross_price_irr − balinyaar_commission_irr, paid weekly after EVV + dispute window — the provider's commission is a platform cost of accepting BNPL and is never passed through to the nurse.

This is a summary. Deep BNPL provider mechanics, the exact revert/cancel/settle API flows, commission-as-config, settlement-timing nuances, and provider-specific behavior are specified in the payments docs — cross-reference the BNPL landscape and cancellation & payout for implementation detail.

(b) Iran-specific considerations

  • Provider-financed Iranian BNPLs (SnappPay, Digipay, Tara, Torob Pay) are uniformly full-upfront, provider-bears-risk, interest-free-to-customer; only bank-financed POS loans (Lendo) charge the customer interest and are a poor fit for short, cancellable nursing visits.
  • Settlement timing is contract-defined and may be gated on the customer's first installment (daily / T+1-3 / weekly / 15-day) — "full amount" does not mean "instant cash." Timing is config + a per-transaction settled_at; weekly nurse payout may key off settlement actually received, never an assumption.
  • Commission rate is per-contract and not public (anecdotal 7–15% for SnappPay; Torob Pay's published 6.6%) — always a config field read from the actual settlement, never hardcoded.
  • Onboarding requires جواز کسب and اینماد for the Balinyaar/partner entity, and whether a multi-vendor re-disbursing marketplace qualifies as a single BNPL merchant is publicly undocumented — an ops/contracting task, not a schema dependency.

(c) MVP vs DEFERRED

  • MVP: full-upfront BNPL via one provider modeled as a single inbound settlement (bnpl_transactions); provider-mediated revert/cancel refunds; nurse payout decoupled from BNPL; commission + settlement timing as config.
  • DEFERRED: customer installment tracking (installment_entries — cut, owned by the provider); tranched settlement (bnpl_settlement_entries modeled-only, added if a future provider tranches); multiple BNPL providers.

(d) Supporting database entities

bnpl_transactions (replaces the old installment_plans; the old installment_entries is cut), payment_transactions, payment_webhook_events, refunds (refund_channel = 'bnpl_revert', external_revert_reference, expected_customer_refund_eta), ledger_entries. See the BNPL landscape and cancellation & payout payments docs.

Related: Data model — BNPL.

↑ Back to top