SRS: UC_5.1 — Flow 3A: Live Onboarding Initiation

<a id="UC_5.1"></a>

UC_5.1 — Flow 3A: Live Onboarding Initiation

1. Overview

Wireframe: Figma — Stack Trading Designs Shared File 2, node-id 1-25967 Open in Figma

Screenshot provided by BA (2026-08-09): Dashboard in "Pending_Compliance" failed visual state — dark overlay, desaturated background, frosted glass effect visible. Modal not captured in this screenshot (modal appears on top of this background state). See §10 for full component inventory.

2. Trigger

Flow 3A fires when Flow 2.2 (Challenge Monitor — Pass Check) emits a PROFIT_TARGET_HIT state-change webhook to Zapier, indicating the trader's SIM equity has met or exceeded Profit_Target.

Architecture note (STAGE2-006 confirmed 2026-07-20): Flow 2 does NOT trigger on Trade_Closed. Node.js middleware monitors SIM account balances server-side in real time. Zapier is only invoked when middleware emits binary state-change webhooks: PROFIT_TARGET_HIT (→ Flow 3A) or CHALLENGE_FAILED (→ Flow 7B).

Profit_Target formula:

Profit_Target_PnL    = Starting_Capital × SIM_target_percent
Target_Equity_Trigger = Starting_Capital + Profit_Target_PnL

Example — $25,000 package (at current Table C value of 14%):

Profit_Target_PnL     = $25,000 × SIM_target_percent (14%) = $3,500
Target_Equity_Trigger = $25,000 + $3,500 = $28,500

Pass recorded when Net_Equity >= $28,500.

Pass condition check (Flow 2.2 — middleware):

IF Net_Equity >= Target_Equity_Trigger:
  Action 1: Disable SIM account (POST /disable-sim-account — Lock Profit)
  Action 2: UPDATE Users SET account_status = 'Passed_Challenge'
  Action 3: Trigger Flow 3A (emit PROFIT_TARGET_HIT webhook to Zapier)
  Action 4: POST /community/trigger-review-invite (delay_hours=0) — Trustpilot, concurrent

POST /community/trigger-review-invite — Middleware logic:

When called with delay_hours=0, Middleware executes the following steps sequentially:

1. Delay scheduling: Schedules an internal task at call_time + delay_hours. With delay_hours=0, the task executes immediately.
2. Suppression check: At task execution time, query the Users table. HALT if either condition is true:
   • trustpilot_reviewed_at < 15 days ago (trader reviewed within the last 15 days), OR
   • trustpilot_invited_at < 30 days ago (trader received an invite within the last 30 days).
3. API dispatch: If suppression check passes, call Trustpilot Invitation API with user_id as referenceId. Trustpilot maps referenceId to the trader's registered email and delivers the invitation directly.
4. State update: UPDATE Users SET trustpilot_invited_at = NOW().
5. Audit log: Write execution record to BPS_Audit_Log.

Payload received by Flow 3A:

(Source: Zapier Integration V7.pdf §Flow 2: Challenge Monitor, §Flow 3A; STAGE2-006 confirmed 2026-07-20; MKT-26 confirmed 2026-07-24)

3. Pre-conditions

4. Post-conditions

Branch A — New Trader:

• identity_status = 'Pending'
• institution_approval_status = 'Pending'
• payout_status = 'Pending'
• "Action Required: Complete Live Onboarding" email dispatched (SES template: Live_Onboarding_Compliance_Initiation)
• Dashboard displays Phase 1 "Pending Compliance" hard-lockout overlay (computed state — not a DB write)

Branch B — Returnee Trader:

• payout_status = 'Approved' — set directly by Middleware (no Veriff / Dots / Rippling re-processing — STAGE3-055/H-07)
• setup_status = 'Pending' — reset to force market data repurchase at Flow 3F
• identity_status, institution_approval_status, contract_status remain 'Approved' / 'Signed' — NOT reset
• No Veriff session created; no KYC email dispatched
• Dashboard enters Phase 2 (Market Data Setup) forced screen — trader must re-select and re-pay for market data

Note: account_status is NOT updated at Flow 3A. It is only updated at Flow 3H to 'Active_L[N]_DMA' after full provisioning. 'Pending_Compliance' is a frontend computed state, not a DB column value. (Source: STAGE3-010 — confirmed 2026-08-09)

Futures path additionally:

• kyc_link = Ironbeam White Label Portal URL REMOVED (STAGE3-037 [CHR-46]) — Futures traders now use Veriff same as Forex. kyc_link = Veriff verification_url for all traders.
• After Veriff APPROVED: backend bundles Veriff payload + PII documents + assigned Ironbeam sub-account number and transmits outbound to Ironbeam compliance team. Delivery method: SFTP or Secure Shared Drive, end-of-day batch (confirmed M-02 2026-08-15).

Forex path additionally:

• kyc_link = Veriff verification_url (from POST /v1/sessions)

(Source: Zapier Integration V7.pdf §Flow 3A State Management; RFQ_ Website and Dashboard Implementation V7.pdf §Passing Associate Track modal)

5. Basic Flow

1. Receive trigger payload. Zapier receives the internal webhook from Flow 2 with user_id, Asset_Class, Billing_Country.

Step 0 — Returnee branch gate (runs before any compliance writes).

• Query Users table:

  SELECT dots_payee_id, identity_status, contract_status
  FROM Users WHERE user_id = payload.user_id

• IF identity_status = 'Approved' AND dots_payee_id IS NOT NULL AND contract_status = 'Signed': → Branch B (Returnee Trader). Skip Steps 2–5. Proceed to Step 0B.
• ELSE (any condition not met): → Branch A (New Trader). Continue from Step 2.

Step 0B — Returnee path: auto-approve payout, reset market data, route to Flow 3F. (Branch B only)

UPDATE Users
SET payout_status  = 'Approved',
    setup_status   = 'Pending'
WHERE user_id = payload.user_id

• Middleware fires internal webhook to trigger Flow 3F (Market Data Selection).
• Dashboard enters Phase 2 forced Market Data Setup screen (trader must re-select and pay for market data — same forced-navigation as post-Flow 3E).
• Flow 3H: After trader completes Market Data selection (Flow 3F/3G), Flow 3H provisions a new Live account (MT5/Rithmic) from the Ironbeam/Forex pre-provisioned pool at the level of the SIM just passed, and sets account_status = 'Active_L[N]_DMA'.
• HALT — Steps 2–5 do NOT execute. (Source: STAGE3-055/H-07 second-cycle Dots bypass — extended to full Flow 3A branch gate; setup_status reset confirmed 2026-08-18)

2. Update compliance status fields — Pending_Compliance overlay trigger. (Branch A only)

   UPDATE Users
   SET identity_status             = 'Pending',
       institution_approval_status = 'Pending',
       payout_status               = 'Pending'
   WHERE user_id = payload.user_id

   account_status is NOT changed here. 'Pending_Compliance' is a frontend computed state: Dashboard renders the Pending Compliance overlay when identity_status = 'Pending' OR institution_approval_status = 'Pending' OR payout_status = 'Pending'. It is not stored in the account_status column. (Source: STAGE3-010 — confirmed 2026-08-09)

🔄 CR — STAGE3-037 [CHR-46]: Universal Veriff replaces Ironbeam WLP branch. Ironbeam Compliance Handoff (outbound bundle) added.

3. Generate KYC link (Universal Veriff — all traders).

   • All traders (Futures and Forex): Call Veriff API POST /v1/sessions → receive verification_url. Set kyc_link = verification_url.
   • IF Asset_Class == 'Futures': Set kyc_link = Ironbeam White Label Portal URL DELETED (STAGE3-037 [CHR-46] 2026-08-12) — Ironbeam waived manual KYC applications for all traders. Universal Veriff flow replaces the Ironbeam WLP branch. Flow 3B.2 (UC_5.3) is also deleted (see STAGE3-039 [CHR-46]).
   • Ironbeam Compliance Handoff (NEW — Futures only, post-Veriff): After Veriff APPROVED webhook (handled in Flow 3B/UC_5.2), backend must bundle the approved Veriff JSON payload, all supporting PII documents, the trader's legal_name and address, and the newly assigned Ironbeam sub-account number from the predefined bulk pool. Backend transmits this package directly to Ironbeam's compliance team via SFTP or Secure Shared Drive, end-of-day batch (confirmed M-02 2026-08-15). (Source: STAGE3-037 confirmed 2026-08-12)

4. Send "Action Required: Complete Live Onboarding" email (SES template: Live_Onboarding_Compliance_Initiation).

   • Recipient: trader's registered email address.
   • Email contains: kyc_link (Veriff hosted verification page URL) only.
   • Payout setup link: NOT included in this email. The personalized Dots payout setup flow link (flow_link) is generated in Flow 3B (Process Veriff Handoff, UC_5.2) after Veriff APPROVED, and dispatched in a second email.
   • Note: Template key renamed from Live_Onboarding_Level_1 to Live_Onboarding_Compliance_Initiation to avoid collision with Live_Onboarding_Credentials email at Flow 3H (STAGE3-060 confirmed 2026-08-15). (Source: Zapier Integration V7.pdf §Flow 3A Compliance Initiation; STAGE3-050 / STAGE3-060; confirmed 2026-08-15)

5. Write compliance state to Users table.

   UPDATE Users
   SET identity_status               = 'Pending',
       institution_approval_status   = 'Pending',
       payout_status                 = 'Pending'
   WHERE user_id = payload.user_id

   (Source: Zapier Integration V7.pdf §Flow 3A State Management; STAGE3-010 confirmed 2026-08-09)

6. Dashboard renders "Live Onboarding In Progress" hard lockout overlay. (STAGE3-048 2026-08-12)

   • Trigger (computed state): Frontend evaluates identity_status = 'Pending' OR institution_approval_status = 'Pending' OR payout_status = 'Pending'. This is NOT driven by account_status DB column — 'Pending_Compliance' is a frontend computed state only.
   • Overlay copy (confirmed from screenshot 2026-08-13):
     • Headline: Live Onboarding In Progress
     • Subtitle: Congratulations on passing the Associate Track. To provision your live account, you must complete Identity Verification, Payout Setup, and sign your Trader Agreement.
     • Info box: Please check your email. We have sent you secure links to complete these required steps. This dashboard will unlock once your live account is fully provisioned.
   • Progress steps (dynamic — reflect DB state in real time):
     • ○ Identity Verification → identity_status
     • ○ Payout Setup → payout_status
     • ○ Trader Agreement → contract_status
     • Each circle transitions from empty (Pending) to filled/checked when its field reaches 'Approved' / 'Signed'.
     • institution_approval_status is NOT shown as a separate circle — set simultaneously with identity_status per STAGE3-037 [CHR-46].
   • "Back to Website" button: Only interactive exit. Routes to www.stacktrading.com.
   • No close button. Overlay is a hard lockout — cannot be dismissed. Sidebar and Settings disabled. See BR_5.1.8.
   • Hide condition: Overlay dismissed when account_status = 'Active_L[N]_DMA' (Flow 3H write-back). (Source: STAGE3-048 confirmed 2026-08-12; screenshot confirmed 2026-08-13)

7. Terminate Zap. Flow 3A ends. Downstream flows (3B, 3B.2 (deprecated — STAGE3-039 [CHR-46]), 3C, 3D–3H) are triggered independently by their own events.

6. Alternative Flows

Alt-1 — Trader closes the modal and navigates the dashboard.

• Updated (STAGE3-048 2026-08-12): Trader cannot freely navigate. As long as identity_status, payout_status, and institution_approval_status are all 'Pending' (Flows 3A–3E not yet complete), the trader is hard-locked to the "Live Onboarding In Progress" screen. Sidebar navigation and the standard Settings menu remain DISABLED.
• The "Back to Website" button routes the trader OUT of the application to the public marketing site (www.stacktrading.com).
• The trader can re-read the email and act on the KYC link at any time, but cannot access other dashboard screens until onboarding is complete.
• Flow 3F transition: Once Flow 3E completes (contract signed — contract_status = 'Signed'), the next login recognizes the DB state change and forces the trader to the native Market Data selection screen (Flow 3F). See UC_5.5. (Source: STAGE3-048 confirmed 2026-08-12)

Alt-2 — Trader loses or doesn't receive the KYC/Onboarding email.

• Trader contacts Operations.
• Step 1 — Check AWS SES: Dev checks SES console for Bounce, Spam/Complaint, or Suppression List entry for the trader's email address.
• Step 2 — BPS Manual Veriff Reset (Flow 3.1): BPS admin calls POST /api/bps/kyc/reset (or equivalent admin UI).
  • Middleware clears veriff_failed_flag and resets veriff_attempts = 0 in PostgreSQL RDS.
  • Middleware fires VERIFF_MANUAL_RESET webhook to Zapier Flow 3.1.
  • Zapier Flow 3.1 calls Veriff API to generate a new verification session link.
  • AWS SES sends a new email: "Action Required: Your ID Verification has been reset..." containing the new KYC link.
  • Slack alert pushed to Ops channel: "⚠️ Veriff session manually reset for Trader [ID]".
• Step 3 — Freshdesk escalation (via Flow 38): If Trader complained via Discord (#the-pit / #verify), Discord Bot (Flow 38) auto-detects, removes public message, and creates a High Priority Freshdesk ticket under the trader's email. If L1 support cannot resolve → POST /user_id/ticket_id (Escalate to L2) auto-tags L2_Escalation and Compliance_Review.

  (Source: CR-20260720-004 — Freshdesk replaces Zendesk across all ticketing including Flow 38)

• Step 4 — Break-Glass (Veriff system outage): If Veriff API is unavailable system-wide, Ops activates "Manual KYC Exception Handling" from Ops Console. Admin bypasses KYC status via internal Middleware endpoints with mandatory Reason Code + evidence attachment. All overrides are permanently logged to the audit table for NFA/CFTC inspection.

Note: POST /resend-welcome (Flow 41) is NOT used here. Flow 41 is for Stage 1 Welcome/Sim email resend only (re-sends Welcome_Sim_Challenge with a new credentials_claimed_at-gated token). Using Flow 41 for a Stage 3 KYC email is incorrect.

(Source: QnA STAGE3-001, STAGE3-006 — confirmed 2026-07-20; Ops runbook clarification 2026-08-09)

Alt-3 — Returnee Trader (Branch B): passes SIM after Hard Breach with prior KYC/Dots/ICA complete.

• Flow 2 emits PROFIT_TARGET_HIT a second (or later) time for the same user_id.
• Step 0 gate detects: identity_status = 'Approved' AND dots_payee_id IS NOT NULL AND contract_status = 'Signed'.
• Branch B executes:
  • payout_status set to 'Approved' directly — no Dots API call.
  • setup_status reset to 'Pending' — trader must re-purchase market data.
  • Flows 3B (Veriff), 3C (Dots webhook), 3D (ICA routing) are NOT triggered — entirely skipped.
  • Flow 3E (ICA webhook) is NOT triggered — contract_status already 'Signed'.
  • Internal webhook fires → Flow 3F (Market Data Selection) triggered directly.
  • Dashboard enters Phase 2 forced Market Data Setup screen.
• Flow 3H: provisions new Live account from pre-provisioned Ironbeam/Forex pool at the level of the SIM just passed (Level N = Current_Level at time of Passed_Challenge).
• Flow 3A terminates. No KYC email sent.

7. Exceptional Flows

Exc-1 — Veriff API non-200 (Forex path, Step 3).

• Veriff POST /v1/sessions returns a non-200 or times out.
• Retry: 3 attempts over 15 minutes via Redis BullMQ queue on Core Compute (30s → 5min → 15min).
• Rollback: Do NOT write identity_status = 'Pending'. Trader state remains Passed_Challenge in DB. Cancel SES email dispatch.
• Alerting: Log to bps_audit_logs. Fire Severity-2 Slack alert to #ops-compliance. After 3 failed retries: auto-create Freshdesk ticket (tags: Compliance_Hold, Technical_Fault). (Source: STAGE3-012 — confirmed 2026-08-09; CR-20260720-004 — Freshdesk replaces Zendesk)

Exc-2 — Email dispatch failure (Step 4).

• AWS SES fails to send the "Action Required: Complete Live Onboarding" email.
• Retry: 5 automatic retries per AWS SES retry policy (or Middleware queue).
• Rollback: Do NOT rollback identity_status or payout_status — the KYC link was already generated successfully and is saved in DB. Rollback would break the onboarding cycle.
• Alerting: Log SES failure to CloudWatch. Alert #ops-support via Slack. Ops can use BPS Reset/Resend API (POST /api/bps/kyc/reset) to resend the existing KYC link without regenerating a new Veriff session. (Source: STAGE3-012 — confirmed 2026-08-09)

Exc-3 — Users table write failure (Step 5).

• UPDATE Users SET identity_status / institution_approval_status / payout_status fails (DB connection error).
• Retry: 3 immediate retries at connection pool level. If connection failure persists, task is frozen in memory queue.
• Rollback: Abort entire transaction — do NOT call Veriff API, do NOT dispatch SES email. Return HTTP 500 to client.
• Alerting: Severity-1 Slack alert to #dev-alerts. Trigger AWS CloudWatch Alarm (DB CPU/connection timeout) → SMS/PagerDuty to DevOps team. (Source: STAGE3-012 — confirmed 2026-08-09)

Exc-4 — Double-trigger (Flow 3A fires twice for same user_id).

• Cause: Flow 2 webhook fires twice due to a race condition (e.g., two Trade_Closed events near the profit target), or network retries replaying the same event.
• Retry: 0 — rejected immediately at the webhook entry point.
• Idempotency Guard (3 layers):
  1. Middleware queries provider_event_id before any processing. If already exists → HALT, return HTTP 200 No-Op.
  2. State Machine Guard: if any of {identity_status, payout_status, institution_approval_status} is already 'Pending' or 'Approved' → Block; no Veriff call; no email re-send.
  3. DB Constraint: UNIQUE INDEX on provider_event_id in Users table — rejects concurrent second write and auto-Rollback.
• Alerting: Log Warning (Severity-3) to bps_audit_logs to monitor webhook replay frequency. (Source: STAGE3-012 — confirmed 2026-08-09)

Exc-5 — Invalid or NULL Asset_Class (confirmed — QnA STAGE3-022, 2026-08-10):

• Cause: Trigger payload carries Asset_Class value outside {'Futures', 'Forex'} (e.g., 'Crypto', empty string, NULL) — possibly a legacy record or upstream data error.
• Behavior: Flow 3A MUST HALT immediately. No KYC API call (no Veriff). No DB writes. No email dispatched.
• Logging: Error logged to system log with user_id and the invalid Asset_Class value received.
• Rationale: System is designed exclusively for Futures and Forex. Flow 3A's KYC routing branch (Route KYC Flow) cannot execute without a valid Asset_Class. Global safety directive: "All Funding Zaps must filter by Asset_Class." (Source: QnA STAGE3-022; Zapier Integration V7.pdf — "All Funding Zaps must filter by Asset_Class")

8. Business Rules

🔄 CR — STAGE3-037 [CHR-46]: KYC routing changed. All traders now use Veriff. Ironbeam WLP branch deleted.

<a id="BR_5.1.1"></a>

BR_5.1.1: KYC routing by Asset_Class — UPDATED (STAGE3-037 [CHR-46] 2026-08-12)

Flow 3A routes the KYC link generation based on Asset_Class: - 'Forex' → Veriff hosted verification page (dynamic URL per session via POST /v1/sessions) - 'Futures' → Ironbeam White Label Portal URL (static, pre-configured)

All traders — both Futures and Forex — now use Veriff for identity verification. Ironbeam confirmed that because traders are independent contractors trading corporate capital, their full manual KYC applications are waived. Flow 3A calls POST /v1/sessions for all traders regardless of Asset_Class. The Asset_Class field still determines downstream behavior (Rithmic vs MT5/TE provisioning at Flow 3H) but no longer determines the KYC link type.

(Source: STAGE3-037 [CHR-46] confirmed 2026-08-12; Zapier Integration V7.pdf §Flow 3A — superseded for Futures path)

🔄 CR — STAGE3-037 [CHR-46]: Universal Veriff for all traders. Ironbeam WLP branch removed.

<a id="BR_5.1.2"></a>

BR_5.1.2: Dots payout setup — triggered in Flow 3B after Veriff APPROVED, NOT at Flow 3A

Flow 3A does NOT call the Dots API. Flow 3A's email (SES template Live_Onboarding_Compliance_Initiation) contains the kyc_link only.

The full 3-step Dots payee creation process occurs inside Flow 3B (Process Veriff Handoff, UC_5.2) after Veriff returns APPROVED:

1. POST /v2/users — creates the Dots user with SIM registration data (first_name, last_name, email, country_code, phone_number, metadata.internal_id).
2. Submit Compliance Information — patches Veriff-extracted legal_name + address to pre-fill the W-9 (US) or W-8BEN (International) tax form.
3. POST /v2/flows (manage-payouts step) → returns flow_link (personalized, session-scoped).

The flow_link from step 3 is dispatched in a second email ("Payout Profile Setup") at Flow 3B. Tax form routing (W-9 vs W-8BEN) is determined by Billing_Country at step 2.

Separation of concerns:

• Dots payee creation uses SIM registration data (first_name/last_name/email etc. from Stage 1/2 registration) for the user identity record.
• Dots compliance submission uses Veriff-extracted data (legal_name, address) to pre-fill the authoritative tax form.
• Ironbeam compliance handoff (Flow 3H) uses Veriff-extracted data separately — SFTP/Secure Shared Drive, end-of-day batch (confirmed M-02 2026-08-15).

(Source: Zapier Integration V7.pdf §Flow 3A, §Flow 3B; STAGE3-050 confirmed 2026-08-15; M-02 confirmed 2026-08-15)

<a id="BR_5.1.3"></a>

BR_5.1.3: Dashboard lockout state machine — three phases (STAGE3-048 2026-08-12)

The dashboard lockout progresses through three phases, each driven by backend DB state:

Forex traders skip Phase 2: setup_status = 'N/A' is set by Flow 3D. Forex goes directly Phase 1 → Phase 3.

Pending_Compliance is a frontend computed state — it is NOT stored as an account_status value in the DB at Flow 3A. Dashboard evaluates identity_status = 'Pending' OR institution_approval_status = 'Pending' OR payout_status = 'Pending' on every load.

⚠️ Note: The original RFQ_ Website and Dashboard Implementation V7.pdf §Passing Associate Track (lines 866–879) described a closable modal with a "Continue to Dashboard" CTA. This spec has been superseded by STAGE3-048 which mandates a hard lockout with no close button. The closable modal spec must NOT be implemented.

(Source: STAGE3-048 confirmed 2026-08-12; RFQ_ Website and Dashboard Implementation V7.pdf §Passing Associate Track — superseded)

BR_5.1.3a: Progress circles — dynamic DB state reflection

Each circle in the Phase 1 overlay reflects the real-time DB value of its corresponding field:

institution_approval_status is not shown as a separate circle — it is set simultaneously with identity_status at Veriff APPROVED (STAGE3-037).

Frontend must update circles on WebSocket push or page refresh. DB is authoritative.

(Source: STAGE3-048 confirmed 2026-08-12)

<a id="BR_5.1.4"></a>

BR_5.1.4: SIM account lock precedes Flow 3A

Flow 3A must only fire after Flow 2 has already locked and flattened the SIM account (execution disabled, positions closed). Flow 3A does not itself call the Lock & Liquidate endpoint — that is Flow 2's responsibility.

(Source: Zapier Integration V7.pdf §Flow 2 — Action 1: Disable Sim Account; Action 2: Update SQL Database Status = 'Passed_Challenge'; Action 3: Trigger Flow 3)

<a id="BR_5.1.5"></a>

BR_5.1.5: Status fields written only after links are generated

The state management write (identity_status, institution_approval_status, payout_status all set to 'Pending') occurs in Step 6, after KYC link and Dots onboarding link are successfully generated (Steps 3–4) and the email is dispatched (Step 5). If any earlier step fails, the status fields MUST NOT be written. ⚠️ [ASSUMPTION — BA to confirm exact atomicity scope]

<a id="BR_5.1.6"></a>

BR_5.1.6: Downstream flow independence — UPDATED (STAGE3-037/039 2026-08-12)

Flow 3A does not trigger Flows 3B or 3C directly. Each downstream flow has its own independent trigger:

• Flow 3B: triggered by Veriff webhook (ALL traders — Futures and Forex; confirmed STAGE3-037)
• Flow 3B.2: triggered by Zapier Email Parser (Futures traders, FCM_approvals@stacktrading.com) DELETED — UC_5.3 / Flow 3B.2 deprecated. Ironbeam inbound email parser removed from scope. (STAGE3-039 [CHR-46])
• Flow 3C: triggered by Dots Active/Payable webhook (all traders)

(Source: Zapier Integration V7.pdf §Flow 3B; STAGE3-037/039 confirmed 2026-08-12)

<a id="BR_5.1.7"></a>

BR_5.1.7: MT5 profit-lock mechanism (Forex platform note)

For Forex traders on MT5, the SIM account profit-lock (Profit Target trigger, position flatten) is handled by the YourBourse Contest Stop Out server-side plugin on the MT5 White Label server — not by Middleware directly. When the plugin fires, Middleware detects the state change and fires the webhook to initiate Level-Up / Flow 3A activities.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §2.2 MT5 Infrastructure)

BR_5.1.8: Dashboard hard lockout during Flows 3A–3E (STAGE3-048 2026-08-12)

While any of identity_status, payout_status, or institution_approval_status is 'Pending' (i.e., Flows 3A–3E are not fully complete), the trader dashboard MUST enforce a hard lockout:

• Sidebar navigation: DISABLED
• Standard Settings menu: DISABLED
• Trader is locked to the "Live Onboarding In Progress" screen only
• "Back to Website" button is the only exit — routes to www.stacktrading.com (public marketing site)

This lockout prevents any possibility of a trader bypassing onboarding flows or accessing execution modules before compliance is complete.

(Source: STAGE3-048 confirmed 2026-08-12 — "the intent is that the user can't access the standard Settings menu during this phase")

BR_5.1.9: "Back to Website" button routing (STAGE3-048 2026-08-12)

The "Back to Website" button present on the "Live Onboarding In Progress" lockout screen routes the user out of the application to the public Stack Trading marketing site: www.stacktrading.com. It does NOT navigate to another dashboard screen.

(Source: STAGE3-048 confirmed 2026-08-12)

<a id="BR_5.1.10"></a>

BR_5.1.10: POST /provision-in-house-trader — BPS admin in-house provisioning bypass (STAGE3-044)

POST /provision-in-house-trader is a BPS admin-only endpoint that provisions a trader directly into the live onboarding phase (Flow 3) without requiring the standard Associate Track checkout flow. Used for traders hired directly as in-house staff.

Input parameters:

Desk fee logic (sourced from Table J):

After payment of the upfront 2× desk fee, the trader is pushed into Flow 3A. All subsequent flows (3B–3H) execute identically to a standard checkout trader.

Authorization: BPS admin RBAC only. Audit log required (Admin ID, Action, Timestamp, user_id, target_level, desk fee charged).

⚠️ PENDING CONFIRMATION (STAGE3-044):

1. target_level — restricted to Level 1 only, or can admin provision at Level 2/5?
2. Payment method for upfront desk fee — NMI Customer Vault or manual invoice?
3. Month 3 recurring — same payment gateway as standard or separate billing?
4. Does provisioned trader go through full KYC/Veriff/Dots/Rippling (Flows 3A–3G), or does admin attest compliance directly?

(Source: STAGE3-044 pending confirmation; Zapier Integration V7.pdf Table J desk fee)

<a id="BR_5.1.11"></a>

BR_5.1.11: Returnee Trader bypass — Branch B (STAGE3-055/H-07 extended, 2026-08-18)

When Flow 3A fires and the trader satisfies all three conditions simultaneously:

• identity_status = 'Approved'
• dots_payee_id IS NOT NULL
• contract_status = 'Signed'

…the system MUST execute Branch B and MUST NOT execute Branch A. Specifically:

1. DO NOT create a new Veriff session (POST /v1/sessions must NOT be called).
2. DO NOT reset identity_status, institution_approval_status, or contract_status to 'Pending'.
3. DO NOT dispatch the Live_Onboarding_Compliance_Initiation KYC email.
4. DO NOT trigger Flows 3B, 3C, or 3D.
5. DO set payout_status = 'Approved' directly in Users table (atomic write with Step 6 below).
6. DO reset setup_status = 'Pending' in the same atomic write — trader must repurchase market data.
7. DO fire internal webhook to trigger Flow 3F (Market Data Selection) immediately.
8. Flow 3H provisions a new Live account from the Ironbeam/Forex pre-provisioned pool at Current_Level (level of SIM just passed).

Rationale: Trader has already completed KYC, Dots tax form, and ICA in a prior cycle. Re-running compliance flows is unnecessary, creates compliance data duplication, and degrades UX. Market data must be repurchased because the prior subscription is terminated by Flow 7.

(Source: STAGE3-055/H-07 second-cycle Dots bypass — extended to full Flow 3A branch gate; setup_status reset confirmed 2026-08-18)

9. NFRs

10. Screen / UI References

Figma — Live Onboarding overlay (Shared File 2): Stack Trading Designs — Shared File 2, node-id 1-25967

Figma — Dashboard background (Finalized Asset Designs): Stack Trading Finalized Asset Designs, node-id 1767-361033 — Dashboard state sau khi trader bắt đầu Stage 3 (desaturated/dark overlay background visible behind Live Onboarding In Progress modal)

Full-flow wireframe:

• Phase 1 (all pending): References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3A: Dashboard.png
• Phase 1A (KYC Approved): References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3B: Dashboard.png
• Phase 1B (Contract Expired): References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3E: Contract's link expired.png

Phase 1 — "Live Onboarding In Progress" hard lockout overlay (confirmed from screenshot 2026-08-13; screenshot confirmed 2026-08-17):

Screenshot: References/Wireframe/Stage 3/UC_5.1_Live_Onboarding_Initiation/Phase_1_Live_Onboarding_In_Progress.png Full-flow ref: References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3A: Dashboard.png

The original Dashboard V7 spec (§Passing Associate Track lines 866–879) described a closable modal with "Continue to Dashboard" CTA. Superseded by STAGE3-048. Do not implement the closable modal.

Phase 1A — "Live Onboarding In Progress" — KYC Approved sub-state (confirmed from screenshot 2026-08-17):

Triggered when identity_status = 'Approved' AND payout_status still 'Pending' AND contract_status still 'Pending'. Same hard lockout overlay as Phase 1, with Identity Verification step checked.

Screenshot: References/Wireframe/Stage 3/UC_5.1_Live_Onboarding_Initiation/Phase_1A_KYC_Approved.png Full-flow ref: References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3B: Dashboard.png

Phase 1B — "Live Onboarding In Progress" — Contract Expired sub-state (confirmed from screenshot 2026-08-14):

Triggered when identity_status = 'Approved' AND payout_status = 'Approved' AND contract_status = 'Expired' (signing link TTL of 7 days elapsed — per BR_5.5.10). Same hard lockout overlay as Phase 1, with the following differences:

Full-flow ref: References/Wireframe/Stage 3/Stage 3: Total wireframe/Flow 3E: Contract's link expired.png

"Request New Contract Link" interaction:

• Trader clicks the inline link next to the Trader Agreement step.
• Frontend calls the backend endpoint to generate a new Rippling ICA signature request.
• contract_status transitions back from 'Expired' → 'Pending'.
• Trader Agreement circle reverts from hourglass icon → empty circle (pending state).
• Subtitle reverts to standard Phase 1 subtitle.
• New signing link email dispatched to trader.

(Source: screenshot confirmed 2026-08-14; BR_5.5.10 — QnA STAGE3-034 confirmed 2026-08-12)

Phase 2 — Market Data Setup forced screen (Futures only):

Native Stack Trading dashboard screen. Activated when contract_status = 'Signed' AND setup_status = 'Pending'. Dashboard forces navigation to this screen — trader cannot navigate away. Option A (Standard, firm-paid) / Option B (Premium, trader-paid with native checkout). Confirmed platform: Stack Trading frontend (STAGE3-042). Full spec in UC_5.5 §9 Wireframe.

Phase 3 — Unlocked dashboard:

Standard Bento Grid layout. Career map, trading data, all navigation accessible. Connections & Credentials tab in Settings shows live platform login credentials. Activated when account_status = 'Active_L[N]_DMA' (Flow 3H).

11. Acceptance Criteria

12. Update History