Billing & Payment Discovery

Workstream 2: Billing & Payment Discovery

Purpose: Comprehensive technical and operational discovery of QuranFlow's billing landscape — what exists today, what the admin needs, what Stripe can provide, and what must be custom-built. Scope: Steps 2.1 through 2.5 of the QuranFlow Admin Backend Redesign Plan. Date: March 2026 Sources: Code audit of 5 GitHub repos, Admin Navigation Interview Report, Admin Capability Map (including Appendix A schema)

Table of Contents

1. Step 2.1 — Checkout Repo Audit
2. Step 2.2 — Current Billing Workarounds
3. Step 2.3 — Stripe Data Available via API
4. Step 2.4 — Billing Screen Requirements
5. Step 2.5 — Billing Integration Brief

Step 2.1 — Checkout Repo Audit

Architecture Overview

QuranFlow's billing is distributed across five repositories that form a multi-layered checkout and payment system. The architecture is split between the legacy QuranFlow-specific backend (Yii2/PHP) and a newer, shared checkout platform (Laravel) that serves multiple AlMaghrib products.

                    Student-Facing                          Backend Services
                    ─────────────                          ────────────────

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│  fe-checkout     │────▶│  fe-checkout-     │────▶│  quranflow-backend   │
│  (QF checkout    │     │  backend          │     │  (Yii2 admin panel)  │
│  frontend+Stripe)│     │  (webhook handler,│     │  Subscriptions table │
│                  │     │  session tracking)│     │  Payment Plans       │
│  Laravel/Vue     │     │  Laravel          │     │  Coupons             │
└──────────────────┘     └──────────────────┘     │  StripeIntegration   │
                                                   └──────────────────────┘
┌──────────────────┐
│  alm-checkout    │     (New multi-product checkout — not yet primary for QF)
│  Laravel/React   │
│  Multi-account   │
│  Stripe          │
└──────────────────┘

┌──────────────────┐
│  wp-plugin-      │     (WordPress shortcode that embeds checkout lightbox)
│  checkout-alm    │
│  React lightbox  │
└──────────────────┘

Repo 1: fe-checkout — QuranFlow Checkout Frontend

Location: almaghrib-engineering/fe-checkout Technology: Laravel 11 + Inertia.js + Vue 3 + Tailwind CSS Primary language: PHP (backend), Vue (frontend) Stripe library: stripe/stripe-php (server-side SDK) Deployment: Docker (Caddy web server), GitHub Actions CI/CD

Stripe Integration Points

Payment Plans Supported

The checkout supports exactly two plans, configured via environment variables:

Source: codebase/config/services.php — prices are mapped by slug (monthly, annual) to Stripe Price IDs.

Coupon/Scholarship Handling

• A single scholarship coupon is used: ID 7IoeEtUb (configurable via STRIPE_SCHOLARSHIP_COUPON_ID)
• The scholarship is a 50% discount on the annual plan only (reducing $120 to $60)
• The coupon is applied at the Stripe level using discounts on Checkout Sessions or Subscriptions
• When scholarship is active, the plan ID sent to the backend webhook is SCHOLARSHIP_PLAN_ID (default: 69) rather than ANNUAL_PLAN_ID (21)
• There is a dedicated /scholarship page that reveals the discount and redirects back to checkout with the scholarship flag

Source: StripeController.php lines involving $hasScholarship, Scholarship.vue

Webhook Handling (fe-checkout)

The WebhookController.php in fe-checkout handles only two events:

Critical gap: This webhook handler does not process subscription lifecycle events (cancellation, failure, past_due). These events are only handled in fe-checkout-backend.

Subscription Duplicate Prevention

Before proceeding to payment, the checkout calls /check-user-subscription which routes through the Laravel backend to fe-checkout-backend's /api/checkout/fe/user-active-subscription endpoint. If an active subscription is found for the email, the checkout displays an alert and prevents duplicate purchase. This is documented in docs/SUBSCRIPTION_CHECK_IMPLEMENTATION.md.

Source: codebase/routes/web.php, docs/SUBSCRIPTION_CHECK_IMPLEMENTATION.md

Data Model (fe-checkout)

fe-checkout stores no local billing data. It uses Laravel sessions for checkout state and relies entirely on:

• Stripe for payment processing
• fe-checkout-backend for session tracking and user provisioning
• quranflow-backend for the actual user account and subscription records

Key Files Inventory

Repo 2: fe-checkout-backend — Checkout Backend Services

Location: almaghrib-engineering/fe-checkout-backend Technology: Laravel 11 (modular architecture) Primary language: PHP (Blade templates for emails) Databases: PostgreSQL (own DB), plus connections to alm_db_core (users) and alm_db_fe (subscriptions)

Role in the System

This is the central webhook processor and session tracker for the QuranFlow checkout. It:

1. Tracks checkout sessions (IP, email, referral URL, status)
2. Receives the invoice.paid webhook from Stripe
3. Creates or updates user accounts in the core database
4. Creates subscription records in the FE database
5. Sends welcome/onboarding emails

Stripe Webhook Handling (THE critical handler)

The StripeService.php in this repo is the primary webhook handler. It processes:

All other Stripe events are ignored (returns { "ignored": true }).

Subscription cancellation handling: There is commented-out code for customer.subscription.deleted that would handle unsubscription with refund logic. This code handles: subscription status update, refund processing for annual plans within 30 days, cancellation/refund emails. However, this is entirely commented out and not active.

Webhook Flow Detail (invoice.paid)

1. Extract invoice data and line item metadata (plan type, email, checkout_session_id)
2. Determine internal plan_id:
   • Annual + 50% coupon = SCHOLARSHIP_PLAN_ID (69)
   • Annual without coupon = ANNUAL_PLAN_ID (21)
   • Monthly = MONTHLY_PLAN_ID (29)
3. Check if user exists in alm_db_core.users by email
   • If not: create user with generated password, send welcome email
   • If exists: check for active subscription — if already active, ignore (dedup)
4. Check/create subscription in alm_db_fe.subscriptions (status = active)
5. Create subscription_signups record with Stripe IDs
6. Create fe_onboarding_emails tracking record
7. Update checkout session status from "draft" to "paid"

Data Model (fe-checkout-backend — own database)

Data Model (fe-checkout-backend writes to external databases)

alm_db_core.users — Creates new user accounts:

• email, name_full, password (hashed), created_at, updated_at

alm_db_fe.subscriptions — Main subscription record:

• user_id, status (active/cancelled), created_at, updated_at, last_active

alm_db_fe.subscription_signups — Individual signup records:

• user_id, plan_id, pp_customer_id (Stripe customer ID), pp_subscription_id (Stripe subscription ID), pp_subscription_status, signup_total, signup_used, has_loggedin, date_end, created_at

alm_db_fe.fe_onboarding_emails — Email sequence tracking:

• subscription_id, email_1 through email_6 (boolean flags), created_at

API Endpoints

Key Files Inventory

Repo 3: quranflow-backend — QuranFlow Admin Panel

Location: almaghrib-engineering/quranflow-backend Technology: Yii2 (PHP framework) Primary language: PHP Stripe library: Stripe PHP SDK (vendored in backend/components/stripe/)

Role in the System

This is the admin panel that the QuranFlow admin uses daily. It has its own Stripe integration layer and local subscription management, but these are legacy systems primarily used for manual subscription operations rather than automated checkout.

Stripe Integration (StripeIntegrationComponent)

Located at common/components/StripeIntegrationComponent.php, this component provides direct Stripe API calls:

Subscription Data Model (subscriptions table)

Important: The subscription is linked to user_link_level_tag_id, NOT directly to user_id. This means subscriptions are per-enrollment (student + semester + level), not per-student. This has implications: if a student is promoted to a new level or enrolls in a new semester, their subscription link changes.

Users Table (billing-relevant fields)

The users table contains several billing-relevant fields:

stripe_customer_id population gap: The checkout flow in fe-checkout creates Stripe customers directly and passes the customer ID to fe-checkout-backend, which stores it in subscription_signups.pp_customer_id, NOT in users.stripe_customer_id. Only manual admin-created subscriptions (via the subscription modal) populate the users table field. This means most students who enrolled through the checkout have their Stripe customer ID stored in a different database.

Google IAP fields: The GoogleInAppPurchase.php helper writes to google_in_app_purchase_subscription_state and google_in_app_purchase_subscription_expiry_time via Yii2's dynamic property access, but these fields are not formally declared in the User.php model class. They exist as database columns only.

Source: common/models/User.php (line 30: @property string $stripe_customer_id), common/helpers/GoogleInAppPurchase.php

Subscription Types and Pricing

The Ex_Subscriptions model defines subscription constants:

Note: These are the legacy QuranFlow pricing tiers. The current checkout (fe-checkout) uses the Faith Essentials pricing: $15/month or $120/year. This indicates a pricing model transition has occurred, and the admin backend's subscription constants are outdated.

Payment Types

The admin can create subscriptions manually via a modal on the student profile page, choosing either "Goodwill" (free) or "Stripe" (paid with card entry).

Payment Plans Data Model

The payment_plans table defines pricing options:

Source: common/models/PaymentPlans.php, backend/views/payment-plans/_form.php

Key finding: The plan type dropdown includes family and discount as options, and sub_type includes Installment. This means family plans and instalment payment structures have partial representation in the database schema, even though no automated logic exists to process them. They are defined as plan records but all management happens in Google Sheets.

Coupons Data Model

The coupons table tracks discount codes:

Source: common/models/Coupons.php

Additionally, a couponsToken table provides a token-based redemption system:

Source: common/models/CouponsToken.php

This means the admin backend has infrastructure for unique, single-use coupon tokens (each token can only be redeemed once by one user). This is more sophisticated than the checkout's single shared scholarship coupon ID.

Stripe Products Table

A stripeProducts table exists in the database:

Source: common/models/StripeProducts.php, backend/controllers/StripeProductsController.php

The StripeProductsController provides CRUD with Stripe sync via StripeIntegrationComponent::createStripeProductUsingSdk() — but this controller is not listed in the main navigation (not in Appendix B of the capability map).

Payments Table Schema

The payments table tracks historical transaction records:

Source: common/models/Payments.php, common/models/extended/payments/Ex_Payments.php

The PaymentsController.actionIndex() retrieves payment history via raw SQL joining payments with payment_plans and users. The actionCreate() method contains a dead die('test') call, indicating it was disabled during development and never re-enabled — payments cannot be created through the admin UI.

Source: backend/controllers/PaymentsController.php

Subscription Stats Bar (Dashboard)

The admin dashboard includes a subscription statistics view (_subscriptions_stats_bar.php) showing:

• Yearly One-time, Yearly Monthly, Semester One-time, Semester Monthly, Semester Family, Number of Dependents
• Both Stripe and Local Database counts are displayed side by side

Critical finding: The Semester Family count and Number of Dependents are hardcoded to 4 in the view. The Local Database section also uses hardcoded values (30 for yearly/semester counts). This confirms these views are mockups/placeholders that were never connected to live data.

Source: backend/views/site/_subscriptions_stats_bar.php

Refund View (Existing)

A refund modal exists at backend/views/users/_refund.php. It presents a dropdown of subscriptions and a "Confirm" button that POSTs to users/refund. This shows refund capability was designed but may not be fully implemented — the form exists but the underlying UsersController::actionRefund() needs verification.

Source: backend/views/users/_refund.php

Student Subscription Details View

The student profile shows subscription details via _student_subscription_details.php:

• Lists active subscriptions with plan name (looked up from payment_plans by payment_plan_id) and date range
• Each subscription has a delete/cancel button
• "Renew" and "Cancel" action buttons at the bottom
• JavaScript handles subscription type selection and add/delete operations

This is the existing billing surface within the admin — it shows locally-stored subscription records but not real-time Stripe data.

Source: backend/views/users/_student_subscription_details.php

Legacy Payment Systems

The quranflow-backend contains three legacy payment integrations beyond the current Stripe checkout:

1. Google In-App Purchase (Android)

Located at common/helpers/GoogleInAppPurchase.php and backend/controllers/InAppPurchaseController.php:

• Handles Google Play subscription lifecycle notifications via Pub/Sub webhooks
• Processes 11 notification types: PURCHASED, RENEWED, CANCELED, ON_HOLD, IN_GRACE_PERIOD, RESTARTED, DEFERRED, PAUSED, REVOKED, EXPIRED, RECOVERED
• Links purchases to users via externalAccountIdentifiers.obfuscatedExternalAccountId
• Updates users table fields: google_in_app_purchase_subscription_state, google_in_app_purchase_subscription_expiry_time
• Package name: com.almaghrib.quranrevdevelopment (legacy branding)

Important: These user fields (google_in_app_purchase_subscription_state, google_in_app_purchase_subscription_expiry_time) exist in the database but are NOT declared in the User model's property docblock — they're accessed dynamically via Yii2's magic properties.

Implication for billing integration: Some students may have active subscriptions through Google Play rather than Stripe. The billing dashboard must account for this payment channel.

2. PayPal (Sandbox)

Located at common/components/PaypalComponent.php, backend/controllers/PaypalController.php, backend/models/PaypalProduct.php, backend/models/PaypalPlan.php:

• Full PayPal product and plan management via REST API
• Uses sandbox credentials (not production) — suggesting this was developed but never deployed to production
• Supports: create/update products, create plans, create subscriptions, retrieve products
• Admin views exist at backend/views/paypal/ for product/plan management

3. InfusionSoft Migration

Located at common/models/InfusionSoftSubscriptions.php:

• Model for InfusionSoftSubscriptions table tracking migrated subscription data
• Fields: contact_id, product_id, subscription_plan_id, product_name, billing_cycle, start_date, end_date, last_billed_date, status, emailatInfusionSoft, charges
• Legacy webhook handler in Ex_Subscriptions/MisGT.php contains processStripeWebhooks() with InfusionSoft migration logic and hardcoded user_ids in TODO comments

Implication: The system has been through at least three payment platform transitions: InfusionSoft → PayPal (attempted) → Stripe. Historical data from earlier platforms may exist in the database.

Legacy Webhook Handler (MisGT.php)

The Ex_Subscriptions/MisGT.php file contains a separate, legacy webhook handler (processStripeWebhooks()) that:

• Processes customer.created, charge.succeeded, invoice.payment_succeeded, payment_intent.succeeded
• Uses hardcoded legacy Stripe Plan IDs (e.g., plan_FXeRd8nuOaELrK)
• Contains TODO comments with hardcoded user IDs for testing
• Includes createGoodWillSubscription() for free subscriptions and createStripeSubscription() for legacy Stripe subscriptions

This is distinct from the fe-checkout-backend webhook handler and appears to be the original webhook processing before the checkout was rebuilt. It confirms the legacy pricing model was active at one point.

Source: common/models/extended/generic/Ex_Subscriptions/MisGT.php

Admin Panel Controllers Related to Billing

Key Files Inventory

Repo 4: alm-checkout — Multi-Product Checkout Platform

Location: almaghrib-engineering/alm-checkout Technology: Laravel 11 + Inertia.js + React + TypeScript + Tailwind CSS Stripe library: stripe/stripe-php (uses Laravel Cashier migrations)

Role in the System

This is the newer, centralized checkout platform designed to handle multiple AlMaghrib products (events, Faith Essentials subscriptions, donations) across multiple Stripe accounts and regional entities. It uses a template-based system where checkout flows are defined by an API and rendered dynamically.

Multi-Account Stripe Architecture

Unlike fe-checkout (single Stripe account), alm-checkout supports six Stripe accounts:

Source: codebase/config/services.php, codebase/app/Services/StripeService.php

Stripe Integration Points

Data Model (uses Laravel Cashier schema)

The alm-checkout repo includes Laravel Cashier-compatible migrations:

Users table additions: stripe_id, pm_type, pm_last_four, trial_ends_at

Subscriptions table: user_id, type, stripe_id (unique), stripe_status, stripe_price, quantity, trial_ends_at, ends_at

Subscription Items table: standard Cashier schema with stripe_id, stripe_product, stripe_price, quantity, meter_id, meter_event_name

QuranFlow Connection

The config/services.php includes explicit QuranFlow API configuration:

'quranflow' => [
    'base_url' => env('QURANFLOW_API_URL', 'https://dev.api.quranflow.org'),
    'api_version' => env('QURANFLOW_API_VERSION', 'v8'),
    'platform' => env('QURANFLOW_PLATFORM', 'web'),
]

This suggests alm-checkout is designed to eventually replace fe-checkout as the QuranFlow checkout frontend, with the ability to handle multi-product checkout scenarios.

Key Files Inventory

Repo 5: wp-plugin-checkout-alm — WordPress Checkout Plugin

Location: almaghrib-engineering/wp-plugin-checkout-alm Technology: WordPress plugin + React lightbox (via shortcode)

Role in the System

This is a lightweight WordPress plugin that embeds a checkout lightbox/button on WordPress pages. It renders a React component via a shortcode [react_button type="event"] that opens the alm-checkout system in a modal. It does not contain any billing logic itself — it's purely a UI embedding mechanism.

Relevance to billing discovery: Minimal. This plugin is the entry point for WordPress-hosted landing pages but delegates all billing to alm-checkout.

Cross-Repo Data Flow Summary

Student clicks "Subscribe"
         │
         ▼
┌─────────────────┐
│   fe-checkout    │  1. Collects email + plan choice
│   (or alm-       │  2. Calls fe-checkout-backend to create checkout session
│    checkout)     │  3. Creates Stripe Checkout Session or Subscription
│                  │  4. Redirects to Stripe hosted checkout (or processes inline)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Stripe         │  5. Processes payment
│                  │  6. Sends `invoice.paid` webhook
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   fe-checkout-   │  7. Receives webhook
│   backend        │  8. Looks up or creates user in quranflow-backend DB
│                  │  9. Creates subscription in FE DB
│                  │  10. Sends welcome email
│                  │  11. Updates checkout session to "paid"
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   quranflow-     │  Now has: user record, subscription_signup record
│   backend DB     │  Admin can see: student in list, payment in history
│                  │  Admin CANNOT see: Stripe subscription status,
│                  │    payment method, renewal dates (must go to Stripe)
└─────────────────┘

Critical Architectural Findings

1. Two subscription systems exist in parallel: The legacy QuranFlow subscriptions table (linked to user_link_level_tag_id with cycles, billing dates, plan IDs) and the newer FE subscription_signups table (linked to user_id with Stripe IDs, plan IDs, status). These are in different databases and serve different purposes.

2. stripe_customer_id in the users table is inconsistently populated: The checkout flow stores the Stripe customer ID in subscription_signups.pp_customer_id, not in users.stripe_customer_id. Only manual admin-created subscriptions (via the subscription modal) would populate the users table field. This is confirmed by code analysis — the User model declares the field but the fe-checkout-backend webhook handler never writes to it.

3. No automated subscription lifecycle handling: The only webhook event processed is invoice.paid. There is no handling of customer.subscription.deleted, invoice.payment_failed, or customer.subscription.updated. A legacy handler in MisGT.php processes more events but uses hardcoded user IDs and legacy plan IDs — it is not in active use.

4. Pricing divergence: The admin backend defines legacy pricing ($67/month, $197/4months, $497/year) while the checkout uses Faith Essentials pricing ($15/month, $120/year). The plan_id mapping bridges this (21=annual, 29=monthly, 69=scholarship).

5. Family plans and instalment plans have partial schema representation: The payment_plans.type field supports family and discount as values, and sub_type supports Installment. This means the database can store these plan types, but no business logic processes them — all management happens in Google Sheets. The dashboard subscription stats bar has family/dependent counters but they display hardcoded values (all set to 4).

6. Three payment channels exist, only one is actively maintained: (a) Stripe via fe-checkout (active), (b) Google Play In-App Purchase (functional — updates user state on subscription events), (c) PayPal (sandbox only, likely never deployed). The billing integration must account for students who may have Google Play subscriptions rather than Stripe.

7. Duplicate/dead subscription check: fe-checkout implements a pre-checkout subscription check (/check-user-subscription) that calls fe-checkout-backend's /api/checkout/fe/user-active-subscription to prevent duplicate purchases. This is documented in docs/SUBSCRIPTION_CHECK_IMPLEMENTATION.md. However, the fe-checkout-backend also performs dedup during webhook processing (checks for existing active subscription before creating a new one). These are two independent layers of protection.

8. Coupon system is more capable than currently used: The admin backend has a full coupon CRUD with semester scoping, Stripe sync, percentage-off configuration, expiry dates, and a token-based single-use redemption system (couponsToken table). The checkout only uses a single hardcoded coupon ID. The coupon management screens already show usage count per coupon (via Ex_Coupons.getJsonData() which joins subscriptions by coupon_id).

9. Existing billing surfaces in the admin are partially built: The student profile has a subscription details card showing active subscriptions from the local DB with Renew/Cancel buttons. A refund modal exists. The dashboard has a subscription stats bar. The payments index shows transaction history. These are starting points — not greenfield.

10. Three payment platform transitions have occurred: InfusionSoft (migrated from) → PayPal (sandbox, never deployed) → Stripe (current). Historical data from InfusionSoft exists in the InfusionSoftSubscriptions table. Migration code and references persist across the codebase.

Step 2.2 — Current Billing Workarounds

Workaround Inventory

Workaround Detail Analysis

W1: Stripe Dashboard Dependency

What the admin does: Opens Stripe dashboard to look up customer by email, view subscription status, check payment history, see upcoming invoices, manage subscription (cancel, modify, refund).

Why it's a workaround: The admin backend has a "Payments" screen (/payments/index) but it only shows historical payment records stored locally. It does not show:

• Real-time subscription status (active, past_due, canceled)
• Payment method details
• Upcoming renewal dates
• Failed payment attempts
• Refund history

Ideal replacement: A billing tab on the student profile showing real-time Stripe data (subscription status, plan, payment history, payment method) with action buttons (cancel, modify, refund link).

W2: Family Payment Plans

What the admin does: Maintains a Google Sheet listing families where multiple members share a single payment arrangement (e.g., one payment covers two siblings).

Why it's a workaround: Stripe doesn't natively support "family plans." Each student is a separate Stripe customer with a separate subscription. The admin must manually track which students are connected and ensure their billing is coordinated.

Ideal replacement: A "family group" entity in the admin backend that links student accounts, with a shared billing view showing all family members' subscription status and a single point for managing family-wide billing changes.

Volume estimate: Unknown — flagged as open question. Interview suggests this is a recurring pattern but exact numbers per semester are not available.

W3: Scholarship Tracking

What the admin does: Tracks scholarship recipients in a Google Sheet. The checkout handles the 50% annual discount via a Stripe coupon, but ongoing scholarship management (renewals, eligibility changes, different scholarship levels) is manual.

Why it's a workaround: The only automated scholarship mechanism is a binary 50% coupon on annual plans. There's no concept of:

• Partial scholarships (25%, 75%)
• Scholarship with conditions (maintain submission count, attend sessions)
• Scholarship renewal tracking
• Different scholarship sources or programs

Ideal replacement: Scholarship status as a tag/flag on student profiles with configurable discount levels, visible in billing screens and reportable.

Volume estimate: Unknown — flagged as open question.

W4: Deferment Tracking

What the admin does: Tracks students who have been granted payment deferment (delayed start, paused billing) in a Google Sheet.

Why it's a workaround: There is no concept of deferment in any codebase. A deferred student's Stripe subscription is either active (being charged) or canceled (not being charged). There's no middle state.

Ideal replacement: A deferment status on student profiles that pauses billing (via Stripe's pause_collection or subscription schedules) and tracks the resumption date.

Volume estimate: Unknown — flagged as open question.

W5: Support Staff Billing Access

Current state: Customer support staff must escalate all billing questions to the admin because:

1. They have no access to Stripe
2. The admin backend shows no billing data
3. Google Sheets with billing info may not be shared with support

Ideal replacement: A read-only billing view accessible to support staff (user type 5: Admin View Only) showing subscription status, payment history, and plan type — without the ability to modify.

W8: Linked Deactivation + Payment Cancellation

Current state: When a student leaves the program:

1. Admin deactivates the student account in the backend (changes user_activation_status to 0)
2. Admin separately navigates to Stripe Dashboard
3. Admin finds the customer by email
4. Admin cancels the subscription in Stripe

If step 2-4 is missed, the student continues to be charged. If step 1 is missed, the student retains app access.

Ideal replacement: A single "Deactivate Student" action that simultaneously:

• Deactivates the backend account
• Cancels the Stripe subscription (via API)
• Logs both actions
• Optionally processes a refund

Volume and Frequency Estimates (Open Questions)

Step 2.3 — Stripe Data Available via API

Stripe Object Reference for QuranFlow Admin

Customer Object

API Endpoints:

• GET /v1/customers/{id} — Retrieve a customer
• GET /v1/customers?email={email} — Search by email
• GET /v1/customers/search?query=email:'{email}' — Search API

Rate Limits: 100 read requests/second in live mode. Customer search is more expensive.

Admin Actions Available:

• Update customer metadata
• Update default payment method
• Apply credit/debit balance

Subscription Object

API Endpoints:

• GET /v1/subscriptions/{id} — Retrieve a subscription
• GET /v1/subscriptions?customer={customer_id} — List customer's subscriptions
• POST /v1/subscriptions/{id} — Update (cancel, modify, pause)
• DELETE /v1/subscriptions/{id} — Cancel immediately

Rate Limits: 100 read requests/second. Listing with expand can be expensive.

Admin Actions Available:

• Cancel subscription (immediately or at period end)
• Pause collection (for deferments)
• Resume paused collection
• Update subscription (change plan, apply coupon)
• Schedule cancellation at a future date

Invoice Object

API Endpoints:

• GET /v1/invoices?customer={customer_id} — List customer's invoices (full payment history)
• GET /v1/invoices/{id} — Retrieve a single invoice
• GET /v1/invoices/upcoming?customer={customer_id} — Preview next invoice

Rate Limits: 100 read requests/second. Listing all invoices for a customer is a single API call with pagination.

Admin Actions Available:

• Void an open invoice
• Mark uncollectible
• Send invoice (email to customer)
• Create manual invoice

Payment Intent Object

API Endpoints:

• GET /v1/payment_intents/{id} — Retrieve payment details
• Not typically listed directly — accessed via Invoice

Admin Relevance: Most useful for troubleshooting failed payments — provides the exact decline code and failure reason.

Coupon / Promotion Code

API Endpoints:

• GET /v1/coupons — List all coupons
• GET /v1/coupons/{id} — Retrieve a coupon
• POST /v1/coupons — Create a coupon

Admin Relevance: Already partially integrated — CouponsController in quranflow-backend syncs coupons to Stripe. But the admin cannot see coupon usage or applied discounts on student subscriptions.

Product / Price

API Endpoints:

• GET /v1/prices — List all prices
• GET /v1/products — List all products

Admin Relevance: Needed for the Payment Configuration screen to display and manage available plans.

Answering Key Questions

Q1: Real-time API vs. webhooks for subscription status?

Answer: Both approaches are viable, with different trade-offs.

Recommendation: Use webhooks for proactive alerts (failed payments, cancellations) and real-time API for student profile payment tab (on-demand when admin views a student). This avoids building a full local Stripe data mirror while still enabling the dashboard alerts the admin requested.

Q2: Is stripe_customer_id populated?

Answer: Inconsistently. Based on code analysis:

• users.stripe_customer_id (QuranFlow backend): Populated only when subscriptions are created through the admin panel's StripeIntegrationComponent. Students who signed up through the checkout (most students) have their Stripe customer ID stored in subscription_signups.pp_customer_id in the FE database instead.

• subscription_signups.pp_customer_id (FE database): Populated by the webhook handler in fe-checkout-backend for all checkout-originated subscriptions.

Implication: To look up a student's Stripe data, the system needs to:

1. Check users.stripe_customer_id first
2. If empty, look up subscription_signups.pp_customer_id in the FE database by user_id
3. If neither exists, search Stripe by email using Customer::search()

Recommendation: Backfill users.stripe_customer_id from subscription_signups.pp_customer_id and ensure future webhook processing updates it.

Q3: Full payment history with one API call?

Answer: Yes, with pagination. GET /v1/invoices?customer={customer_id}&limit=100 returns all invoices for a customer, ordered by creation date. Each invoice includes amount, status, date, and line items. For most QuranFlow students (1-3 years of monthly or annual payments), this would be 12-36 invoices — well within a single paginated response.

Stripe also provides hosted_invoice_url on each invoice, giving the admin a direct link to a Stripe-rendered invoice page without needing to build one.

Q4: What powers "failed payment alerts"?

Answer: Two Stripe webhook events:

Current state: Neither event is processed by any QuranFlow system. The fe-checkout-backend webhook handler only processes invoice.paid.

To implement: Add webhook handlers for invoice.payment_failed and customer.subscription.updated, store failed payment alerts in a local alerts table, and surface them on the admin dashboard.

Stripe's automatic retry schedule: By default, Stripe retries failed payments on a Smart Retries schedule (typically 3 attempts over ~3 weeks before marking the subscription as past_due or canceled). This is configurable in Stripe Dashboard > Settings > Billing > Subscriptions and emails.

Q5: Family plans in Stripe?

Answer: Stripe has no native family plan concept. Options for representation:

Recommendation: Use metadata + custom layer (option 3). Create a "family group" entity in the admin backend that links student IDs. Apply family-specific coupons to each member's subscription. The family group provides the administrative view while Stripe handles individual billing. This aligns with the admin's stated need (interview Q2): seeing family plan status on student profiles.

Improvement Opportunities: Stripe Features Not Currently Used

Step 2.4 — Billing Screen Requirements

A. Student Profile — Payment Tab

Purpose: Show all billing information for a single student in context, eliminating the need to visit Stripe.

Data Displayed

Actions Available

View-Only Access (Support Staff)

Support staff (user type 5) should see:

• Subscription status, plan, payment history, special flags
• NO action buttons except "View in Stripe" (which they won't have access to unless given Stripe viewer role)

B. Billing Dashboard / Alerts

Purpose: Proactive operational view showing billing exceptions that need attention. This directly addresses interview Q7 — the admin's ideal dashboard.

Alert Types

Metrics (Summary Bar)

Technical Implementation

Recommended approach: Implement webhook handlers for key events and store them in a local billing_events table. The dashboard queries this table rather than making live Stripe API calls.

C. Payment Configuration

Purpose: Manage payment plans, coupons, scholarships, deferment policies, and family plan settings.

Sub-screens

C1. Payment Plans (already exists at /payment-plans/index)

C2. Coupons (already exists at /coupons/index)

C3. Scholarship Management (NEW — replaces Google Sheets)

C4. Deferment Management (NEW — replaces Google Sheets)

C5. Family Plan Management (NEW — replaces Google Sheets)

D. Semester Close — Payment Workflow

Purpose: Streamline the most error-prone billing workflow — setting up payments for continuing students after promotions.

Current Pain Point (from interview Q3, Q8)

1. Admin promotes students (or automation does)
2. Admin goes to Stripe to create subscriptions for continuing students
3. But promotions may change (teacher overrides, student opt-outs)
4. Admin must correct Stripe subscriptions that were set up too early

Proposed Workflow

Technical Approach

• Step 3 uses Stripe's Subscription::create() or Subscription Schedule to create subscriptions that start on the new semester date
• Step 4 uses the linked deactivation action (Stripe cancel + backend deactivate)
• Step 5 is a read-only verification view

Improvement: Gate Payment Setup Behind Promotion Finalization

Implement a promotion gate: the billing setup step cannot begin until the admin marks promotions as "finalized." This prevents the current problem of setting up payments before promotion decisions are complete.

E. Additional Billing Surfaces Beyond the Plan

E1. Refund Management

Source: The commented-out unsubscription code in fe-checkout-backend already contains refund eligibility logic (30-day window for annual plans, amount verification).

E2. Revenue Reports

E3. Automated Billing Emails

Step 2.5 — Billing Integration Brief

1. What Billing Data Exists Today

In Stripe (source of truth for payment data)

In Local Databases

In Google Sheets Only (no system representation)

Legacy Payment Data (may exist in database)

2. What the Admin Needs to See and Do

Must-Have (eliminates highest-impact workarounds)

Should-Have (significant efficiency gain)

Nice-to-Have (future improvement)

3. What Stripe Can Provide

4. What Gaps Remain (Custom Development Needed)

5. Billing as Nav Sections — Proposed Screens

The following screens must have a home in whatever navigation structure Workstream 1 selects:

Primary Billing Screens

Supporting Billing Screens

Navigation Accommodation Requirements

Any navigation candidate from Workstream 1 must accommodate:

1. Billing data on student profiles — regardless of where billing lives as a section, the student profile must have a payment tab
2. Billing alerts on the dashboard — failed payments and past-due subscriptions must surface on whatever serves as the operational dashboard
3. A billing configuration area — plans, coupons, scholarships, deferments, family plans need a management home
4. A semester-close billing step — the semester close workflow must include billing operations
5. Role-based access — support staff see read-only billing; admin sees full controls

6. Implementation Phases

Phase 1: Foundation (Weeks 1-4)

Goal: Eliminate the highest-impact workaround (Stripe Dashboard dependency) and enable support staff independence.

Note: Phase 1 should also verify the population of google_in_app_purchase_subscription_state on users and decide whether to display it on the billing tab. If only a handful of students use Google IAP, a simple text field may suffice.

Impact: Admin and support staff can see billing data without leaving the admin backend. Reduces Stripe visits by ~60%.

Phase 2: Actions + Alerts (Weeks 5-8)

Goal: Enable billing actions from within the admin backend and implement proactive alerts.

Impact: Admin can manage most billing operations without Stripe. Failed payments are visible proactively. Linked deactivation eliminates the most critical process gap.

Phase 3: Bulk Operations + Tracking (Weeks 9-12)

Goal: Replace Google Sheets for scholarship, deferment, and family plan tracking. Streamline semester-end billing.

Impact: All Google Sheets eliminated. Semester-end billing is safer and faster. All billing data lives in one system.

Phase 4: Optimization (Weeks 13-16)

Goal: Add polish, reporting, and self-service capabilities.

Impact: Full billing management maturity. Admin is proactive rather than reactive. Students can self-serve for routine billing tasks.

7. Open Questions Requiring PM/Admin Input

Appendix: Complete Key Files Index

fe-checkout (almaghrib-engineering/fe-checkout)

• codebase/app/Http/Controllers/StripeController.php — Stripe API interactions
• codebase/app/Http/Controllers/WebhookController.php — Webhook receiver
• codebase/routes/web.php — Checkout flow orchestration
• codebase/app/Services/AlMaghribApiService.php — API client to backend
• codebase/config/services.php — Stripe configuration
• codebase/resources/js/Pages/Checkout/Checkout.vue — Checkout UI
• codebase/resources/js/Pages/Checkout/Scholarship.vue — Scholarship page

fe-checkout-backend (almaghrib-engineering/fe-checkout-backend)

• codebase/app/Modules/Checkout/Services/StripeService.php — Critical webhook handler
• codebase/app/Modules/Checkout/Services/CheckoutService.php — Session CRUD
• codebase/app/Modules/Checkout/Services/CheckoutItemService.php — Item and subscription management
• codebase/app/Modules/Checkout/Routes/api.php — API routes
• codebase/app/Modules/Checkout/Models/Checkout.php — Checkout model
• codebase/app/Modules/Checkout/Models/CheckoutItem.php — Item model
• codebase/app/Modules/Checkout/Models/CheckoutRecurringFe.php — FE subscription signup model
• codebase/app/Modules/Checkout/Database/Migrations/2025_02_10_135429_checkout.php — Checkout tables
• codebase/app/Modules/Checkout/Database/Migrations/2025_02_12_135429_checkout_items.php — Item tables
• codebase/app/Modules/Checkout/Database/Migrations/2025_07_12_061223_checkout_recurring_fe.php — Recurring FE table

quranflow-backend (almaghrib-engineering/quranflow-backend)

Core billing components:

• common/components/StripeIntegrationComponent.php — Stripe API wrapper (Customer, Subscription, Charge, Coupon, Product operations)
• common/components/PaypalComponent.php — PayPal REST API wrapper (sandbox credentials; product/plan/subscription management)
• common/helpers/GoogleInAppPurchase.php — Google Play subscription lifecycle (11 notification types, user state updates)
• common/helpers/InAppPurchase.php — Base IAP logging class

Data models:

• common/models/Subscriptions.php — Subscription data model (linked to user_link_level_tag_id)
• common/models/Payments.php — Payment transactions (marchant: 1=Stripe, 2=PayPal; status, coupon_id, subscription_id, user_id)
• common/models/PaymentPlans.php — Plan definitions (type: semester/Year/family/discount; sub_type: OneTime/Installment; product_id for Stripe lookup)
• common/models/Coupons.php — Coupons (semester-scoped, percentage_off, expiry_date)
• common/models/CouponsToken.php — Single-use coupon tokens (token, coupon_id, redeemed_by)
• common/models/StripeProducts.php — Stripe product/plan records (name, type, currency, interval, amount)
• common/models/InfusionSoftSubscriptions.php — Legacy InfusionSoft migration data
• common/models/User.php — User model (stripe_customer_id + undeclared google_in_app_purchase_* fields)

Extended models:

• common/models/extended/generic/Ex_Subscriptions.php — Subscription constants, type/pricing definitions
• common/models/extended/generic/Ex_Subscriptions/AddGT.php — Subscription creation (cycle-based billing dates)
• common/models/extended/generic/Ex_Subscriptions/GetGT.php — Query methods (goodwill, stripe, by user)
• common/models/extended/generic/Ex_Subscriptions/MisGT.php — Legacy: goodwill creation, legacy Stripe subscriptions, processStripeWebhooks (hardcoded plan IDs/user IDs)
• common/models/extended/payments/Ex_Payments.php — recordTransaction(), getPaymentsHistory() (raw SQL)
• common/models/extended/payments/Ex_Coupons.php — Coupon listing with usage count (joins subscriptions by coupon_id)
• common/models/extended/payments/Ex_PaymentPlans.php — Plan lookup by product_id

Controllers:

• backend/controllers/PaymentsController.php — Payment history view (create action has die('test') — dead code)
• backend/controllers/CouponsController.php — Coupon CRUD + Stripe sync via createCoupon()
• backend/controllers/PaymentPlansController.php — Plan CRUD
• backend/controllers/StripeProductsController.php — Stripe product management (not in main nav)
• backend/controllers/PaypalController.php — PayPal product/plan management (sandbox)
• backend/controllers/InAppPurchaseController.php — Google IAP webhook receiver

Views:

• backend/views/users/_student_subscription_details.php — Student profile subscription card (local DB subscriptions, Renew/Cancel buttons)
• backend/views/users/_subscription_modal.php — Manual subscription creation (Goodwill/Stripe choice, Stripe card element)
• backend/views/users/_refund.php — Refund modal (subscription dropdown, confirm action)
• backend/views/site/_subscriptions_stats_bar.php — Dashboard subscription stats (hardcoded family/dependent values)
• backend/views/payment-plans/_form.php — Plan form (type: semester/Year/family/discount; sub_type: OneTime/Installment)
• backend/views/coupons/_form.php — Coupon form (name, semester, short_code, percentage_off, expiry)
• backend/assets_n/js/custom/stripe-components.js — Legacy Stripe.js card element with test API key

alm-checkout (almaghrib-engineering/alm-checkout)

• codebase/app/Services/StripeService.php — Multi-account Stripe service (6 accounts: US, CA, GB, GB_FD, AU, FE)
• codebase/app/Http/Controllers/CheckoutController.php — Template-based checkout flow handler
• codebase/config/services.php — Multi-account Stripe config + QuranFlow API config
• codebase/config/checkout.php — Checkout API config
• STRIPE_IMPLEMENTATION_GUIDE.md — Comprehensive implementation guide (Phase 1/2 scenarios)
• codebase/database/migrations/2025_10_09_140105_create_customer_columns.php — Customer columns (stripe_id, pm_type, pm_last_four)
• codebase/database/migrations/2025_10_09_140106_create_subscriptions_table.php — Subscriptions table (Laravel Cashier-compatible)
• codebase/database/migrations/2025_10_09_140107_create_subscription_items_table.php — Subscription items table
• codebase/resources/js/components/Coupon.tsx — Coupon component (React)
• codebase/resources/js/components/Payment.tsx — Payment component (React)
• codebase/resources/js/components/stripe/StripeCheckoutEmbed.tsx — Embedded Stripe Checkout (React)
• codebase/resources/js/components/stripe/StripePaymentForm.tsx — Stripe payment form (React)
• codebase/resources/js/hooks/useStripeCheckout.ts — Stripe checkout hook
• codebase/resources/js/types/stripe.ts — Stripe TypeScript type definitions

wp-plugin-checkout-alm (almaghrib-engineering/wp-plugin-checkout-alm)

• codebase/plugin.php — WordPress plugin (UI embedding only, no billing logic)