hamid
72 lines
13 KiB
HTML
72 lines
13 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>BNPL Cancellation, Refund & Nurse Payout (Q1 & Q2) — 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="../business/index.html">Overview & MVP scope</a></li><li><a href="../business/01-actors-and-onboarding.html">1. Actors & onboarding</a></li><li><a href="../business/02-nurse-verification.html">2. Nurse verification</a></li><li><a href="../business/03-service-catalog-and-pricing.html">3. Service catalog & pricing</a></li><li><a href="../business/04-search-and-matching.html">4. Search & matching</a></li><li><a href="../business/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../business/06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a href="../business/07-cancellation-and-refunds.html">7. Cancellation & refunds</a></li><li><a href="../business/08-payments-and-escrow.html">8. Payments & escrow</a></li><li><a href="../business/09-installments-bnpl.html">9. Installments / BNPL</a></li><li><a href="../business/10-payouts.html">10. Payouts to nurses</a></li><li><a href="../business/11-reviews-trust-and-safety.html">11. Reviews, trust & safety</a></li><li><a href="../business/12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="../business/13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="../business/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="index.html">Overview & exec summary</a></li><li><a href="iranian-payment-reality.html">Iranian payment reality</a></li><li><a href="escrow-ledger.html">Escrow as a ledger</a></li><li><a href="bnpl-landscape.html">BNPL landscape & finding</a></li><li><a class="active" href="cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="integration-notes.html">Integration & schema touchpoints</a></li><li><a href="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>
|
||
<p><a href="index.html">← Payments overview</a></p>
|
||
<h1 id="bnpl-cancellation-refund-nurse-payout-q1-q2">BNPL Cancellation, Refund & Nurse Payout (Q1 & Q2)</h1>
|
||
<p>See also the BNPL data model (<a href="../data-model/08-bnpl.html">../data-model/08-bnpl.md</a>) and the business view (<a href="../business/09-installments-bnpl.html">../business/09-installments-bnpl.md</a>).</p>
|
||
<h2 id="6-q1-cancellation-refund-of-a-bnpl-booking-mid-plan">6. Q1 — Cancellation / refund of a BNPL booking mid-plan <a class="anchor" href="#6-q1-cancellation-refund-of-a-bnpl-booking-mid-plan" aria-hidden="true">#</a></h2>
|
||
<p><strong>Decisive rule: money ALWAYS flows <code>customer ↔ SnappPay ↔ Balinyaar</code>. Never refund the customer directly, and never route a nurse→customer refund.</strong> Balinyaar initiates the reversal through SnappPay's API using the stored payment token/transaction id:</p>
|
||
<ul>
|
||
<li><strong>Full cancel/refund → <code>revert</code></strong> (full amount).</li>
|
||
<li><strong>Partial / shortened-visit → <code>update</code></strong> (new amount must be strictly lower than the original settled amount) — or <code>cancel</code> per the provider's partial semantics.</li>
|
||
</ul>
|
||
<p>SnappPay then, on its own ledger and asynchronously:</p>
|
||
<ol>
|
||
<li><strong>cancels the customer's remaining UNPAID installments</strong> and credits their equivalent back to the customer's <strong>credit wallet</strong> (reusable BNPL credit — not merely "wiped"),</li>
|
||
<li><strong>refunds any already-PAID installment</strong> to the customer's <strong>bank account in ~7–10 business days.</strong></li>
|
||
</ol>
|
||
<p>The merchant's only role is to authorize/cancel; <strong>SnappPay owns the unwind.</strong> <em>(VERIFIED verbatim: "اقساط پرداختنشده لغو و معادل آن به موجودی حساب اعتباری شما برگشت داده میشود"; "مبلغ قسط پرداختشده به حساب بانکی شما برگشت داده خواهد شد (۷ تا ۱۰ روز کاری)".)</em></p>
|
||
<h3 id="balinyaars-internal-bookkeeping">Balinyaar's internal bookkeeping <a class="anchor" href="#balinyaars-internal-bookkeeping" aria-hidden="true">#</a></h3>
|
||
<ol>
|
||
<li>Record a <strong><code>refund</code> row</strong> with <code>refund_channel = 'bnpl_revert'</code>, <code>external_revert_reference</code>, <code>expected_customer_refund_eta</code>, and a <code>refund_status</code> that stays <code>processing</code> until SnappPay confirms (a reconciliation job clears it). <strong>Surface the asynchronous 7–10-day window in the UI and reconciliation</strong> — never assume instant.</li>
|
||
<li><strong>Decompose the refund</strong> across the two fee legs: <code>platform_fee_refunded_irr</code> and <code>nurse_payout_refunded_irr</code> (the booking gross = platform fee + nurse payout; the refund must say how much of each is reversed).</li>
|
||
<li><strong>Post balanced ledger entries</strong> (§3.2c/d): debit the decomposed <code>platform_revenue</code> / <code>nurse_payable</code>, credit <code>refund_payable</code>; record the revert reference on the <code>bnpl_transactions</code> row (<code>reverted_amount_irr</code>, <code>reverted_at</code>, <code>refund_channel</code>).</li>
|
||
<li><strong>If the nurse has NOT been paid</strong> (booking still inside the dispute window / not in a processed batch): reverse the <code>nurse_payable</code> accrual — clean, nothing leaves Balinyaar. <em>(This is the common case if you gate payout on the dispute window.)</em></li>
|
||
<li><strong>If the nurse HAS been paid</strong> (refund-after-payout): take the <strong>clawback</strong> path — a <code>nurse_clawbacks</code> row + a <code>nurse_clawback_receivable</code> ledger leg (§3.2d), recovered from the next payout batch or written off.</li>
|
||
</ol>
|
||
<p><strong>Partial / shortened-visit</strong> maps to the <code>update</code> endpoint with a reduced amount: record <code>refund_delta_irr</code>, reduce <code>settled_amount_irr</code> on the <code>bnpl_transactions</code> row, and apply the same fee-leg decomposition.</p>
|
||
<blockquote><p><strong>UNCERTAIN (confirm at contracting):</strong> whether the provider returns <em>its</em> merchant commission on a full vs partial refund (full / pro-rata / not at all) is <strong>undocumented</strong> and directly affects platform P&L on cancellations. Model <code>provider_commission_reversed_amount</code> as nullable and reconcile from the provider's refund response — do not hardcode. Digipay's exact mid-installment proration mechanics are likewise undocumented and contract-dependent.</p>
|
||
</blockquote>
|
||
<hr>
|
||
<h2 id="7-q2-under-bnpl-who-pays-the-nurse-and-when">7. Q2 — Under BNPL, who pays the nurse, and when? <a class="anchor" href="#7-q2-under-bnpl-who-pays-the-nurse-and-when" aria-hidden="true">#</a></h2>
|
||
<p><strong>Balinyaar pays the nurse, on Balinyaar's own normal weekly payout schedule, after EVV check-out and after the dispute window closes — exactly the same path as a card-funded booking.</strong> SnappPay <strong>never</strong> pays the nurse and is indifferent to Balinyaar's internal split. The customer's BNPL repayment timeline is completely decoupled from the nurse payout cycle.</p>
|
||
<h3 id="the-crucial-accounting-rule-the-three-amount-split">The crucial accounting rule — the three-amount split <a class="anchor" href="#the-crucial-accounting-rule-the-three-amount-split" aria-hidden="true">#</a></h3>
|
||
<p>The nurse's payout is computed from the booking's <strong>own price and Balinyaar's own commission</strong>, <strong>NOT</strong> from the BNPL-net amount. SnappPay's commission is a <strong>cost of accepting BNPL, borne by Balinyaar</strong>, and must <strong>never</strong> be passed through to the nurse. Store three separate amounts so the two fee deductions are never conflated:</p>
|
||
<div class="table-wrap"><table><thead><tr><th>Amount</th><th>Meaning</th><th>Drives</th></tr></thead><tbody>
|
||
<tr><td><code>gross_price_irr</code></td><td>What the customer is charged (booking price)</td><td>The invoice; the inbound <code>escrow_held</code> debit</td></tr>
|
||
<tr><td><code>balinyaar_commission_irr</code></td><td>Balinyaar's own cut (was <code>platform_fee_amount</code>)</td><td><code>platform_revenue</code>; <strong>the nurse payout</strong></td></tr>
|
||
<tr><td><code>bnpl_commission_irr</code></td><td>The BNPL provider's merchant discount</td><td><code>bnpl_fee_expense</code> (platform expense) — <strong>never the nurse</strong></td></tr>
|
||
</tbody></table></div>
|
||
<pre><code>nurse_payout_amount = gross_price_irr − balinyaar_commission_irr</code></pre>
|
||
<p><strong>The nurse receives the identical amount whether the family paid by card or by SnappPay, and on the identical weekly timing</strong> (batch, gated on <code>dispute_window_ends_at < now()</code>). The only difference a BNPL order makes to the books is the extra <code>bnpl_fee_expense</code> leg that reduces <em>Balinyaar's</em> margin — not the nurse's pay.</p>
|
||
<p><strong>Worked example</strong> (illustrative; rates are config): gross <code>5,000,000</code> IRR, Balinyaar commission 15% = <code>750,000</code>, nurse payout = <code>4,250,000</code>. If paid via SnappPay at a 10% merchant commission, <code>bnpl_commission_irr = 500,000</code> is a Balinyaar expense; SnappPay settles <code>4,500,000</code> net to Balinyaar; the <strong>nurse still receives <code>4,250,000</code></strong>, and Balinyaar's net margin is <code>750,000 − 500,000 = 250,000</code> (before PSP/VAT). The nurse payout is invariant to the payment method.</p>
|
||
<blockquote><p><strong>Timing guard (CONFIGURABLE):</strong> because BNPL settlement can lag, optionally key weekly-payout eligibility off <code>bnpl_transactions.settled_at</code> (settlement actually received) in addition to EVV + dispute window, so the platform never advances a nurse before it holds the cash.</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>
|