Payout automation & creator KYC (RazorpayX)

Why / Context

MVP payouts are manual (admin closes a period, marks Payout PAID after a bank/UPI transfer). At creator scale that breaks — PRD §9.2 makes "Payments, Payouts & Revenue-Share Ledger" a core module. This issue automates payout execution via RazorpayX (payout rails) with proper creator KYC collection, keeping our ledger as the source of truth (build-the-ledger/buy-the-rails split per PRD §4).

Schema already in place — NO migration required

• Payout (status machine incl. PENDING_APPROVAL/PROCESSING/FAILED, method: RAZORPAYX, providerRef, period bounds, statementAssetId)
• LedgerAccount/LedgerEntry (PAYOUT + PAYOUT_REVERSAL entry types)
• Tenant.payoutDetails Json (bank/UPI/PAN) and MentorProfile ledger accounts
• WebhookEvent(provider: RAZORPAY) handles RazorpayX payout webhooks too

Implementation plan

1. KYC collection in studio/mentor settings: structured payoutDetails (account holder, IFSC/UPI, PAN, GSTIN optional) with validation; admin verification queue (mark verified, request re-submission).
2. RazorpayX integration (src/lib/payments/razorpayx.ts): create Contact + Fund Account per verified payee; store refs in payoutDetails.providerRefs.
3. Payout run job (scheduled, monthly + on-demand): close period → compute eligible balance per account (ledger sum minus holds: pending refund windows, disputed amounts) → create Payout(DRAFT) batch with statement line items.
4. Approval flow: admin reviews batch → PENDING_APPROVAL → approve triggers RazorpayX payout API (idempotency key = payout id) → PROCESSING.
5. Webhooks: payout.processed → PAID + LedgerEntry(PAYOUT); payout.failed/reversed → FAILED + PAYOUT_REVERSAL, alert + retry console.
6. Statements: per-payout PDF (earnings breakdown by order item / project fee, commission, refund clawbacks, TDS field placeholder) → statementAssetId; email via facade.
7. Hold policy: configurable payout hold (e.g., earnings payable 14+ days post-sale to clear the refund window) in PlatformConfig.
8. Threshold + self-serve: minimum payout amount; payee can request early payout (fee optional).
9. Reconciliation view: RazorpayX balance vs ledger PAYOUT sums; alerts on drift.

Acceptance criteria

• Verified creator receives an automated monthly payout with a correct statement PDF
• Refund-window holds excluded from payable balance
• Failed payout reverses cleanly in the ledger and is retryable
• Unverified payees are skipped with a clear studio prompt
• Ledger↔RazorpayX reconciliation report shows zero drift on the happy path

Dependencies / sequencing

• MVP M7/M12 (ledger + manual payouts) required; RazorpayX account activation is an ops prerequisite
• TDS/GST treatment details coordinate with issue #24 (compliance pack)

Start with the existing schema for Payout, LedgerEntry, Tenant.payoutDetails, and WebhookEvent, then inspect src/lib/payments/razorpayx.ts and the studio/mentor settings entry point. Review the ledger and manual payout flow before mapping the scheduled job, approval flow, and webhook handling. Done means the listed acceptance criteria pass, including statements, holds, retries, and zero-drift reconciliation.