SRS: UC_9.12 — Flow 35: Rippling PTO Ledger Sync

1. UC Index

UC_9.12 — Flow 35: Rippling PTO Ledger Sync

2. Trigger

Event: Rippling Time Off Request Approved webhook → Zapier Flow 35 catch hook.

Upstream: the W-2 trader requests time off inside Rippling and Rippling approves it (CR-20261027-001). The same webhook fans out to two independent Zaps: Flow 35 (this UC — ledger) and Flow 13 Path A (UC_9.2 — extend stagnation_deadline, lock account, notify). Stack Trading does not create time-off records in Rippling.

(Source: Zapier Integration V7.pdf §Flow 35 · CR-20261027-001 · UC_9.2 §2.1)

3. Pre-conditions

4. Post-conditions

5. Basic Flow

Step 1 — Receive webhook (Zapier).

Step 2 — Filter: active W-2 trader. Continue only if payload corresponds to an active Stack Trading W-2 trader; otherwise stop (Alt-2).

(Source: Zapier Integration V7.pdf §Flow 35)

Step 3 — Dedup check on Rippling Request ID. If processed → Alt-1.

Step 4 — Call POST /api/ledger/record

(Source: Zapier Integration V7.pdf §Flow 35)

Step 5 — Middleware mints on Polygon — identical to UC_9.11 Step 5 (JWT validation → Ethers.js wallet → recordMetric() via Alchemy → await confirmation → store tx_hash → HTTP 200).

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Record Immutable Ledger)

Step 6 — Terminate Zap.

6. Alternative Flows

Alt-1 — Duplicate delivery: return HTTP 200 with stored tx_hash; no second mint.

Alt-2 — Not an active W-2 trader: Zap stops at filter; no ledger call.

7. Exceptional Flows

Exc-1 (invalid JWT → HTTP 401) and Exc-2 (Polygon RPC failure → non-2xx, not marked processed, Zapier retry) — same as UC_9.11 §7.

Exc-3 — Time-off later cancelled in Rippling

• The on-chain event is immutable and cannot be reversed. No corrective ledger entry is written.
• Re-enabling the trading account and adjusting stagnation_deadline are handled manually by Ops — see UC_9.2 Alt-5.

(Source: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-017], [BG-002] — client sheet 2026-11-04)

8. Business Rules

BR_9.12.1: Ledger Logging Only

Flow 35 only writes the PTO event to the Immutable Ledger. stagnation_deadline extension, TRIM_TO_COMPLIANCE, and execution lock (Rithmic / MT5 / TraderEvolution) are owned by Flow 13 (UC_9.2 Steps A-3+) and must not be re-executed here.

(Source: Zapier Integration V7.pdf §Flow 35 — only action is POST /api/ledger/record then "Terminate Zap"; §Flow 13)

BR_9.12.2: Fixed Ledger Mapping

metric_category = "Corporate Benefits"; metric_value = "[Days_Approved] Days PTO Approved (Paid Time Off)", with Days_Approved as a whole integer — PTO is measured in full days only (no half days); receipt_hash = Rippling Request ID.

(Source: Zapier Integration V7.pdf §Flow 35; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-018] — client sheet 2026-11-04)

BR_9.12.3: Scope — Active W-2 Only

International contractor hiatus is unpaid and is not logged by Flow 35.

(Source: Zapier Integration V7.pdf §Flow 35; §Flow 13 Path B)

BR_9.12.4: One Approval = One Ledger Event

Rippling Request ID is the idempotency key. Same as BR_9.11.3.

BR_9.12.5: Audit Retention

Same as BR_9.11.7 (5 years + 1 month; > 25 months → cold storage).

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Audit Requirements)

9. Acceptance Criteria

10. API Reference

POST /api/ledger/record — schema as UC_9.11 §10.

{
  "trader_id": "94a2b1c8-3f4e-4b21-a123-890abcdef123",
  "metric_category": "Corporate Benefits",
  "metric_value": "3 Days PTO Approved (Paid Time Off)",
  "date": "2026-03-15T18:00:00Z",
  "receipt_hash": "rip_pto_99120482"
}

11. Open Questions

12. Changelog