stripe-integration

Stripe Integration

Full Stripe integration: Android SDK → Firebase Functions → Stripe API → Firestore sync. Secret keys never touch the Android client. All payment operations are server-side.

Pre-Processing (Auto-Context)

Before starting, gather project context silently:

• Read PORTFOLIO.md if it exists in the project root or parent directories for product/team context
• Run: cat package.json 2>/dev/null || cat build.gradle.kts 2>/dev/null || cat Podfile 2>/dev/null to detect stack
• Run: git log --oneline -5 2>/dev/null for recent changes
• Run: ls src/ app/ lib/ functions/ 2>/dev/null to understand project structure
• Use this context to tailor all output to the actual project

Integration Architecture

Android App
  └── StripeDataSource (Android SDK + PaymentSheet)
        ↓ Firebase Callable Function
  Cloud Functions
    ├── createPaymentIntent / createSubscription
    ├── createSetupIntent (save card)
    ├── stripeWebhook (HTTP — Stripe → Firebase)
    └── createPortalSession (manage subscription)
          ↓ Stripe API (secret key, server-side only)
  Stripe
    └── Events → stripeWebhook → Firestore sync

Step 1: Classify the Integration Type

Need	Primary Function
Subscriptions (recurring)	createSubscription
One-time payment	createPaymentIntent
Save payment method	createSetupIntent
Manage subscription	createPortalSession
Webhook handling	stripeWebhook
Android UI (PaymentSheet)	PaymentSheet SDK
Full paywall screen	All of above

Step 2: Gather Context

1. Payment type — subscription / one-time / both?
2. Plan tiers — names, prices, billing intervals
3. Trial period — yes/no, how many days?
4. Free tier — yes/no?
5. Payment UI — use Stripe PaymentSheet (recommended) or custom UI?
6. Existing Stripe account — test mode / live mode setup?

Step 3: Security Rules (Always Apply)

Client (Android) can:

• Call Firebase Callable Functions (authenticated)
• Use Stripe Android SDK for UI (PaymentSheet, CardElement)
• Read own subscription status from Firestore

Client CANNOT:

• Hold or use Stripe secret key
• Create/modify subscriptions directly via Stripe API
• Write to subscription documents in Firestore (Cloud Functions only)
• Access other users' payment data

Stripe Config & Keys

Publishable Key → Android app (safe to expose)
Secret Key      → Firebase Secret Manager only (never in client)
Webhook Secret  → Firebase Secret Manager only
Price IDs       → Firebase Remote Config (safe to expose)

Price ID Management

Store price IDs in Firebase Remote Config so they can be updated without app release:

// Android — fetch from Remote Config
val priceIds = mapOf(
    "starter_monthly" to remoteConfig.getString("stripe_price_starter_monthly"),
    "pro_monthly" to remoteConfig.getString("stripe_price_pro_monthly"),
    "pro_annual" to remoteConfig.getString("stripe_price_pro_annual")
)

Webhook Events to Handle

Always implement idempotent handlers for:

// Critical — must handle
'checkout.session.completed'        // Initial subscription
'customer.subscription.updated'     // Plan changes, renewals
'customer.subscription.deleted'     // Cancellation
'invoice.payment_succeeded'         // Successful payment
'invoice.payment_failed'            // Failed payment

// Recommended
'customer.subscription.trial_will_end'  // 3 days before trial ends
'payment_method.attached'               // New payment method saved

Firestore Subscription Document Shape

interface UserSubscription {
  stripeCustomerId: string;
  subscriptionId: string;
  status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid';
  planId: string;
  priceId: string;
  currentPeriodStart: Timestamp;
  currentPeriodEnd: Timestamp;
  cancelAtPeriodEnd: boolean;
  trialEnd: Timestamp | null;
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

Test Cards

Success:          4242 4242 4242 4242
Decline:          4000 0000 0000 0002
Requires auth:    4000 0025 0000 3155
Insufficient:     4000 0000 0000 9995

Code Generation (Required)

You MUST generate actual Stripe integration code using Write:

1. Webhook handler: functions/src/stripe/webhook.ts — handles all critical Stripe events:
   • checkout.session.completed → provision access
   • invoice.paid → extend subscription
   • invoice.payment_failed → notify user, grace period
   • customer.subscription.deleted → revoke access
   • charge.refunded → handle refund logic
2. Checkout session creator: functions/src/stripe/create-checkout.ts — creates Stripe Checkout sessions
3. Customer portal: functions/src/stripe/customer-portal.ts — creates billing portal sessions
4. Subscription types: src/types/subscription.ts — TypeScript types for plans, subscription states
5. Firestore schema: functions/src/stripe/sync-to-firestore.ts — syncs Stripe data to Firestore
6. Security rules: Append subscription-aware rules to firestore.rules
7. Android client: data/repository/SubscriptionRepository.kt — checks subscription status
8. iOS client: Data/Repositories/SubscriptionRepository.swift — checks subscription status

Before generating, Grep for existing Stripe references (stripe|Stripe|subscription|checkout) to understand current integration state.

Tech Stack

android: Stripe Android SDK (PaymentSheet)
backend: Firebase Cloud Functions v2 (TypeScript)
stripe_sdk: stripe@14.x (Node.js)
firestore: subscription status sync
remote_config: price IDs
secret_manager: Stripe secret key + webhook secret