SRS: UC_7.2 — Compliance Check & Amount Determination

---

Document References

---

UC_7.2 — Compliance Check & Amount Determination

1. Overview

No wireframe — backend compliance/calculation step with no UI screen of its own in this version. A "Day 2 Payouts" dashboard screen that would surface a "Pending DOTS Review" flag has been raised by the client but is not yet confirmed as in scope (open item, tracked as A-74 — not part of this version).

---

2. Trigger

Event-driven — fires immediately after UC_7.1 (Anti-Fraud Reconciliation) completes, within the same Flow 5 execution, regardless of UC_7.1's outcome (within tolerance, beyond tolerance, or endpoint failure — none of those outcomes block this UC).

This UC — and Flow 5 as a whole — only ever fires once Flow 4 (Promotion) has fully completed, including its "Data Fee Refund Calculation" step, which locks the promotion's payout amount into the SQL payouts table (see BR_7.2.3). There is no intermediate state in which a trader has "hit" a Profit Target without Flow 4 having already finished and handed off payout data — see BR_7.2.5 for why this rules out a hard-breach race condition between target-hit and payout.

Reaching a Profit Target while in Defense mode (Flow 4B) does not constitute a genuine promotion for payout purposes and does not trigger Flow 4's payout-locking step — see BR_7.2.6.

---

3. Pre-conditions

---

4. Post-conditions

Payout_Status = 'Approved'

• The locked Payout_Amount from Flow 4 (plus any amount still accrued from earlier held promotions, bundled — see BR_7.2.2) proceeds immediately to UC_7.3 (Routing & Execution — SRS not yet written). No minimum-amount or rollover check is applied — not even when the locked amount is $0 — see BR_7.2.3.

Payout_Status is anything other than 'Approved'

• The amount is held in an accrued state, not cancelled. The promotion/level-up itself is unaffected — only the money transfer is paused. The middleware fires a webhook that opens a Freshdesk ticket for Ops. See BR_7.2.2.

---

5. Basic Flow

1. Flow 5 continues. Immediately after UC_7.1's reconciliation call, Flow 5 proceeds to its "Compliance Check" step for the same trader/promotion event.

2. Query Payout_Status. The middleware queries the trader's Payout_Status field from the internal PostgreSQL database — this value is not fetched live from Dots/Ripplings; it is maintained asynchronously by Dots/Ripplings webhooks and simply read here. See BR_7.2.1.

3. Evaluate Payout_Status:

   • 'Approved' → continue to step 4 (see §6 Alt-1).
   • Anything else → go to Exc-1; do not continue to step 4 for this promotion's amount yet. See BR_7.2.2.

4. Read the locked payout amount. The system does not recompute the bonus from Table A/B at this point. It reads the Total_Payout value that Flow 4 already calculated and wrote to the SQL payouts table record for this specific promotion, at the moment the trader was promoted — see BR_7.2.3 for how Flow 4 produced that value (Table A/B lookup by Current_Level, plus the Level 3 + Futures Market Data refund where applicable). This proceeds even if Total_Payout resolves to $0 — see BR_7.2.3.

5. Hand off to Routing & Execution. The determined Payout_Amount proceeds to UC_7.3 (Routing & Execution — SRS not yet written) for Dots/Rippling dispatch.

---

6. Alternative Flows

• Alt-1 — Payout_Status is already 'Approved' at promotion time (expected common case).

  • Context: the trader's compliance/KYC profile with Dots is already fully approved when this promotion event reaches the Compliance Check step.
  • The flow proceeds through steps 4–6 of §5 with no hold and no delay.

• Alt-2 — Level 3, Futures: the locked amount includes the Market Data fee refund.

  • Context: the trader is being promoted to Level 3 on a Futures account. At the Flow 4 stage that preceded this UC, the middleware called GET /financial/calculate-data-refund (input user_id) to total the "Base" Market Data fees paid during Level 1 and Level 2 (SELECT SUM(amount) FROM invoices WHERE user_id = [Input] AND fee_type = 'MARKET_DATA_BASE' AND status = 'paid'), explicitly excluding non-refundable "Add-On" (e.g., NYMEX/COMEX) and "Platform" fees, and added the result (refundable_amount) to Level_Performance_Bonus to form the locked Total_Payout. (Source: RFQ_ Stack Trading Prop Tech V7.pdf §Financial & Transaction Endpoints; Zapier Integration V7.pdf §Flow 4 "Data Fee Refund Calculation (Level 3 Bonus)")
  • This UC's own step 4 behaves identically to Alt-1 from this point on — it simply reads whatever Total_Payout was locked, whether or not it includes the refund component.

---

7. Exceptional Flows

• Exc-1 — Payout_Status is not 'Approved' (any other value, including values not yet enumerated).
  • The automated payout API trigger halts for this promotion's amount. The amount remains in an accrued holding state — it is not cancelled and the trader's level-up is not reversed. See BR_7.2.2.
  • The middleware separately fires a webhook that opens a Freshdesk ticket for Ops. The freshdesk ticket for Operations, the payload must include the user_id, the user's registered email, the new payout_status, and any specific error or reason code provided by the Dots webhook (If have).
  • If the trader is promoted again (reaches another level) while still held, that promotion's own locked amount accrues as well — when Payout_Status eventually returns to 'Approved', all accrued amounts across every held promotion are bundled into a single aggregated payout, executed instantly by resuming Flow 5 (UC_7.3 — Routing & Execution, SRS not yet written).

---

8. Business Rules

BR_7.2.1: Compliance Check — Payout_Status gate, checked at every promotion, sourced from internal PostgreSQL

The system checks the Payout_Status variable at every single level promotion, not just once. This check queries the internal PostgreSQL database — it is not a direct, live Dots/Ripplings API call. The value is maintained asynchronously by DotsRipplings webhooks, which write it into the database whenever Dots' own status changes.

---

BR_7.2.2: Non-'Approved' status holds and accrues the payout; it never cancels it, and held amounts bundle

If Payout_Status is anything other than 'Approved' at the Compliance Check — the client explicitly ruled out building custom routing for intermediate statuses such as pending, action_required, or rejected; any non-'Approved' value is treated identically — the automated payout halts and the funds enter an accrued holding state. This is a hold, not a cancellation: the trader's promotion/level-up already happened via Flow 4 and is not reversed.

If the trader advances through additional levels while still held, each subsequent promotion's locked amount (see BR_7.2.3) accrues on top of the earlier one. When Payout_Status is confirmed 'Approved' again, the system must bundle all earned bonuses into a single aggregated payout and execute it instantly.

---

BR_7.2.3: The payout amount is computed and locked by Flow 4 at promotion time — Flow 5 only disburses it

Flow 4 (Promotion), not Flow 5, is responsible for determining the dollar amount of a payout. During the promotion event, Flow 4 looks up Level_Performance_Bonus (= Bonus_Paid_To_Trader from Table A/B, keyed by the level just reached) and, for Level 3 + Futures only, adds the Market Data fee refund (refundable_amount, from GET /financial/calculate-data-refund — see §6 Alt-2) to form Total_Payout. Flow 4 then writes this Total_Payout into the SQL payouts table record for that specific promotion event, before triggering Flow 5.

When Flow 5 reaches this UC's Compliance Check / amount-determination step — whether immediately or after a compliance hold is later released (see BR_7.2.2) — it must use the exact amount already locked in the payouts table for each individual promotion, not re-derive it from a fresh Table A/B lookup at disbursement time. This is what allows a trader who is promoted multiple times while held under BR_7.2.2 to still receive the correct amount for each earlier level, even though their Current_Level has since moved on — a fresh lookup by Current_Level at payout time would silently return the wrong, more-recent level's bonus instead.

---

BR_7.2.4: Ops "Do Not Pay" list gate is out of scope for this phase

An Ops-maintained "Do Not Pay" list, checked as a separate gate before Compliance Check disburses funds, was proposed during analysis (with a corresponding Held_Ops hold state, distinct from the Held_Compliance state in BR_7.2.2). This gate is not part of the current phase's scope — the Compliance Check in this UC relies solely on Payout_Status (BR_7.2.1/BR_7.2.2). Do not build a payout_hold / "Do Not Pay" gate in this version.

(Source: QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-19 — BA Trang Nguyen, 2026-10-04, descoped to a later phase)

---

BR_7.2.5: No race window between a Profit Target hit and a hard breach before the payout is locked

Flow 5 — and therefore this UC — is never triggered by a Profit Target being hit in isolation. It is triggered only once Flow 4 has fully completed and handed off locked payout data (see BR_7.2.3). Consequently, there is no window in which a trader could hit a Profit Target, then suffer a hard breach, before this UC's Compliance Check / amount lookup runs: if Flow 4 has not yet finished, the payout simply has not been triggered yet either.

(Source: QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-77 — BA Trang Nguyen, 2026-10-04)

---

BR_7.2.6: Hitting Profit Target while in Defense mode does not trigger a payout

If a trader is in Defense mode (per Flow 4B) when they reach their Profit Target, this does not trigger a payout. The trader must instead return to standard trading and reach the Profit Target of the level prior to entering Defense in order to level up properly — only that produces a genuine promotion, and therefore a payout via Flow 4 → Flow 5.

This reverses an earlier BA assumption that Defense status would have no bearing on payout eligibility.

(Source: QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-78 — BA Trang Nguyen, 2026-10-04, reversing the original BA-proposed assumption)

---

9. Update History

---