hamid
59 lines
11 KiB
HTML
59 lines
11 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>9. Installments / BNPL — Balinyaar docs</title>
|
||
<link rel="stylesheet" href="../assets/doc.css">
|
||
</head>
|
||
<body>
|
||
<div class="layout">
|
||
<aside class="sidebar">
|
||
<a class="brand" href="../index.html"><span class="dot"></span> Balinyaar docs</a>
|
||
<p class="tagline">Trust-first home-nursing marketplace · Iran</p>
|
||
<nav><div class="group"><div class="label">Start here</div><ul><li><a href="../index.html">Docs home</a></li><li><a href="../overview/platform-summary.html">Platform summary & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & onboarding</a></li><li><a href="02-nurse-verification.html">2. Nurse verification</a></li><li><a href="03-service-catalog-and-pricing.html">3. Service catalog & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a href="07-cancellation-and-refunds.html">7. Cancellation & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & escrow</a></li><li><a class="active" href="09-installments-bnpl.html">9. Installments / BNPL</a></li><li><a href="10-payouts.html">10. Payouts to nurses</a></li><li><a href="11-reviews-trust-and-safety.html">11. Reviews, trust & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & decisions</a></li><li><a href="../data-model/diagrams.html">Diagrams</a></li><li><a href="../data-model/01-identity-and-access.html">1. Identity & access</a></li><li><a href="../data-model/02-geography.html">2. Geography</a></li><li><a href="../data-model/03-services-and-pricing.html">3. Services & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & refunds</a></li><li><a href="../data-model/07-payouts.html">7. Payouts</a></li><li><a href="../data-model/08-bnpl.html">8. BNPL / installments</a></li><li><a href="../data-model/09-messaging.html">9. Messaging</a></li><li><a href="../data-model/10-reviews-and-records.html">10. Reviews & records</a></li><li><a href="../data-model/11-notifications.html">11. Notifications</a></li><li><a href="../data-model/12-audit-config-and-reference.html">12. Audit, config & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & exec summary</a></li><li><a href="../payments/iranian-payment-reality.html">Iranian payment reality</a></li><li><a href="../payments/escrow-ledger.html">Escrow as a ledger</a></li><li><a href="../payments/bnpl-landscape.html">BNPL landscape & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & risks</a></li><li><a href="../research/verification.html">Verification (research)</a></li><li><a href="../research/legal-landscape.html">Legal landscape</a></li><li><a href="../research/go-to-market.html">Go-to-market & sources</a></li></ul></div><div class="group"><div class="label">Notes & more</div><ul><li><a href="../notes/open-questions.html">Open questions</a></li><li><a href="../notes/future-ideas.html">Future ideas</a></li><li><a href="../wireframes/index.html">Wireframes</a></li><li><a href="../fa/index.html">Farsi documents</a></li></ul></div></nav>
|
||
</aside>
|
||
<main class="main"><div class="content">
|
||
<div class="topbar"><button class="theme-toggle" type="button" onclick="__t()">theme</button></div>
|
||
<h1 id="9-installments-bnpl">9. Installments / BNPL</h1>
|
||
<p><a href="index.html">← Business Requirements</a></p>
|
||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||
<ul>
|
||
<li>BNPL is offered as an alternative checkout. The decisive, verified model is <strong>full-upfront settlement</strong>: on approval the BNPL provider pays Balinyaar the <strong>full booking amount in one lump, net of the provider's merchant commission</strong>, and <strong>bears 100% of customer-default risk</strong>. The customer's interest-free installment repayment (typically a 4-installment plan) is <strong>owned entirely by the provider</strong> and is <strong>decoupled</strong> from Balinyaar's escrow/EVV/payout cycle.</li>
|
||
<li><strong>Therefore a BNPL order is, in Balinyaar's books, identical to a card payment that lands net-of-fee in one inbound settlement.</strong> Balinyaar <strong>does NOT track customer installments, per-installment webhooks, or default propagation</strong> — that fragile subsystem is intentionally not built.</li>
|
||
<li>A BNPL order is recorded once as a single inbound settlement in <code>bnpl_transactions</code> (1:1 with a payment transaction), capturing the provider, the merchant-of-record (Balinyaar), the external payment token / transaction id, <code>order_amount_irr</code>, <code>settled_amount_irr</code> (net of provider commission), <code>bnpl_commission_irr</code>, currency (converted at the boundary), an idempotent status state-machine (<code>eligible</code>/<code>token_issued</code>/<code>verified</code>/<code>settled</code>/<code>reverted</code>/<code>cancelled</code>/<code>failed</code>), <code>installment_count</code> (informational, default 4), <code>settled_at</code>, and the revert fields.</li>
|
||
<li><strong>BNPL refunds flow only customer ↔ provider ↔ Balinyaar</strong> — 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.</li>
|
||
<li><strong>The nurse's payout is unchanged by BNPL:</strong> computed from <code>gross_price_irr − balinyaar_commission_irr</code>, paid weekly after EVV + dispute window — the provider's commission is a <strong>platform cost of accepting BNPL</strong> and is <strong>never</strong> passed through to the nurse.</li>
|
||
</ul>
|
||
<blockquote><p><strong>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 <a href="../payments/bnpl-landscape.html">BNPL landscape</a> and <a href="../payments/cancellation-and-payout.html">cancellation & payout</a> for implementation detail.</strong></p>
|
||
</blockquote>
|
||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||
<ul>
|
||
<li>Provider-financed Iranian BNPLs (SnappPay, Digipay, Tara, Torob Pay) are uniformly <strong>full-upfront, provider-bears-risk, interest-free-to-customer</strong>; only bank-financed POS loans (Lendo) charge the customer interest and are a poor fit for short, cancellable nursing visits.</li>
|
||
<li><strong>Settlement timing is contract-defined and may be gated on the customer's first installment</strong> (daily / T+1-3 / weekly / 15-day) — "full amount" does not mean "instant cash." Timing is config + a per-transaction <code>settled_at</code>; weekly nurse payout may key off settlement actually received, never an assumption.</li>
|
||
<li><strong>Commission rate is per-contract and not public</strong> (anecdotal 7–15% for SnappPay; Torob Pay's published 6.6%) — always a config field read from the actual settlement, never hardcoded.</li>
|
||
<li>Onboarding requires جواز کسب <strong>and</strong> اینماد 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.</li>
|
||
</ul>
|
||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||
<ul>
|
||
<li><strong>MVP:</strong> full-upfront BNPL via one provider modeled as a single inbound settlement (<code>bnpl_transactions</code>); provider-mediated revert/cancel refunds; nurse payout decoupled from BNPL; commission + settlement timing as config.</li>
|
||
<li><strong>DEFERRED:</strong> customer installment tracking (<code>installment_entries</code> — <strong>cut</strong>, owned by the provider); tranched settlement (<code>bnpl_settlement_entries</code> modeled-only, added if a future provider tranches); multiple BNPL providers.</li>
|
||
</ul>
|
||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||
<p><strong><code>bnpl_transactions</code></strong> (replaces the old <code>installment_plans</code>; the old <code>installment_entries</code> is cut), <code>payment_transactions</code>, <code>payment_webhook_events</code>, <code>refunds</code> (<code>refund_channel = 'bnpl_revert'</code>, <code>external_revert_reference</code>, <code>expected_customer_refund_eta</code>), <code>ledger_entries</code>. See the <a href="../payments/bnpl-landscape.html">BNPL landscape</a> and <a href="../payments/cancellation-and-payout.html">cancellation & payout</a> payments docs.</p>
|
||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/08-bnpl.html">BNPL</a>.</p>
|
||
</blockquote>
|
||
<a class="back-to-top" href="#">↑ Back to top</a>
|
||
</div></main>
|
||
</div>
|
||
<script>
|
||
(function(){var k='balinyaar-docs-theme';var s=localStorage.getItem(k);
|
||
if(s)document.documentElement.setAttribute('data-theme',s);
|
||
else if(matchMedia('(prefers-color-scheme: dark)').matches)document.documentElement.setAttribute('data-theme','dark');})();
|
||
function __t(){var d=document.documentElement;var n=d.getAttribute('data-theme')==='dark'?'light':'dark';
|
||
d.setAttribute('data-theme',n);localStorage.setItem('balinyaar-docs-theme',n);}
|
||
</script>
|
||
|
||
</body>
|
||
</html>
|