Kingdom ID App — Stripe Payment Overhaul + Full Access Flow Audit

Kingdom ID (kingdomid.app) is a faith-based identity transformation PWA built on React, TypeScript, Vite, Firebase (Auth, Firestore, Hosting, Cloud Functions v2), and Stripe. We need an experienced full-stack developer to diagnose and permanently fix our Stripe payment flows, then audit every user access path in the app to ensure nothing is broken. This is NOT a simple bug fix. This is a full payment and access flow overhaul with thorough testing across every user type. --- TECH STACK - React, TypeScript, Vite (PWA) - Firebase: Auth, Firestore, Cloud Functions v2 (Node 20), Hosting - Stripe live account, API version 2026-02-25.clover - Stripe Connect for referral commissions - GitHub repo access provided --- PROBLEM 1 — SINGLES $7 TRIAL PAYMENT (CRITICAL, BROKEN NOW) What should happen: 1. User fills in name, email, password on the singles marketing page — Step 1 2. User enters card details — Step 2 3. Stripe creates a payment method on the platform account 4. A Cloud Function called createBasicMembershipSubscription is called: - Creates Stripe customer - Attaches payment method to customer - Charges $7 upfront via PaymentIntent - Creates 7-day free trial subscription - Writes membership fields to Firestore user doc 5. Frontend confirms the SetupIntent 6. User is routed to onboarding What is actually happening: - Cloud Function returns a 500 error - Firebase account gets created then immediately rolled back and deleted - User lands on the login page with an invalid-credential error - Stripe shows the customer was created at $0.00 but no payment was processed - No transaction appears in Stripe Known issues to investigate and fix: - The off_session parameter on the PaymentIntent create call is set to false — it should be true since the card is being confirmed server-side after the user entered it in the browser - The paymentMethods.attach error handling does not gracefully catch 404 errors from Stripe - A previous bug where confirmCardSetup was re-passing the payment method ID has been fixed on the frontend — verify this is correct and not causing cross-account issues - Check Cloud Function logs to find the exact line causing the 500 crash --- PROBLEM 2 — COUPLES $7 TRIAL PAYMENT (NEEDS VERIFICATION) Same general flow as singles but uses a separate Cloud Function called createCouplesSubscription and a separate couples marketing page. The same off_session bug likely exists here. Fix and test end to end: - Primary spouse signs up via the couples marketing page using createCouplesSubscription - Primary gets tagged as membershipType couples and spouseRole primary in Firestore - Primary generates a spouse invite code from Covenant Home - Linked spouse signs up via /spouse-signup with the invite code - Linked spouse uses createLinkedSpouseSubscription — no trial, half the monthly price - A Cloud Function called linkSpouse couples both accounts together - Both route to covenant onboarding then Covenant Home - Confetti experience fires for both spouses when they are linked --- PROBLEM 3 — FULL ACCESS FLOW AUDIT After fixing payments, audit every user access path to make sure routing is correct. The app has these user types — all must work: Singles paid via Stripe: - Signs up via singles marketing page, pays $7, goes through onboarding, then to the activation screen, then to the main home - Subscription status trialing, hasMembershipAccess true, membershipSource stripe - After trial ends: subscriptionStatus active, isPayingMember true Couples paid via Stripe: - Primary spouse signs up via couples marketing page, pays $7, routes to covenant onboarding, then Covenant Home - Linked spouse uses the spouse invite link, pays half price, links accounts, routes to covenant onboarding, then Covenant Home Gift Code Users — Basic Membership: - Admin creates code in the admin panel and sends a redeem link to the user - New user hits the redeem page, creates an account, and the redeemMembershipGiftCode Cloud Function runs - Routes through onboarding then activation then home - membershipSource is gift_basic, hasMembershipAccess is true Gift Code Users — Full Access Premium: - Same flow as Basic but user also gets premiumAccessAll set to true - All premium tools unlocked immediately after onboarding Gift Code Users — Couples Basic Membership: - membershipPlan couples, spouseRole primary - A spouse invite code is automatically generated - Routes correctly to covenant onboarding Gift Code Users — Couples Premium Tools: - Both spouses must already be linked before this code can be redeemed - Sets premiumAccessAll to true on BOTH user docs simultaneously Weekly Call Landing Users: - Signs up via the weekly-calls page - membershipSource is weekly_call_landing - Routes to /weekly-call-home — NOT the main identity journey - This flow must remain completely unaffected by any payment fixes Admin and Team Members: - Super admin always bypasses all access gates - Team admins are identified by reading from the teamMembers Firestore collection - Access checks must use the useUnifiedAccess hook — never read the role field directly from the user doc --- PROBLEM 4 — STRIPE WEBHOOK HARDENING The stripeWebhook Cloud Function handles subscription lifecycle events. Verify the following: - subscription created, updated, and deleted events correctly sync to Firestore - invoice.paid and invoice.payment_failed events handled correctly - The current Stripe API version returns customer and subscription on invoices as expanded objects, not plain string IDs — the dot-id property must be extracted explicitly. This fix exists in the referral webhook but needs to be verified in the main webhook too - Webhook signature verification is working correctly - Pricing tier evaluation fires correctly after subscription changes CRITICAL RULES — DO NOT BREAK THESE 1. Never write privileged Firestore fields from the client side. Fields like premiumAccessAll, hasMembershipAccess, subscriptionStatus, isPayingMember, and weeklyCallAccess must only be written by Cloud Functions using the Admin SDK. 2. Always use the useUnifiedAccess hook for role and access checks. Never read the role field directly from the user doc via useAuth. 3. The super admin user always bypasses all gates. Their UID is provided in the repo environment variables. 4. Never chain build and deploy commands together. Run npm run build first, wait for it to complete, then run firebase deploy as a separate command. 5. Deploy Cloud Functions individually using the --only functions:functionName flag. Never deploy all functions at once. 6. The Stripe API version in use is 2026-02-25.clover. Invoice objects return customer and subscription as expanded objects — always extract the id property from them explicitly. 7. Do not use useAuth for role or access decisions. It is only for reading the current user and base user data fields. --- DELIVERABLES 1. Singles $7 trial fully working — user pays, gets access, routes to onboarding 2. Couples primary $7 trial fully working 3. Linked spouse half-price signup fully working 4. All 4 gift code types tested and working 5. Weekly call landing flow confirmed unaffected 6. Stripe webhooks verified and hardened 7. Written summary of every change made and why 8. Test accounts demonstrating each flow working end to end --- WHAT WE NEED FROM YOU - Proven Firebase and Stripe integration experience - Ability to read and interpret Cloud Function logs in Firebase Console - Clear understanding of Stripe Connect vs platform account — these are different contexts and mixing them up is what caused the current bug - TypeScript and React experience - Clear communication on what you changed and why Access to the GitHub repo, Firebase Console, and Stripe Dashboard (read-only) will be provided upon hire.