Payment Architecture — Stripe Connect, Razorpay, 15% Fee, and Why Two Providers

[LarytheLord]

Related Issue

This discussion provides context for issue #106 (Stripe Connect). It also explains decisions that affect all payment-related work.

---

The Payment Stack

The platform uses two providers simultaneously:

lib/payment-provider.ts  →  routes based on currency
  ├── lib/stripe.ts       →  international (USD, EUR, etc.)
  └── lib/razorpay.ts     →  India (INR)

Both singletons already exist. Both webhook handlers already exist (app/api/payments/webhooks/stripe and app/api/payments/webhooks/razorpay). Issue #106 connects Stripe to a real onboarding flow — it is not starting from zero.

---

Why Two Providers

Razorpay is the dominant payment provider in India. Indian bank accounts, UPI, and INR transactions work natively. Stripe's India support has historically been unreliable for domestic payouts. Since Open Paws India Pvt Ltd is based in Bangalore and many interns and clients will be Indian, Razorpay is the practical choice for INR.

Stripe Connect handles everything else. It is the global standard for marketplace payouts. When international clients pay, or when adventurers have international bank accounts, Stripe routes the money.

The routing logic in lib/payment-provider.ts:

const provider = currency === 'INR' ? 'razorpay' : 'stripe';

---

The 15% Platform Fee

Every paid quest has a 15% commission taken by the platform.

Client pays ₹10,000 for a quest
Platform fee: ₹1,500  (15%)
Adventurer receives: ₹8,500  (85%)

This is calculated at payment time in payment-provider.ts. The fee is stored on the Transaction model as platformFee and platformFeeRate.

Why 15%? The org plan projects ₹1–2 lakh revenue in months 1–3, ₹5–10 lakh by month 6. At 15%, that requires ₹7–13 lakh in GMV in months 1–3. That is achievable with 20 interns completing 1–2 quests each at an average reward of ₹15–20K per quest.

---

Stripe Connect Express

Adventurers receive payouts via Stripe Connect Express. This is the right product because:

• Express is designed for marketplaces (like ours)
• Stripe handles KYC and compliance — we don't
• Adventurers get their own Stripe dashboard
• We transfer funds from our platform account to their Express account on approval

The flow:

1. Adventurer clicks "Set up payouts" in dashboard settings
2. Platform creates a Stripe Express account on their behalf
3. Adventurer completes Stripe's onboarding (identity, bank account)
4. stripeOnboardingDone = true saved to their AdventurerProfile
5. On quest approval: platform initiates a transfer to their Express account

---

Payment Timeline in the Quest Lifecycle

Company accepts quest → PaymentIntent created (client authorises payment)
  → Quest in progress
  → Submission → pending_admin_review → review
  → Client approves → payout triggered
  → Adventurer receives 85%, platform keeps 15%

The PaymentIntent is created at quest acceptance (not at submission). This creates an escrow-like behaviour — the money is reserved but not transferred until approval.

---

What Phase 2 Builds vs What Already Exists

Already exists (before issue #106):

• lib/stripe.ts — Stripe singleton with lazy init
• lib/razorpay.ts — Razorpay singleton
• lib/payment-provider.ts — unified routing
• POST /api/payments/webhooks/stripe — handles payment_intent events
• POST /api/payments/webhooks/razorpay — handles payment.captured events
• POST /api/payments — records transactions (simulated, txn_${Date.now()})

What issue #106 adds:

• stripeAccountId + stripeOnboardingDone on AdventurerProfile
• stripeCustomerId on CompanyProfile
• stripePaymentIntentId + platformFee + platformFeeRate on Transaction
• POST /api/payments/stripe/connect — create Express account + return onboarding URL
• GET /api/payments/stripe/connect/callback — handle Stripe return, mark onboarding done
• POST /api/payments/stripe/intent — create PaymentIntent for quest reward
• Dashboard settings page — payout setup status + button

Not in Phase 2:

• Razorpay Connect onboarding (the Razorpay equivalent — Phase 3)
• Automatic payout on approval (Phase 3 — Phase 2 creates the intent, actual transfer is manual)
• Subscription billing (Phase 3)

---

Simulated Payments Must Still Work

The existing POST /api/payments endpoint uses simulated transactions (txn_${Date.now()}). This must continue to work when Stripe is not configured (i.e., in local development without Stripe env vars).

When implementing #106, do not break the fallback path. If STRIPE_SECRET_KEY is not set, the system should gracefully fall back to the simulated payment model.

---

BOOTCAMP Track Gets No Payment

This is a deliberate architectural decision (Decision #13 in docs/ARCHITECTURE_DECISIONS.md).

Bootcamp students earn XP and portfolio work in Phase 2. No payment. When building #106, gate the Stripe integration:

if (quest.track === 'BOOTCAMP') {
  // skip payment — XP only
  return;
}

Do not trigger PaymentIntents or transfers for BOOTCAMP track quest approvals.

---

Env Vars Required for Payment Work

# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

# Razorpay
RAZORPAY_KEY_ID="rzp_test_..."
RAZORPAY_KEY_SECRET="..."

Get Stripe test keys from dashboard.stripe.com. Never commit real keys.