SRS: Stage 3 KYC & Live Onboarding — UC_5.3: Flow 3B.2 Ironbeam Institution Verification

⛔ DEPRECATED — 2026-08-12 (STAGE3-037 [CHR-46] / STAGE3-039 [CHR-46])

Flow 3B.2 and UC_5.3 are deleted from the active architecture.

Reason: Ironbeam confirmed that because traders are independent contractors trading corporate capital, their full manual KYC applications are waived. All traders (Futures and Forex) now use Veriff for identity verification via Flow 3B (UC_5.2). Because traders are assigned Ironbeam sub-accounts instantly from a pre-provisioned bulk pool, and institution verification is now instantaneous on Veriff pass, there will be no inbound JSON approval files sent to FCM_approvals@stacktrading.com for Zapier to parse.

What replaced this UC:

• Veriff flow (UC_5.2 / Flow 3B) now covers all traders.
• Ironbeam receives an outbound compliance package from the backend (Veriff payload + PII documents + assigned sub-account number). Delivery method (SFTP / Secure Shared Drive) pending Ironbeam confirmation.

This file is retained for audit history only. Do not implement.

---

---

UC Index

---

Changelog

---

Glossary

For all shared project terminology, refer to the single source of truth: Project Glossary.

---

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

UC_5.3 — Flow 3B.2: Ironbeam Institution Verification

1. Overview

Scope note: This UC covers Futures traders only. Forex traders do not go through Ironbeam — their institution approval (institution_approval_status = 'Approved') is set automatically inside Flow 3B (Veriff) on a successful APPROVED outcome. (Source: Zapier Integration V7.pdf line 1096 — IF Asset_Class == 'Forex', Set institution_approval_status = 'Approved'.)

---

2. Trigger

Flow 3B.2 is triggered when Zapier Email Parser receives an inbound email at FCM_approvals@stacktrading.com containing a JSON attachment sent by Ironbeam following a trader's KYC review decision.

This email is sent by Ironbeam asynchronously — after the Futures trader completes the Ironbeam White Label KYC portal flow (initiated via the kyc_link set in UC_5.1 Flow 3A). There is no fixed SLA; the trigger fires whenever Ironbeam sends the result.

---

3. Pre-conditions

• The trader's Asset_Class = 'Futures' in the Users table.
• Flow 3A (UC_5.1) has already executed: identity_status = 'Pending', institution_approval_status = 'Pending', payout_status = 'Pending' are set; the Ironbeam White Label Portal URL was delivered to the trader via email.
• The trader has submitted their KYC application through the Ironbeam White Label Portal.
• Ironbeam has completed its internal review and issued a result (Approved or Denied).
• An email with a valid JSON attachment has arrived at FCM_approvals@stacktrading.com.

---

4. Post-conditions

On Approved path:

• Users table updated: identity_status = 'Approved', institution_approval_status = 'Approved', rithmic_subaccount_id = parsed_subaccount_id.
• Aggregation gate evaluated — if all three statuses are 'Approved', Flow 3D is triggered via internal webhook to proceed to contract execution.
• If any status is still pending, Zap terminates and waits.

On Denied path:

• Users table is NOT updated (no status change on denial).
• A Slack alert is sent to the Head of Operations containing the parsed_reason_for_denial.
• The Zap terminates. No automated retry or re-invitation is sent to the trader by this flow.

---

5. Basic Flow

1. Ironbeam sends the KYC review result as an email with a JSON attachment to FCM_approvals@stacktrading.com.
2. Zapier Email Parser receives the email and parses the attached JSON file.
3. Zapier evaluates: IF JSON status == 'Approved'.
4. Zapier executes a PostgreSQL UPDATE on the Users table WHERE user_id = parsed_user_id:
   • Set identity_status = 'Approved'
   • Set institution_approval_status = 'Approved'
   • Set rithmic_subaccount_id = parsed_subaccount_id
5. Aggregation gate check: Zapier queries the Users table for user_id and evaluates:
   • IF identity_status == 'Approved' AND institution_approval_status == 'Approved' AND payout_status == 'Approved' → fire internal webhook to trigger Flow 3D (UC_5.5).
   • ELSE → Zap terminates; system waits for missing approvals (e.g., payout_status still Pending from Dots/Flow 3C).

---

6. Alternative Flow

• [If payout_status is not yet Approved when Ironbeam approves]
  • The aggregation gate condition is not fully met after step 5.
  • Zap terminates after updating identity/institution fields. No Flow 3D is triggered yet.
  • When Flow 3C (UC_5.4 — Dots Payout Verification) later sets payout_status = 'Approved' and re-evaluates the gate, Flow 3D will be triggered at that point.

---

7. Exceptional Flow

• [If JSON status == 'Denied']

  • Zapier detects JSON status == 'Denied'.
  • Zapier fires a Slack alert to the Head of Operations containing parsed_reason_for_denial.
  • No database update is performed. The trader's identity_status and institution_approval_status remain 'Pending'.
  • Zap terminates. No automated re-invitation or retry email is sent to the trader by this flow.
  • Further remediation (e.g., manual re-submission, contacting Ironbeam) is handled by the Operations team out-of-band.

• [If JSON parsing fails or the attachment is malformed]

  • [MISSING] — no failure path for malformed JSON is documented in the source. The system behavior (silent failure, Slack alert, retry) is unspecified. Raise with client: "If Zapier Email Parser fails to parse the JSON attachment (malformed file, unexpected schema), what should happen? Should Ops be alerted? Should the email be quarantined for manual review?"

• [If parsed_user_id does not match any record in the Users table]

  • [MISSING] — no handling documented. Raise with client: "If the user_id in the Ironbeam JSON does not match any record in the database, what should happen? Should Ops be alerted?"

• [Spoofed or unauthenticated email received at FCM_approvals@stacktrading.com]

  • ⚠️ Confirmed security gap (QnA STAGE3-015, 2026-08-10): No authentication or verification mechanism is defined in source for inbound emails at this mailbox. Any email with a valid JSON payload can trigger identity_status = 'Approved', institution_approval_status = 'Approved', and rithmic_subaccount_id write for an arbitrary user_id. A spoofed Ironbeam email could fraudulently provision a live Rithmic sub-account.
  • Current state: Zapier Email Parser ingests all email arriving at the inbox — no sender domain filter, no DKIM/SPF enforcement, no JSON signature, no shared secret.
  • Remediation required before implementation. See BR_5.3.7 for options. Client must select and confirm a security control before this flow goes to dev.

---

8. Business Rules

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

BR_5.3.1: Futures-Only Scope

This flow applies exclusively to traders with Asset_Class = 'Futures'. Forex traders' institution approval is handled within Flow 3B (Veriff) — see UC_5.2. No Ironbeam institution verification step exists for Forex.

(Source: Zapier Integration V7.pdf line 1096) <a id="BR_5.3.2"></a>

BR_5.3.2: Intake Email Address

Ironbeam sends all KYC result emails to the dedicated operational inbox: FCM_approvals@stacktrading.com. Zapier Email Parser is configured to monitor this address. Any routing change to this inbox address must be coordinated with Ironbeam and the Zapier configuration simultaneously.

(Source: Zapier Integration V7.pdf line 1134–1135) <a id="BR_5.3.3"></a>

BR_5.3.3: Dual-Field Approval Write

On an Approved result, both identity_status and institution_approval_status are set to 'Approved' in the same database write. This is intentional — for Futures traders, a successful Ironbeam KYC approval satisfies both the identity verification requirement (replacing Veriff) and the institutional onboarding requirement simultaneously.

(Source: Zapier Integration V7.pdf lines 1143–1144) <a id="BR_5.3.4"></a>

BR_5.3.4: rithmic_subaccount_id Persistence

The rithmic_subaccount_id returned in the Ironbeam approval JSON (parsed_subaccount_id) is written to the Users table at this step. This ID is required later in Flow 3H (UC_5.8) to provision the live sub-account on Rithmic. The format and naming convention of this ID is defined by Ironbeam and is not validated by the system before write — see open question in [Stage 3 QnA backlog, Q-8].

(Source: Zapier Integration V7.pdf line 1145) <a id="BR_5.3.5"></a>

BR_5.3.5: Three-Way Aggregation Gate

Flow 3D (contracts and live onboarding pipeline) can only be triggered when ALL three of the following conditions are simultaneously 'Approved' for the same user_id:

If any one of the three is still 'Pending', Zap terminates without triggering Flow 3D. The gate is re-evaluated each time one of the three flows writes its approval.

(Source: Zapier Integration V7.pdf lines 1147–1153) <a id="BR_5.3.6"></a>

BR_5.3.6: Denial Alert — Ops Slack, No Trader Notification

On a Denied outcome, a Slack alert is sent to the Head of Operations containing the parsed_reason_for_denial. No automated email notification is sent to the trader by this flow. The trader is not informed of the denial automatically — Operations must handle communication manually.

(Source: Zapier Integration V7.pdf lines 1155–1156)

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

BR_5.3.7: Email Intake Authentication — Confirmed Security Gap

⚠️ No authentication or verification mechanism is defined in source for the FCM_approvals@stacktrading.com intake mailbox.

The current spec processes any email arriving at this address that contains a valid JSON attachment. There is no:

• Sender domain whitelist (e.g., Zapier Email Parser FROM filter restricting to @ironbeam.com)
• DKIM/SPF enforcement at the mailbox or Zapier level
• JSON payload signature or cryptographic hash verification
• Shared secret or API key within the JSON body

Risk: A spoofed email from any sender can trigger DB-mutating compliance writes (identity_status = 'Approved', institution_approval_status = 'Approved', rithmic_subaccount_id mapped to an arbitrary user_id), and consequently trigger the aggregation gate that initiates live Rithmic sub-account provisioning.

Status: Confirmed security gap — not a design decision. Remediation must be designed and added to source spec before implementation. Options for client consideration:

Client must select and confirm a security control. No implementation should begin on Flow 3B.2 until this is resolved.

(Source: QnA STAGE3-015 confirmed 2026-08-10 — no authentication defined in source)

---

9. Wireframe / UI

No screen is required for this UC. Flow 3B.2 is a fully automated backend/Zapier flow with no trader-facing UI interaction. The trader interacts with Ironbeam's own White Label Portal directly (external, not built by Stack Trading).

---

10. Screen Description and Business Rules

N/A — this use case contains no Stack Trading-owned UI screens. All processing is automated via Zapier Email Parser and direct PostgreSQL writes.

---

END OF UC_5.3