hamid/baya-monorepo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ui phase 13

Browse Source
This commit is contained in:
hamid
2026-07-20 01:35:15 +03:30
parent d33568bf31
commit 12ce7fa7de
21 changed files with 868 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
product/business/10-payouts.html
+22
View File
@@ -38,6 +38,28 @@
<li><strong>MVP:</strong> weekly batches; EVV + dispute-window gating; per-session accrual for engagements; <code>nurse_clawbacks</code> with next-batch netting and write-off; unique booking↔payout link; <code>iranian_holidays</code>-aware scheduling; verified-IBAN payouts with reconciliation references.</li>
<li><strong>DEFERRED:</strong> on-demand / instant nurse withdrawal; per-nurse configurable payout frequency; automated clawback recovery beyond netting.</li>
</ul>
<h2 id="d1-rules-confirmed-in-build-backend-b13">(d1) Rules confirmed in build (backend b13) <a class="anchor" href="#d1-rules-confirmed-in-build-backend-b13" aria-hidden="true">#</a></h2>
<p>These fill gaps the requirements left open; the payout engine was built to them:</p>
<ul>
<li>**Clawback netting recovers <em>whole</em> clawbacks up to a batch's earnings.** A <code>nurse_clawbacks</code> row is atomic —</li>
</ul>
<p> it is recovered in full or not at all — so a batch nets the largest set of whole pending clawbacks (oldest first) that fits within the nurse's earnings that week; <code>net_amount = gross_earnings − clawback_applied ≥ 0</code> (never negative). A single clawback <strong>larger than a batch's earnings</strong> stays fully <code>pending</code> and recovers from a later, larger batch (it is not partially recovered). The recovery is a real ledger movement (<code>DEBIT nurse_payable / CREDIT nurse_clawback_receivable</code>), not just a status flag, so the derived balances reconcile.</p>
<ul>
<li><strong>A booking with an active (non-failed/-rejected) refund is held out of payout batches</strong> — its money was (partly)</li>
</ul>
<p> reversed, so paying its frozen <code>nurse_payout_amount</code> would overpay. It is excluded until resolved (this is the operational reading of "no open dispute", since there is no separate dispute table yet).</p>
<ul>
<li><strong>PAYA vs SATNA</strong> is chosen per payout by the <code>payout_satna_threshold_irr</code> config (SATNA for net amounts at/above</li>
</ul>
<p> the threshold, else PAYA).</p>
<ul>
<li><strong>Optional BNPL settlement gate:</strong> <code>require_bnpl_settlement_for_payout</code> (config, <strong>default off</strong>) — when on, a</li>
</ul>
<p> BNPL-paid booking is payout-eligible only once its provider settlement (<code>settled_at</code>) is received.</p>
<ul>
<li>The weekly <strong>cron trigger is DEFERRED</strong> — batches are admin-triggered; the cadence lives in</li>
</ul>
<p> <code>nurse_payout_interval_days</code> (default 7) for the future scheduler.</p>
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
<p><code>nurse_payout_batches</code>, <code>nurse_payouts</code> (with <code>gross_earnings_irr</code>, <code>clawback_applied_irr</code>, <code>net_amount_irr</code>, <code>iban_snapshot</code>), <code>nurse_payout_booking_links</code> (unique per booking), <strong><code>nurse_clawbacks</code></strong>, <code>ledger_entries</code>, <strong><code>iranian_holidays</code></strong>, <code>bookings.dispute_window_ends_at</code>, <code>nurse_bank_accounts</code>.</p>
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/07-payouts.html">Payouts</a>.</p>