5 · Payments & plans

TL;DR

Objective — stand up the gateway and plans without the two expensive mistakes: never assume the webhook URL or event list (vendors ship custom controllers) and never invent pricing tiers (that’s a market decision) — most work is in the Stripe dashboard, a few values land in the panel.

User part + done-when

👤 User part — decide the Stripe account strategy and the plan pricing, create the account/sandbox/webhook and copy the keys in the Stripe dashboard, confirm each human-gated write, and paste keys into the admin panel; an agent discovers the real webhook URL, checks DB columns, and seeds plan rows.

Done when the strategy is recorded, the real webhook URL + events are discovered (not assumed), keys are in the panel with DESCRIBE-verified lengths, a sandbox test payment fires the webhook 200, and plans come only from approved research (or are marked BLOCKED).  ·  ⏱ 60–120 min  ·  🔀 mixed (👤 Stripe + decisions, 🤖 discovery + DB).

Background

This is the heaviest page in the phase and the most expensive to get wrong. Most of the work happens in the Stripe dashboard (external), then a few values land in the admin panel. Two rules dominate everything below: never assume the webhook URL or event list (CodeCanyon apps ship custom controllers), and never invent pricing tiers (that’s a market decision, not a config choice).

SSH artisan + DB writes use $PHP_BIN

Any artisan/tinker you run over SSH (column checks, plan seeding) must use the $PHP_BIN resolved on page 3 — never bare php. Every Stripe write is human-gated (see §4) even in sandbox.

Steps

1. Choose a Stripe account strategy

Before creating any account or webhook, decide which Stripe account this app lives under. The right choice is cheap now and expensive to change after customers subscribe — a product decision, not a config one.

Who does this

👤 User picks the account strategy (A/B/C/D) — a business choice about accounting, statement descriptors, and migration cost that an agent can inform but not make.

1. Pick the account option from the trade-off table.

   Option	Account	Setup cost	Statement descriptor	Best for
   A. Catch-all	Existing “general” account	Zero — swap .env keys	❌ Shows the catch-all name	Pre-launch, ship today
   B. Rename unused	An abandoned account you own	~5 min	✅ New project name	Recycling old accounts
   C. New dedicated	Fresh account under your org	~15 min	✅ Clean from day 1	”Serious” product, clean accounting
   D. A → C later	Catch-all now, graduate later	Zero now	Mixed during bootstrap	Launch fast, defer

   • ✅ An option is chosen with rationale recorded in _CUSTOMIZATIONS.md → ## Stripe account strategy.

Migration cost depends on your billing architecture — check before committing to A.

1. Detect the billing architecture to know A’s migration cost.

   # Cashier? (persistent Subscription objects — migration is HIGH cost)
   grep -rn "Billable\|->newSubscription\|->subscriptions()" app/Models/ app/Http/ 2>/dev/null | head
   # Custom webhook controller? (ad-hoc invoices — migration is NEAR-ZERO cost)
   find app/ -iname "*Stripe*Controller*" -o -iname "*BillingWebhook*" 2>/dev/null
   # Expected: Cashier usage (Billable/newSubscription) OR a custom Stripe controller

   • ✅ Architecture is known: Cashier (Billable trait) → active subscriptions don’t transfer; pick C upfront. Ad-hoc invoices (Froiden/WorkDo — a fresh Stripe Invoice each cycle) → swapping .env keys is enough; A is safe, graduate to C later.

What never migrates freely even for ad-hoc apps: historical invoices + dispute history (stay in the old account), the statement descriptor on past charges, and tax filings / 1099-K (mid-year splits = two 1099-Ks). Record your choice, rationale, and migration trigger in _CUSTOMIZATIONS.md → ## Stripe account strategy.

2. Discover the REAL webhook URL and event list

Do NOT assume the webhook URL is /stripe/webhook

Many CodeCanyon apps ship a custom webhook controller at a non-canonical URL — sometimes with a per-install hash in the path. Register the wrong URL in Stripe and every payment event 404s — the app never learns the customer paid.

Find the actual URL in three places, in order: the admin panel Payment Gateway tab (Froiden / WorkDo / MagicAI show a read-only “Webhook URL” field — copy it verbatim, hash included), the routes, then the controller.

1. Search routes for the real Stripe POST endpoint.

   grep -rnE "stripe|webhook" routes/ | grep -viE "^\s*//|#"
   find app/ -iname "*Stripe*Controller*" -o -iname "*Webhook*Controller*"
   # Expected: the Route::post(...) Stripe POSTs to + the controller file path

   • ✅ The actual webhook URL is found (panel field, route, or controller); the hash, if any, is noted in _CUSTOMIZATIONS.md.

2. Extract the exact event list the controller handles — do not pad with Cashier’s defaults (unhandled events count against Stripe’s per-endpoint limit and add noise).

   grep -rnE "'(checkout|customer|invoice|payment_intent|charge|subscription|payout)\." \
     app/Http/Controllers/ --include="*StripeWebhookController*.php" 2>/dev/null
   # Froiden family typically: invoice.payment_succeeded / invoice.payment_failed /
   #                           payment_intent.succeeded / payment_intent.payment_failed
   # Expected: the exact event strings the controller's switch/match handles

   • ✅ The exact handled-event list is captured — no padding with unhandled defaults.

Real URLs observed in the wild:
  https://[DOMAIN]/webhook/billing-verify-webhook/{32-char hash}
  https://[DOMAIN]/webhooks/stripe
  https://[DOMAIN]/api/stripe/webhook

3. Create the account, sandbox, and keys

This all happens in the Stripe dashboard — account creation, sandbox setup, and copying keys are browser actions a person performs.

Who does this

👤 User creates/selects the Stripe account, makes the sandbox, copies the publishable/secret/signing keys (each shown once), creates the webhook endpoint, and sets the statement descriptor — all Stripe-dashboard actions an agent can’t log into.

1. Set up the account per the §1 decision. A → sign into the general account; B → Settings → Business details, update DBA/descriptor; C → create under your org (shared legal entity auto-fills KYC; skip Stripe’s “products” phase — the app creates products via API).

   • ✅ The account matches the §1 strategy.

2. Create a Sandbox named “[PROJECT] Staging” (and ideally a separate “[PROJECT] Development”), then confirm you’re in the right one via the key suffix.

   • ✅ The sandbox is confirmed via the account ID encoded in the key suffix: a sandbox acct_1TLiIg1Uhxevahdt issues sk_test_51TLiIg1Uhxevahdt… / pk_test_51TLiIg1Uhxevahdt… / rk_test_51TLiIg1Uhxevahdt… — matching suffixes = same sandbox.

3. Grab the keys and create the webhook endpoint. Copy the Publishable key (pk_test_…) and Secret key (sk_test_…, one chance to view), create the endpoint (Developers → Webhooks → Add endpoint) with the §2 URL and event list, reveal and copy the signing secret (whsec_…), then set the statement descriptor (Settings → Business details → ASCII uppercase, 5–22 chars, ≥5 letters).

   • ✅ pk_test_…, sk_test_…, and whsec_… are copied; the endpoint uses the §2 URL + events; the descriptor is set (it inherits sandbox→live and is hard to change later).

Use a Sandbox, not legacy “Test Mode”

Sandboxes replace Test Mode and are isolated per-environment (up to 5 per parent account).

One sandbox quirk catches people verifying the account ID with an MCP call:

Sandbox dual-identity trap

A sandbox has two identities: API-level it has its own acct_* ID (looks like a separate account); dashboard-level it’s a child of the parent. So an MCP call like get_stripe_account_info may return the parent’s info — both answers are “correct.” Verify you’re in the right sandbox via the account ID encoded in the key suffix (matching suffixes = same sandbox).

4. Separate the three actor keys

Separate Stripe keys by actor, not by “restricted vs unrestricted.” Each key lives in exactly one place and never cross-pollinates.

flowchart TD
    SB["Stripe sandbox"]
    SB --> APP["APP key (sk_test_*)<br/>broad scope by design"]
    SB --> AG["AGENT key (rk_test_agent_*)<br/>narrow scope"]
    SB --> DEV["DEV key (rk_test_dev_*)<br/>narrow scope"]
    APP --> APPL["Admin panel + server shared/.env<br/>(never in shell, never in MCP)"]
    AG --> AGL["Claude Code MCP config<br/>(never in app .env)"]
    DEV --> DEVL["~/.zshrc / stripe-cli<br/>(never in app .env)"]

1. Place each key in its single home.

   • App key (sk_test_*, broad) → admin panel (§5) + server shared/.env. Broad because the app makes whatever Stripe calls the vendor coded; a missing scope = runtime error blocking real checkouts. Never export it to shell or MCP.

     Why the app gets a broad sk_test_*, not a scoped rk_test_app_*

     The app’s code makes whatever Stripe calls the vendor wrote it to make — customers, invoices, subscriptions, payment intents, and so on. Scope the app’s key with a restricted rk_test_app_* and miss one permission, and the app throws a runtime error that blocks real users from checking out. A test-mode sk_test_* cannot move real money, so broad test scope is the default while the code is still being validated.

     Compliance escape-hatch: if you must scope the app key, grep the vendor source first to enumerate every $stripe->* call and grant Write on each, then re-audit after every vendor update.

   • Agent key (rk_test_agent_*, narrow) → Claude Code’s Stripe MCP config. Preset: Write on Products, Prices, Coupons, Promotion Codes, Webhook Endpoints; Read on the rest; subscriptions Read-only (human-gated).

   • Developer key (rk_test_dev_*, narrow) → ~/.zshrc for stripe-cli/curl. Same scope as agent, optionally Write on Customers/PaymentIntents for manual testing.

   • ✅ Each key sits in exactly one place; none cross-pollinate. (Skip the agent/dev keys if you only need the app key for §5 and won’t use Stripe MCP/CLI this phase — they block nothing.)

These Stripe writes pause for explicit confirmation regardless of key scope — a person confirms each before it runs.

Who does this

👤 User confirms each human-gated Stripe write — the agent prints the full payload and waits; only the user’s explicit “yes, execute” runs it.

1. Honour the human-gate table for every listed Stripe write.

   Operation	Sandbox	Live	Why
   refund.create	✅	✅	Money-out — gate always
   subscription.cancel / .update	✅	✅	Customer-facing billing change
   product.delete / price.deactivate	✅	✅	Can break live subscriptions
   webhook_endpoint.delete	✅	✅	Breaks event delivery
   customer.delete	✅	✅	Irreversible; breaks invoice lookups
   Bulk ops (>5 writes in a loop)	✅	✅	Blast radius — show the count first
   *.create (product/price/webhook/coupon)	⬜	✅	Sandbox creates are cheap to reverse

   Gate protocol: agent prints the full payload, says “Confirm with ‘yes, execute’ or I’ll abort,” waits with no timeout, runs only on yes, execute.

   • ✅ Every gated write paused for an explicit yes, execute before running.

5. Configure the gateway in the admin panel

Admin → Config → Finance (or Settings → Payments). Entering the keys is a panel action; verifying they persisted is an agent DB check.

Who does this

👤 User enters the app’s pk_test_…, sk_test_…, and whsec_… in the Finance tab and enables the gateways — a browser form only a person submits.

1. Enter the keys in the Finance tab, enabling the gateways you want and disabling the rest. Transport the values without leaking them to chat/tool logs (temp file chmod 600, or 1Password), then shred -uz the temp file after saving. If there’s no Finance tab, gateway setup is a code task — defer to the payments phase.

   • ✅ Keys saved in the panel; temp files shredded; secrets never hit chat/tool logs.

DESCRIBE the columns BEFORE you trust a verification query

Raw DB queries return NULL silently for columns that don’t exist — so NULL can mean “empty field” or “wrong column name.” Vendors ship inconsistent word orders (test_stripe_key vs stripe_test_webhook_key). Always enumerate the real names first.

1. Enumerate the real column names, then check lengths against the expected values.

   -- Step 1 — enumerate the REAL column names (don't guess)
   DESCRIBE payment_settings;   -- or settings / admin_settings / superadmin_payment_gateways
   
   -- Step 2 — SELECT only columns that exist; check lengths
   SELECT
     LENGTH(test_stripe_key)         AS pk_len,    -- expect 107
     LENGTH(test_stripe_secret)      AS sk_len,    -- expect 107
     LENGTH(stripe_test_webhook_key) AS whsec_len  -- expect 38 (word order may differ!)
   FROM payment_settings WHERE id = 1;
   -- Expected: pk_len 107, sk_len 107, whsec_len 38

   • ✅ Lengths read 107 / 107 / 38. If a length is NULL/0: either the value didn’t save (re-enter in the panel) or you queried a non-existent column (re-check DESCRIBE). Prefer Eloquent (Model::find(1)->test_stripe_secret) when the vendor ships a $fillable model — it throws on unknown attributes; raw SQL does not.

2. Run a sandbox test payment and confirm the webhook fires.

   • ✅ A test payment/subscription in sandbox mode shows 200 under Stripe dashboard → endpoint → recent deliveries.

If the save form maps camelCase→snake_case, find the mapping with grep -rn "stripe_test_webhook_key\|testStripeWebhookKey" app/Livewire/ app/Http/ and record it in _CUSTOMIZATIONS.md.

6. Set up subscription plans

BLOCKED on pricing research — do NOT invent tiers

Tier count, prices, trial length, annual discount, feature gating, and currency are business/market decisions, not config choices. They must come from upstream market research (_CUSTOMIZATIONS.md → ## Market Research Brief + Admin-Local/1-Project/0-Brand/brand-profile.json). If those artifacts are missing, mark the task [!] BLOCKED: needs market research, move on, and resume once they exist. Run a vendor-first check too — some scripts ship sane defaults in database/seeders/SubscriptionPlanSeeder.php.

The plan tiers and prices are a 👤 decision; once approved, the seeding is agent work. Match your execution to the vendor’s billing architecture (confirmed in the capabilities doc):

• Architecture A — Cashier → plans map to Stripe Products/Prices via the Billable flow; seed per the framework’s plan setup.
• Architecture B — paste-price-ID → create Stripe Products + recurring Prices, then paste each price_* ID into the admin panel / packages table.
• Architecture C — price_data at checkout → no pre-created Prices; the app builds line items at runtime from the package row.

Who does this

👤 User supplies the approved tier/price decisions (from market research) and confirms the human-gated Stripe Product/Price creates — pricing is a market call, not a config choice.

1. Confirm tier gating matches the schema before pricing anything. The vendor’s packages/plans table constrains which designs you can enforce (module bundles vs. cap columns vs. both vs. neither) — designing “10-unit limit” tiers when there’s no unit_limit column means Phase 8 rework.

   • ✅ The gating model is confirmed from the capabilities doc and matches what the schema supports.

2. For B/C, run the canonical flow — create 1 Product per paid tier + 2 recurring Prices (monthly + yearly) via Stripe MCP (human-gated write), capture the price_* IDs, then write packages rows (updateOrCreate keyed on name; modules()->sync() for the pivot). Run DB writes on staging via tinker, ideally inside a server-side script that reads the secret from the DB so the key never leaves the server.

   • ✅ Products + recurring Prices exist, price_* IDs are captured, and packages rows are written via updateOrCreate.

Server-side secret execution — the key never touches your laptop or chat

The cleanest way to run §6’s Stripe writes is to execute them from the staging server, using the secret already stored in the panel’s payment-settings table. The persisted script (committed under Admin-Local/1-Project/4-Scripts/Payments/Stripe/) must:

1. Read the Stripe test secret from the DB.
2. Instantiate \Stripe\StripeClient($secret) using the vendor’s installed SDK.
3. Verify $stripe->accounts->retrieve()->id matches the expected sandbox acct_*.
4. Run all Stripe writes via that authenticated client.
5. Capture the resulting price_* / prod_* IDs.
6. Run the packages DB writes (updateOrCreate + modules()->sync()) in the same script.

Then push, execute, and self-delete the remote copy:

scp Admin-Local/1-Project/4-Scripts/Payments/Stripe/sync-subscription-packages.php \
    [STAGING_HOST]:[DEPLOY_PATH]/sync-subscription-packages.php
ssh [STAGING_HOST] "cd [DEPLOY_PATH] && [PHP_BIN] sync-subscription-packages.php 2>&1; rm -f sync-subscription-packages.php" \
    | tee -a Admin-Local/1-Project/4-Scripts/Payments/Stripe/execution-log.raw.txt

The secret never leaves the server: no MCP key needed, no temp file on your laptop, no chat log containing the value.

varchar(191), not 255 — detect the shim, then buffer to ≤160

Laravel’s Schema::defaultStringLength(191) shim silently caps every $table->string(...) column at 191, regardless of what the migration file says. Detect whether the app uses the shim:

dep ssh staging "cd [DEPLOY_PATH] && grep -rn 'defaultStringLength' app/Providers/"
# hit → columns are 191 (or whatever value is passed)
# empty → Laravel 11+, or the shim was never needed

Confirm the live width with SHOW COLUMNS FROM packages, then target ≤ 160 chars for package_name / description. Never validate exactly at 191.

Pre-validate all tier specs before any write. The 8 checks:

1. Every package_name ≤ 160 chars
2. Every description ≤ 160 chars
3. Every stripe_monthly_plan_id / stripe_annual_plan_id matches price_*
4. Every module_id exists in modules
5. Every package_type is valid for the vendor enum
6. Every trial_days is a non-negative integer
7. Every price is non-negative (or null for Free if allowed)
8. Cross-row uniqueness — no duplicate package_name

If any check fails, print all errors and exit(1) before the first write. Add a per-row inline strlen guard inside the loop as defense in depth.

1. Verify the plans render and checkout opens with a recurring price (Playwright /superadmin/packages).

   • ✅ Correct row count, module counts, monthly+yearly prices, and Stripe IDs populated (no “Invalid Stripe plan”); the public pricing page → Subscribe opens Stripe Checkout with the correct recurring price (cancel without paying). (“Price must be recurring for mode=subscription” = a one-time price; recreate with recurring.interval.)

Gotchas to record in _CUSTOMIZATIONS.md

• Pasted price-ID typos fail only at the first real checkout (validated via prices->retrieve() then) — verify all IDs before calling the task done.
• Test → live gap — test-mode Products/Prices do not exist in live mode; recreate + re-paste in the production phase.
• modules()->sync() replaces the whole list each call — use syncWithoutDetaching() to add without dropping existing modules.
• New currency = new packages — adding AED/SAR means duplicate packages + Prices per tier; don’t edit the existing USD rows.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Strategy chosen — Stripe account strategy (A/B/C/D) with rationale + migration trigger recorded in _CUSTOMIZATIONS.md.
• 🤖 Webhook discovered — real webhook URL + exact event list discovered from the app (not assumed); endpoint created; whsec_… copied.
• 👤 Keys grabbed — sandbox confirmed via key-suffix match; statement descriptor set; app keys copied.
• 🔀 Three-actor model honoured — app key in panel/server only; agent key in MCP; dev key in shell; human-gate understood.
• 🔀 Keys verified — saved in the admin panel; columns verified via DESCRIBE-first with expected lengths (107/107/38); test payment fires the webhook with 200.
• 👤 Plans from research — created only from approved market research, or explicitly marked [!] BLOCKED; tier gating matches schema; checkout opens with a recurring price; gotchas logged.

→Next step

6 · Legal & consent