baya-monorepo/product/payments/index.md

# Payments, Escrow, Settlement & Installments (BNPL)

> **Purpose.** This is the fintech deep-dive for Balinyaar, an MVP home-nursing marketplace in Iran. It pins down how the platform collects money from families, holds an *internal escrow ledger state* (not custodied cash), pays nurses weekly minus commission, and integrates Iranian Buy-Now-Pay-Later (خرید اقساطی / BNPL). It answers the two questions the team cares most about — how a BNPL booking is cancelled/refunded mid-plan, and who pays the nurse (and when) under BNPL — and it grounds every decision in verified research, separating **VERIFIED** facts from **CONFIGURABLE / UNCERTAIN** items that must be confirmed at contracting. All money is **IRR (Rials), stored as `BIGINT`**; Toman is display-only and converted only at the provider API boundary.

**Date:** 2026-06-20

---

## 1. Executive summary

- **Balinyaar legally CANNOT custody buyer funds.** In Iran money always flows card → licensed PSP → Shaparak settlement → bank-registered IBANs. A پرداخت‌یار (payment facilitator — the license class an MVP rides on) is explicitly **barred from holding deposits, running wallets, paying interest, or moving money between merchants**. "Platform holds escrow" must therefore be implemented as an **internal double-entry ledger state** over funds custodied at a licensed provider — never as cash in a Balinyaar bank account. *(VERIFIED — multiple independent sources + CBI/Shaparak directives.)*

- **The compliant marketplace primitive is تسهیم (settlement-sharing):** one incoming card payment is split by the provider/Shaparak across multiple registered IBANs (the nurse's share, the platform's commission) and deposited directly — the platform never touches the split. Shaparak has separately **banned inter-merchant / inter-facilitator transfers and wallet-style holding**, which makes a "delay-then-redistribute" pool legally grey-to-prohibited. *(VERIFIED.)*

- **The decisive BNPL finding: full-upfront settlement.** Provider-financed Iranian BNPLs (SnappPay, Digipay, Tara, Torob Pay, ZarinPlus) pay the **merchant the FULL amount in ONE lump, minus a merchant commission, and bear 100% of customer-default risk.** The customer's installments are owned entirely by the provider and are **decoupled** from Balinyaar's escrow/EVV/payout cycle. *(VERIFIED for SnappPay and Torob Pay from credible sources; consistent for Digipay and Tara.)*

- **Consequence — a BNPL order = a card payment landing net-of-fee.** Therefore Balinyaar **does NOT track customer installments** (no `installment_entries`, no per-installment webhooks, no default propagation). This deletes an entire fragile subsystem.

- **But settlement TIMING is not instant.** The "full amount" is true in *amount*, not *timing*: cadence is contract-defined (daily / T+1–3 / weekly / 15-day), and at least one authoritative SnappPay source gates settlement on the customer's **first installment** (پس از واریز اولین قسط). Model a per-transaction `settled_at`; never assume instant. *(VERIFIED correction to the original research.)*

- **Under BNPL the nurse is paid by Balinyaar, on Balinyaar's own weekly schedule, exactly as for a card booking** — after EVV check-out and the dispute window. The nurse's payout is computed from `gross_price_irr − balinyaar_commission_irr`, **NOT** from the BNPL-net amount. The BNPL commission is a **platform expense** that must never touch the nurse's payout.

- **Avoid Lendo for the MVP.** It is bank-financed (Bank Ayandeh): the **customer** pays ~18–23% interest plus a ~5% (often non-refundable) service fee over 6–12 months — a POS loan, a poor fit for short, cancellable nursing visits.

- **Two corrections the research forced:** VAT in Iran is **10%** (rose from 9% in 1403, = govt 7% + municipal 3%), not 9% — and make it configurable since it has moved two years running (see [legal landscape](../research/legal-landscape.md)). And the Digipay "24h-pay / collect-in-5–25-days-from-business" sentence describes the **early-settlement/factoring** product, **not** BNPL — right conclusion, wrong evidence; the correct first-party BNPL source is `mydigipay.com/bpg/`.

- **Provider continuity is a real risk.** In **Nov 2024 the CBI abruptly cut Toman and Jibit's settlement/withdrawal services** with no stated cause, stranding businesses (including millions of Snapp drivers). Design for multi-provider failover and a reconciliation ledger that survives a provider being cut mid-cycle.

- **Recommendation:** integrate **SnappPay first**, **Digipay second**, **avoid Lendo**. Onboarding the Balinyaar entity needs **both جواز کسب AND eNamad (اینماد)** (see [legal landscape](../research/legal-landscape.md)). Whether a multi-vendor marketplace re-disbursing to many independent nurses qualifies as a single merchant is **publicly UNCONFIRMED** — confirm with provider sales before relying on it.

---

## Sub-pages

- [The Iranian payment reality](iranian-payment-reality.md) — the card → PSP → Shaparak → IBAN rails, the پرداخت‌یار custody prohibition, تسهیم settlement-sharing, banned held pools, provider cut-off risk, and VAT/مودیان.
- [Escrow as an internal ledger](escrow-ledger.md) — why escrow is a double-entry ledger state, the `ledger_entries` account types, and all the balanced posting blocks.
- [BNPL Landscape & the Full-Upfront Finding](bnpl-landscape.md) — the six-provider comparison table and the decisive full-upfront settlement finding plus its verified caveats.
- [BNPL Cancellation, Refund & Nurse Payout (Q1 & Q2)](cancellation-and-payout.md) — how a BNPL booking is unwound mid-plan, and who pays the nurse (and when) including the three-amount split and a worked example.
- [Integration Notes & Schema Touchpoints](integration-notes.md) — SnappPay and Digipay endpoints, cross-cutting integration rules, and the final table/field names.
- [Recommendations, Open Questions & Sources](sources.md) — contracting recommendations, the open-questions checklist, the full source list, and the confidence legend.

See also: the [data model](../data-model/index.md) and the [market research](../research/index.md).