3 · Payments & billing

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 3 · Payments & billing
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/03-payments-billing/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 8
- part_number: 3 (legacy stepNumber frontmatter)
- legacy_step_number: 3
- est_time: ~2–4 hr (varies heavily by gateway count)
- description: Choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle documentation.
- tags: codecanyon, laravel, payments, billing, stripe, tax

## Execution rules (binding)
- This is Part 3 of phase 8 (~2–4 hr (varies heavily by gateway count)) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 3 · Payments & billing

## TL;DR

**Objective** — choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle docs — so billing goes from "a card can charge" to production-ready.

**Steps at a glance:**
1. **Choose a payment approach** — Pick at least one. Stripe + PayPal is the most common combination; add Tap
   for GCC markets, or LemonSqueezy to offload tax compliance entirely.
2. **Configure Stripe — CodeCanyon built-in** — No custom code — the app already has the Stripe module wired.
   Paste keys, test, and go live.
3. **Integrate Stripe — from scratch via Cashier** — Skip this if the CodeCanyon built-in above applies.
   Otherwise wire Cashier end-to-end.
4. **Set up PayPal (SHOULD — broad global coverage)** — Add PayPal for global reach and buyer trust.
5. **Set up Tap Payments for MENA** — Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets.
   Approval takes 1–3 business days.
6. **Set up LemonSqueezy — Merchant of Record** — LemonSqueezy is the legal seller: they handle all tax
   compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50).
7. **Assess the billing model** — Answer these before configuring plans anywhere — wrong answers cascade into
   every later task. Stripe Products/Prices are hard to rename after customers subscribe, and
   proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.
8. **Set up subscription plans** — Define tiers/prices/features in the admin panel where it exists, otherwise
   seed them in code — then confirm the provider-side objects exist.
9. **Set up webhooks** — Register the endpoint, store the signing secret, and confirm signature verification —
   the security-critical step.
10. **Configure tax & invoicing** — Pick one tax approach, then verify it on real test purchases.
11. **Configure dunning & failed payments** — Dunning is the retry + notification sequence when a recurring
   charge fails. Without it, MRR silently leaks.
12. **Document the payment lifecycle** — The goal: future-you (or a support agent at 2 AM) can look up any
   subscription's state and know what should happen next.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, identity/bank verification, live-money choices, passwords, 2FA, and secret values. With an authorized browser/API session, the agent drives non-secret provider-console work: create developer apps after the account exists, register webhook endpoints/events, configure approved test products/tax/dunning settings, wire env placeholders, install Cashier when needed, seed plans, and run `stripe trigger` tests. Pause only at password/secret/2FA/payment-account-verification/live-mode gates.

**Done when** at least one gateway is connected with a successful test charge and a rejected decline, plans exist in both the DB and the provider, the webhook endpoint returns 200 with verified signatures, and tax/dunning/lifecycle are configured and documented. &nbsp;·&nbsp; **⏱ ~2–4 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards/keys, 🤖 Cashier + seeders + tests).
:::

## Background

Payment configuration is two jobs: **(1)** establish or authorize the external account(s) and secret material, then **(2)** wire the non-secret provider objects, keys, webhook endpoint, and app code — and then take billing from "a card can charge" to "subscriptions, webhooks, tax, dunning, and lifecycle are production-ready."

Read `Zaj-PROJECT.md` before provider work so the environment URLs, gateway choices, billing model, non-secret provider IDs, webhook endpoint paths, and vault pointers come from one place. Update it after each provider is verified; secrets, signing secrets, and live keys stay only in the vault/provider dashboard.

:::caution[Check the admin panel first]
CodeCanyon SaaS templates almost always ship a built-in payment manager (`Settings → Payment Setting`) and a plans manager (`Settings → Plans`). Configure there when it exists — it is faster and authoritative. Only fall back to code when no admin surface exists.
:::

## Steps

### 1. Choose a payment approach

Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.

:::note[Who does this]
👤 **User** decides which gateway(s) to run — a business/scope decision based on markets and tax tolerance.
:::

<Steps>

1. **Pick the approach(es)** from the matrix.

   | Approach | Best for | Fee | Tax handling |
   |---|---|---|---|
   | **Stripe (CodeCanyon built-in)** | Apps that ship a Stripe module — just paste keys | ~3% | Yours (or Stripe Tax) |
   | **Stripe (from scratch)** | Apps with no Stripe module — via Laravel Cashier | ~3% | Yours |
   | **PayPal** | Global coverage, buyer trust | 2.9% + $0.30 | Yours |
   | **Tap Payments** | MENA region (Mada, KNET, Benefit) | 2.75% + AED 1.00 | Partial (VAT config) |
   | **LemonSqueezy (MoR)** | Solo founders wanting zero tax burden | 5% + $0.50 | They handle everything |

   ```mermaid
   flowchart TD
     Q{"App ships a Stripe module?"}
     Q -- Yes --> CC["Stripe (CodeCanyon)<br/>paste keys, no code"]
     Q -- No --> S{"Want zero tax burden?"}
     S -- Yes --> LS["LemonSqueezy (MoR)"]
     S -- No --> ST["Stripe (Cashier, from scratch)"]
     CC --> M{"Selling in GCC?"}
     ST --> M
     LS --> M
     M -- "Mada / KNET needed" --> TAP["Add Tap Payments"]
     M -- No --> PP["Add PayPal for global reach"]
   ```

   - ✅ At least one approach chosen, with regional gateways added where the market demands.

</Steps>

:::tip[Stripe does not cover MENA rails]
Card-only gateways do not support Mada or KNET. Without a regional gateway you lose **80–90%** of Saudi/Kuwaiti transactions. Add Tap if those markets matter.
:::

Whichever gateway you pick, the object-creation steps below can be automated rather than clicked.

:::note[Stripe MCP automation]
With the Stripe MCP server connected, create products/prices from your AI assistant instead of the dashboard — e.g. *"create a product 'Pro' with a $19 monthly price"*, *"list all products and prices to verify"*, or *"create a 20%-off-3-months coupon"*. Works for every gateway section below where you create or verify Stripe objects.
:::

### 2. Configure Stripe — CodeCanyon built-in (recommended where available)

No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns account login, key creation/copy, secret entry, real purchase/refund authorization, and live-key cutover. 🤖 With an authorized browser session, the agent can drive non-secret panel settings, verify product/price/webhook state, and collect evidence without reading secret values.
:::

<Steps>

1. **Toggle Stripe on and paste the test keys.** Log in as Super Admin → **Settings → Payment Setting → Stripe** → Stripe **ON** → paste the **Stripe Key** (`pk_test_…`) and **Stripe Secret Key** (`sk_test_…`), then **Save**.

   - ✅ Stripe is toggled on with the test keys saved.

2. **Run a test purchase.** Log in as a test user → Pricing → pick a plan → pay with `4242 4242 4242 4242` (CVC `123`, expiry `12/34`, ZIP `12345`). Verify the user upgrades and the transaction appears in the Stripe Dashboard.

   - ✅ The test purchase upgrades the user and shows in the Stripe Dashboard.

3. **Run a decline test.** Pay with `4000 0000 0000 0002` → error message shown, user **not** upgraded.

   - ✅ The declined card errors and does not upgrade the user.

4. **Confirm branding.** The app logo, brand colors, and business name appear during checkout and on the receipt email.

   - ✅ Checkout and the receipt are on-brand.

5. **Go live.** Swap sandbox keys for live keys (Stripe Dashboard → Live mode → Developers → API keys), make a small real purchase ($1–5), verify in the Live dashboard, then refund it.

   - ✅ A small live purchase succeeds and is refunded.

</Steps>

:::note[Webhooks often optional here]
Many CodeCanyon SaaS templates with a built-in Stripe module use a **redirect (hosted-checkout) pattern**, so webhooks are **not** required for basic one-off purchases. Confirm yours by checking whether the success path reads the return redirect vs. a webhook event. If you add subscriptions or custom post-payment logic, wire webhooks per [section 9](#9-set-up-webhooks-must).
:::

### 3. Integrate Stripe — from scratch via Cashier (only if no built-in module)

Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.

<Steps>

1. **Install Cashier.**

   ```bash
   composer require laravel/cashier
   php artisan migrate
   # Verify: php artisan migrate:status | grep cashier  → all "Ran"
   # Expected: Cashier migrations show "Ran"
   ```

   - ✅ Cashier is installed and its migrations have run.

2. **Configure env and publish config.** Confirm `STRIPE_KEY`, `STRIPE_SECRET`, `STRIPE_WEBHOOK_SECRET` are set.

   ```bash
   php artisan vendor:publish --tag="cashier-config"
   # Expected: cashier.php published to config/
   ```

   - ✅ The Stripe env vars are set and the Cashier config is published.

3. **Add the Billable trait** to `App\Models\User`.

   ```php
   use Laravel\Cashier\Billable;

   class User extends Authenticatable
   {
       use Billable;
       // ...
   }
   ```

   - ✅ `User` uses the `Billable` trait.

4. **Add the checkout route.** Add `GET /subscribe/{plan}` that maps plan slugs to Stripe price IDs and calls `->newSubscription()->checkout()`.

   - ✅ `/subscribe/{plan}` resolves plan slugs to price IDs and starts checkout.

5. **Add the billing portal.** Add `GET /billing` calling `->redirectToBillingPortal()`; enable the portal at Stripe Dashboard → Settings → Billing → Customer portal.

   - ✅ `/billing` redirects to the customer portal.

6. **Add the webhook handler.** Add `POST /stripe/webhook` → `WebhookController::handleWebhook`, exclude `stripe/*` from CSRF (**Laravel 10:** `$except` in `app/Http/Middleware/VerifyCsrfToken.php`; **Laravel 11+:** `$middleware->validateCsrfTokens(except: ['stripe/*'])` in `bootstrap/app.php`), and optionally extend Cashier's `WebhookController`.

   - ✅ The webhook route is wired and excluded from CSRF.

7. **Add subscription checks.** Use `$user->subscribed('default')`, `$user->subscribedToPrice()`, `$user->onTrial()`; add an `EnsureSubscribed` middleware for gated routes.

   - ✅ Subscription gating works via Cashier helpers + middleware.

8. **Test and commit.** Run `/subscribe/basic-monthly` with `4242 4242 4242 4242`; test the portal at `/billing`; run `stripe listen --forward-to localhost:8000/stripe/webhook`.

   ```bash
   git add composer.json composer.lock database/ app/ routes/ config/
   git commit -m "feat(payments): integrate Stripe via Laravel Cashier"
   # Expected: the Cashier integration is committed
   ```

   - ✅ Checkout, portal, and webhook forwarding work, and the integration is committed.

</Steps>

### 4. Set up PayPal (SHOULD — broad global coverage)

Add PayPal for global reach and buyer trust.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns PayPal account creation, business verification, bank/payout setup, password/2FA, and all secrets. 🤖 With an authorized browser/API session, the agent may create developer apps, register non-secret webhook endpoints/events, create sandbox test accounts, record IDs, and verify configuration. Pause for identity, banking, secret-copy, or live-money decisions.
:::

<Steps>

1. **Create and verify a business account.** Sign up at [paypal.com/business](https://www.paypal.com/business), complete the business profile (legal name, category Software/Technology, address), add a bank account, and finish identity verification until the profile shows **Verified**.

   - ✅ The PayPal business profile shows **Verified**.

2. **Create the API apps.** At [developer.paypal.com](https://developer.paypal.com/) → Apps & Credentials, create a **Sandbox** app (`[PROJECT] Development`, Merchant) and copy the Client ID (`AW…`) + Secret (`EJ…`); switch to **Live** and create `[PROJECT] Production`, copy Client ID (`AR…`) + Secret (`ES…`).

   - ✅ Sandbox and Live Client IDs + Secrets are copied.

3. **Register webhooks.** Add `https://<selected-nonproduction-domain>/paypal/webhook` (sandbox app) and `https://<production-domain>/paypal/webhook` (live app); subscribe to payment-capture and subscription events; copy each Webhook ID.

   - ✅ Both webhook endpoints are registered and the Webhook IDs copied.

4. **Create sandbox test accounts.** A Business (Seller) account ($5000) and a Personal (Buyer) account ($1000).

   - ✅ Sandbox seller + buyer accounts exist.

5. **Create subscription products** (if recurring) — Products & Subscriptions → create a Service/SaaS product, add Monthly and Yearly billing plans, note the Plan IDs (`P-…`).

   - ✅ Subscription products and Plan IDs exist (if recurring).

6. **Wire env.** Add placeholders to `.env.example` (safe to commit) and fill real values in `.env`.

   ```bash
   ## === PAYPAL ===
   PAYPAL_MODE=sandbox
   PAYPAL_SANDBOX_CLIENT_ID=
   PAYPAL_SANDBOX_CLIENT_SECRET=
   PAYPAL_LIVE_CLIENT_ID=
   PAYPAL_LIVE_CLIENT_SECRET=
   PAYPAL_SANDBOX_WEBHOOK_ID=
   PAYPAL_LIVE_WEBHOOK_ID=
   # Expected: placeholders in .env.example; real values in .env (uncommitted)
   ```

   - ✅ The PayPal env block is wired with placeholders committed, real values local.

</Steps>

### 5. Set up Tap Payments for MENA

Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes **1–3 business days**.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns signup, verification documents, banking, passwords/2FA, and legal/tax approvals. 🤖 With an authorized browser/API session, the agent may navigate Tap settings, enable approved non-secret payment methods, register webhook endpoints/events, record IDs, and verify configuration. Pause for document upload, secret-copy, payout, or live-money decisions.
:::

<Steps>

1. **Sign up and submit for verification.** At [tap.company](https://www.tap.company/) → select country → enter business info (legal name, trade-license number, category) → upload documents (Trade License/CR, Owner ID, bank statement) → submit.

   - ✅ The Tap account is submitted for verification.

2. **Copy the API keys** after approval. [dashboard.tap.company](https://dashboard.tap.company/) → Developers → API Keys; copy test (`sk_test_…`, `pk_test_…`) and live (`sk_live_…`, `pk_live_…`).

   - ✅ Test and live Tap keys are copied.

3. **Enable payment methods** per target country. Settings → Payment Methods.

   | Country | Essential methods |
   |---|---|
   | Saudi Arabia | Mada (90%+ usage), Visa/MC, Apple Pay |
   | Kuwait | KNET (80%+ usage), Visa/MC |
   | Bahrain | Benefit (70%+ usage), Visa/MC |
   | UAE | Visa/MC, Apple Pay |

   - ✅ Country-essential methods are enabled.

4. **Register webhooks.** Developers → Webhooks → `https://<domain>/tap/webhook`; subscribe to `CHARGE.CAPTURED`, `CHARGE.FAILED`, `CHARGE.REFUNDED`, `AUTHORIZE.CAPTURED`, `AUTHORIZE.VOIDED`; copy the secret.

   - ✅ The Tap webhook is registered with its secret copied.

5. **Configure VAT.** Settings → Tax Settings: SA 15%, UAE 5%, BH 10%, KW 0%, QA 0%, OM 5%.

   - ✅ VAT rates are set per country.

6. **Wire env.**

   ```bash
   ## === TAP PAYMENTS ===
   TAP_SECRET_KEY=
   TAP_PUBLISHABLE_KEY=
   TAP_WEBHOOK_SECRET=
   TAP_CURRENCY=SAR
   # Expected: the Tap env block is present with placeholders
   ```

   - ✅ The Tap env block is wired.

</Steps>

### 6. Set up LemonSqueezy — Merchant of Record (ALTERNATIVE)

LemonSqueezy is the **legal seller**: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50). Best for solo founders selling globally; **not** ideal for low-margin products, enterprise buyers, or MENA (no Mada/KNET).

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns account creation, payout/identity verification, password/2FA, secret values, and pricing/business approval. 🤖 With an authorized browser/API session, the agent may configure store metadata, create approved products/variants, register webhook endpoints/events, record IDs, and verify test checkout setup. Pause for secret-copy, payout, identity, or live-money decisions.
:::

<Steps>

1. **Create the account.** [lemonsqueezy.com](https://lemonsqueezy.com/) → Get Started Free → onboarding (Software/SaaS, revenue estimate, location) → connect payout (Stripe Connect or PayPal) → verify identity.

   - ✅ The LemonSqueezy account is created with payout connected.

2. **Configure the store.** Settings → General: Store Name, Support Email, Logo, Currency. Optional: add a custom checkout domain.

   - ✅ Store details are set.

3. **Create products.** Store → Products → New Product, Pricing Type **Subscription**, set Monthly + Yearly, add variants (Basic/Pro/Business), note Product ID + Variant IDs.

   - ✅ Subscription products with Variant IDs exist.

4. **Create the API key.** Settings → API → create (`[PROJECT] Production`, Read & Write); copy the key (`lmn_…`, shown once); note the Store ID.

   - ✅ The API key (`lmn_…`) and Store ID are stored.

5. **Register webhooks.** Settings → Webhooks → `https://<domain>/lemonsqueezy/webhook`; subscribe to `order_created`, `order_refunded`, `subscription_created`, `subscription_updated`, `subscription_cancelled`, `subscription_resumed`, `subscription_expired`, `subscription_payment_failed`; copy the signing secret.

   - ✅ The webhook is registered with its signing secret copied.

6. **Pick the integration method** by effort — simple checkout links (low), Lemon.js overlay (medium), or a Laravel package (high/full API).

   - ✅ An integration method is chosen.

7. **Wire env.**

   ```bash
   ## === LEMONSQUEEZY ===
   LEMONSQUEEZY_API_KEY=
   LEMONSQUEEZY_STORE_ID=
   LEMONSQUEEZY_SIGNING_SECRET=
   LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID=
   # Expected: the LemonSqueezy env block is present with placeholders
   ```

   - ✅ The LemonSqueezy env block is wired.

8. **Test the checkout.** Open the checkout link → complete a test purchase → verify the webhook fires and the user gets access.

   - ✅ A test purchase fires the webhook and grants access.

</Steps>

:::danger[Secret handling — the two highest-value keys]
Billing works with `STRIPE_SECRET` (`sk_live_*`/`sk_test_*`) and `STRIPE_WEBHOOK_SECRET` (`whsec_*`). A leaked `sk_live_*` lets an attacker issue refunds, create charges, and read customer data. Never echo the key, never `grep STRIPE .env` into chat, never paste it back "to check it". For a presence check: `grep -qE '^STRIPE_SECRET=sk_(test|live)_' .env && echo "✅ Stripe key present"` — staging should use `sk_test_`, production `sk_live_`. If a key ever lands in chat or `git log`, rotate immediately (Stripe Dashboard → Developers → API keys → Roll) — even "just the test key".
:::

### 7. Assess the billing model (MUST)

Answer these **before** configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.

:::note[Who does this]
👤 **User** answers the billing-model questions — these are product/pricing decisions, not implementation.
:::

<Steps>

1. **Fill the billing-model decision table.**

   | Question | Your answer |
   |---|---|
   | Billing model | one-time / recurring / usage-based / hybrid |
   | Number of tiers | single / 2–3 tiers / 4+ tiers |
   | Intervals offered | monthly / monthly + yearly / + lifetime |
   | Free tier? | feature-limited / usage-limited / none |
   | Trial period | none / N days no card / N days card required |
   | Annual discount | none / X% off / X months free |
   | Currency | single / multi-currency |
   | Tax handling | inclusive / exclusive / auto (Stripe Tax) |
   | Proration on upgrade | immediate charge / next cycle / none |
   | Cancellation | at period end / immediate + refund / immediate no refund |

   - ✅ You can read this table aloud to a non-technical person and they understand the customer experience.

</Steps>

### 8. Set up subscription plans (MUST)

Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.

<Steps>

1. **Check the admin panel first** — look for `Settings → Plans`/`Pricing`, `Subscriptions → Plans`, `Admin → Membership Plans`, or `Finance → Subscription Plans`. If found, configure tiers/prices/features/trial/annual toggle in the UI (~5 min) and skip to substep 3.

   - ✅ Plans are configured in the admin UI (if it exists).

2. **Code fallback** — if no admin UI, seed via `database/seeders/PlansSeeder.php` using Cashier. Each plan needs `name`, `stripe_id` (the Price ID), `stripe_plan`, `billing_interval`, and a `features` JSON.

   :::caution[Back up the plans table before re-seeding a live DB]
   A seeder that `updateOrCreate`s (or worse, truncates and re-inserts) plan rows can **overwrite the `stripe_id` price mappings** that existing subscribers are billed against — silently breaking their renewals. Before running a plans seeder on **any** environment that already has subscriptions, dump the table so you can roll back. On Herd Pro / MariaDB the dump tool is `mariadb-dump` (the renamed `mysqldump`):

   ```bash
   # Back up first — rollback net before any re-seed touches existing plan rows
   mariadb-dump -u <user> -p <db> plans > /tmp/plans-backup-$(date +%F).sql   # or mysqldump on MySQL hosts
   php artisan make:seeder PlansSeeder
   php artisan db:seed --class=PlansSeeder
   # Expected: the plan rows are seeded with non-null stripe_id values; the backup SQL exists as a rollback
   ```

   Prefer an **idempotent** `updateOrCreate` keyed on a stable column (plan slug) over truncate-and-insert, so a re-run never duplicates or re-IDs rows.
   :::

   - ✅ Plans are seeded with Price IDs and a features JSON, and a pre-seed table backup exists if the DB already had subscriptions.

3. **Confirm provider-side Products/Prices (critical).** The Products + Prices must **also** exist in Stripe/Paddle/LemonSqueezy. Your local records only store the `price_id`; they don't create the provider object. A plan that exists in your DB but not in the gateway will **500 at checkout**.

   - ✅ Each DB plan maps to a real provider-side Product/Price.

4. **Map feature gating.** Map each plan to the features it unlocks (character counts, seats, API calls, branding removal). Most apps store this as JSON on the plan row — document the schema in `Admin-Local/1-Project/1-Info/billing-features.md`.

   - ✅ The admin lists all tiers with correct prices; `\App\Models\Plan::all()->pluck('stripe_id')` returns non-null Price IDs; `/pricing` renders every tier correctly.

</Steps>

### 9. Set up webhooks (MUST)

Register the endpoint, store the signing secret, and confirm signature verification — the security-critical step.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns the payment-provider account, login, secret values, and any live-money decision. 🤖 With an authorized browser/API session, the agent may register the endpoint and event subscriptions, then confirms the verification code and runs the `stripe trigger` tests. If the dashboard asks for a password, 2FA, live-mode confirmation, or payment-account verification, pause for the user.
:::

<Steps>

1. **Check the admin panel.** Many apps expose `Settings → Webhooks` or `Integrations → Stripe` with the URL + secret pre-wired. If present, configure there.

   - ✅ The admin webhook surface is used if it exists.

2. **Register the endpoint.** Stripe Dashboard → Developers → Webhooks → Add endpoint → `https://<domain>/stripe/webhook` (confirm with `php artisan route:list | grep stripe`). Subscribe to the minimum set:
   - `checkout.session.completed`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `customer.subscription.trial_will_end`

   - ✅ The endpoint is registered and subscribed to the minimum event set.

3. **Store the signing secret.** Fill the `STRIPE_WEBHOOK_SECRET=whsec_…` placeholder in the production `.env` via your secrets manager.

   - ✅ The signing secret is stored via the secrets manager.

4. **Confirm signature verification (critical security step).** Cashier does this automatically via its `WebhookController`. A custom handler **must** call:

   ```php
   \Stripe\Stripe::setApiKey(config('cashier.secret'));
   $event = \Stripe\Webhook::constructEvent(
       $request->getContent(),
       $request->header('Stripe-Signature'),
       config('cashier.webhook.secret')
   );
   ```

   A handler that trusts unverified POST bodies lets any attacker upgrade themselves to enterprise for free.

   - ✅ Signature verification runs on every webhook (Cashier or `constructEvent`).

5. **Test locally.**

   ```bash
   stripe listen --forward-to http://<project>.test/stripe/webhook
   stripe trigger checkout.session.completed
   # Expected: handler runs, signature verifies, subscription row created/updated
   ```

   - ✅ The triggered event runs the handler, verifies the signature, and updates a row.

6. **Add alerting.** Webhook failures are silent (users pay, your DB doesn't know). Add a Sentry alert for signature failures and 5xx from `/stripe/webhook` (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/) for Sentry setup).

   - ✅ The Stripe endpoint shows "200 OK" for recent deliveries; `stripe trigger invoice.payment_failed` flips a row to `past_due`; Sentry receives a test error on a deliberately invalid signature.

</Steps>

### 10. Configure tax & invoicing (SHOULD)

Pick one tax approach, then verify it on real test purchases.

<Steps>

1. **Pick a tax approach.**

   | Approach | Cost | Coverage | Best for |
   |---|---|---|---|
   | **Stripe Tax** (auto) | 0.5%/txn | 50+ countries, auto VAT/GST/sales tax | Any SaaS selling internationally |
   | **Paddle as MoR** | ~5% + $0.50 | All countries, remits for you | Indie teams wanting zero tax burden (replaces Stripe) |
   | **Manual tax tables** | Free | Only what you configure | Single-country, single-rate |
   | **No tax collection** | Free | N/A | Pre-revenue MVPs (may be illegal past thresholds) |

   - ✅ A tax approach is chosen.

2. **Enable Stripe Tax (recommended default).** Enable at Dashboard → Tax → Settings, then in the Cashier checkout:

   ```php
   $user->newSubscription('default', $priceId)
       ->checkout([
           'automatic_tax' => ['enabled' => true],
           'customer_update' => ['address' => 'auto'],
       ]);
   ```

   For EU B2B, collect VAT IDs so Stripe applies the reverse charge — add `tax_id_collection: ['enabled' => true]` (Cashier 14+). For invoices: Stripe-hosted PDFs come free via `$user->invoice()->download()`; for a branded template, `php artisan vendor:publish --tag=cashier-views` and edit `receipt.blade.php`; if you legally need sequential gapless numbering, generate it on the `invoice.payment_succeeded` webhook.

   - ✅ A VAT-registered EU test purchase shows 0% VAT with a "reverse charge" note; a US purchase shows correct state tax; the invoice PDF downloads with your branding.

</Steps>

### 11. Configure dunning & failed payments (SHOULD)

Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.

<Steps>

1. **Enable Smart Retries.** Stripe Dashboard → Settings → Billing → Subscriptions and emails → "Manage failed payments" → enable **Smart Retries**; set the max retry period (3 weeks typical, 7 days minimum).

   - ✅ Smart Retries are enabled with a retry window set.

2. **Set a grace period** before cancellation.

   | Grace period | Use case |
   |---|---|
   | 3 days | High-churn, low-ARPU consumer |
   | 7 days | Standard SaaS default |
   | 14 days | B2B, ARR > $500 |

   - ✅ A grace period is set for the product's profile.

3. **Enable email notifications.** Stripe's branded dunning emails (Dashboard → Settings → Emails) **or** handle in Laravel from the `invoice.payment_failed` webhook: `$user->notify(new PaymentFailedNotification($invoice));`

   - ✅ Failed-payment emails are wired (Stripe or Laravel).

4. **Document the post-failure behavior.**
   - **Soft downgrade** (recommended) — subscription → `past_due`, feature gates check `$user->subscribed() && !$user->subscription()->pastDue()`, user sees a billing banner + limited access. Easier recovery.
   - **Hard cancel** — subscription deleted, user drops to free. Cleaner, harder to win back.

   - ✅ The chosen post-failure behavior is documented.

5. **Test the failed-payment path.** In test mode use card `4000 0000 0000 0341` (attaches but fails on charge) to walk failed webhook → `past_due` → dunning emails → grace period → cancellation.

   - ✅ A test-mode failed renewal triggers `invoice.payment_failed`; the user gets the email; after the grace period the DB status flips to `canceled` and access revokes.

</Steps>

### 12. Document the payment lifecycle (SHOULD)

The goal: future-you (or a support agent at 2 AM) can look up any subscription's state and know what should happen next.

<Steps>

1. **Write the lifecycle doc.** Create `Admin-Local/1-Project/1-Info/billing-lifecycle.md` with the state machine, a test matrix, alert rules, and a runbook.

   ```mermaid
   stateDiagram-v2
     [*] --> trialing: checkout (trial_days > 0)
     [*] --> active: checkout (trial_days == 0)
     trialing --> active: trial end + payment success
     trialing --> canceled: trial end + no card
     active --> past_due: invoice.payment_failed
     past_due --> active: retry success
     past_due --> canceled: grace expired
     active --> canceled: user cancels → period end
     canceled --> active: user resubscribes
   ```

   - ✅ The lifecycle doc exists with the state diagram.

2. **Record the test matrix** — for each transition, how to reproduce it in Stripe test mode.

   | Transition | Reproduce (test mode) |
   |---|---|
   | new → trialing | Checkout with `trial_days=7`, card `4242…4242` |
   | trialing → active | `stripe trigger invoice.payment_succeeded` |
   | active → past_due | Card `4000…0341` on renewal, then `stripe trigger invoice.payment_failed` |
   | past_due → canceled | Wait out grace, or `stripe trigger customer.subscription.deleted` |
   | canceled → active | Same user resubscribes |

   - ✅ Every test-matrix transition has been executed once.

3. **Add the Sentry alert rules** (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/)) — a `past_due` spike (>5 in 1 hour = payment processing broke); any `SignatureVerificationException` (someone probing, or your secret rotated); a churn threshold (>3% cancel in 24 hours = check for an outage or bad deploy). Append a "what to do when" runbook for the common support cases ("I paid but can't access", refund requests, stuck renewals).

   - ✅ The 3 Sentry rules are active and one has been test-fired.

</Steps>

## Checklist

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

- [ ] **🔀 At least one gateway connected** — test payment succeeds and a declined card is rejected.
- [ ] **👤 Billing model decision record** filled in.
- [ ] **🔀 Plans exist in both the DB and the provider dashboard** — `/pricing` renders correctly.
- [ ] **🔀 Webhook endpoint returns 200** — signature verification confirmed.
- [ ] **🔀 Tax approach chosen** — Stripe Tax (if applicable) verified on EU + US test purchases.
- [ ] **🔀 Dunning configured + tested** — post-failure behavior documented.
- [ ] **🤖 `billing-lifecycle.md` written** — state machine, test matrix, and alert rules.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the billing model, active gateways, non-secret provider/product/price IDs, webhook endpoint paths, mode per environment, and vault item pointers.

:::next[Next step]
[Email infrastructure](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/04-email/)
:::

# 3 · Payments & billing

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/03-payments-billing/

## TL;DR

**Objective** — choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle docs — so billing goes from "a card can charge" to production-ready.

**Steps at a glance:**
1. **Choose a payment approach** — Pick at least one. Stripe + PayPal is the most common combination; add Tap
   for GCC markets, or LemonSqueezy to offload tax compliance entirely.
2. **Configure Stripe — CodeCanyon built-in** — No custom code — the app already has the Stripe module wired.
   Paste keys, test, and go live.
3. **Integrate Stripe — from scratch via Cashier** — Skip this if the CodeCanyon built-in above applies.
   Otherwise wire Cashier end-to-end.
4. **Set up PayPal (SHOULD — broad global coverage)** — Add PayPal for global reach and buyer trust.
5. **Set up Tap Payments for MENA** — Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets.
   Approval takes 1–3 business days.
6. **Set up LemonSqueezy — Merchant of Record** — LemonSqueezy is the legal seller: they handle all tax
   compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50).
7. **Assess the billing model** — Answer these before configuring plans anywhere — wrong answers cascade into
   every later task. Stripe Products/Prices are hard to rename after customers subscribe, and
   proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.
8. **Set up subscription plans** — Define tiers/prices/features in the admin panel where it exists, otherwise
   seed them in code — then confirm the provider-side objects exist.
9. **Set up webhooks** — Register the endpoint, store the signing secret, and confirm signature verification —
   the security-critical step.
10. **Configure tax & invoicing** — Pick one tax approach, then verify it on real test purchases.
11. **Configure dunning & failed payments** — Dunning is the retry + notification sequence when a recurring
   charge fails. Without it, MRR silently leaks.
12. **Document the payment lifecycle** — The goal: future-you (or a support agent at 2 AM) can look up any
   subscription's state and know what should happen next.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, identity/bank verification, live-money choices, passwords, 2FA, and secret values. With an authorized browser/API session, the agent drives non-secret provider-console work: create developer apps after the account exists, register webhook endpoints/events, configure approved test products/tax/dunning settings, wire env placeholders, install Cashier when needed, seed plans, and run `stripe trigger` tests. Pause only at password/secret/2FA/payment-account-verification/live-mode gates.

**Done when** at least one gateway is connected with a successful test charge and a rejected decline, plans exist in both the DB and the provider, the webhook endpoint returns 200 with verified signatures, and tax/dunning/lifecycle are configured and documented. &nbsp;·&nbsp; **⏱ ~2–4 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards/keys, 🤖 Cashier + seeders + tests).
:::

## Background

Payment configuration is two jobs: **(1)** establish or authorize the external account(s) and secret material, then **(2)** wire the non-secret provider objects, keys, webhook endpoint, and app code — and then take billing from "a card can charge" to "subscriptions, webhooks, tax, dunning, and lifecycle are production-ready."

Read `Zaj-PROJECT.md` before provider work so the environment URLs, gateway choices, billing model, non-secret provider IDs, webhook endpoint paths, and vault pointers come from one place. Update it after each provider is verified; secrets, signing secrets, and live keys stay only in the vault/provider dashboard.

:::caution[Check the admin panel first]
CodeCanyon SaaS templates almost always ship a built-in payment manager (`Settings → Payment Setting`) and a plans manager (`Settings → Plans`). Configure there when it exists — it is faster and authoritative. Only fall back to code when no admin surface exists.
:::

## Steps

### 1. Choose a payment approach

Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.

:::note[Who does this]
👤 **User** decides which gateway(s) to run — a business/scope decision based on markets and tax tolerance.
:::

<Steps>

1. **Pick the approach(es)** from the matrix.

   | Approach | Best for | Fee | Tax handling |
   |---|---|---|---|
   | **Stripe (CodeCanyon built-in)** | Apps that ship a Stripe module — just paste keys | ~3% | Yours (or Stripe Tax) |
   | **Stripe (from scratch)** | Apps with no Stripe module — via Laravel Cashier | ~3% | Yours |
   | **PayPal** | Global coverage, buyer trust | 2.9% + $0.30 | Yours |
   | **Tap Payments** | MENA region (Mada, KNET, Benefit) | 2.75% + AED 1.00 | Partial (VAT config) |
   | **LemonSqueezy (MoR)** | Solo founders wanting zero tax burden | 5% + $0.50 | They handle everything |

   ```mermaid
   flowchart TD
     Q{"App ships a Stripe module?"}
     Q -- Yes --> CC["Stripe (CodeCanyon)<br/>paste keys, no code"]
     Q -- No --> S{"Want zero tax burden?"}
     S -- Yes --> LS["LemonSqueezy (MoR)"]
     S -- No --> ST["Stripe (Cashier, from scratch)"]
     CC --> M{"Selling in GCC?"}
     ST --> M
     LS --> M
     M -- "Mada / KNET needed" --> TAP["Add Tap Payments"]
     M -- No --> PP["Add PayPal for global reach"]
   ```

   - ✅ At least one approach chosen, with regional gateways added where the market demands.

</Steps>

:::tip[Stripe does not cover MENA rails]
Card-only gateways do not support Mada or KNET. Without a regional gateway you lose **80–90%** of Saudi/Kuwaiti transactions. Add Tap if those markets matter.
:::

Whichever gateway you pick, the object-creation steps below can be automated rather than clicked.

:::note[Stripe MCP automation]
With the Stripe MCP server connected, create products/prices from your AI assistant instead of the dashboard — e.g. *"create a product 'Pro' with a $19 monthly price"*, *"list all products and prices to verify"*, or *"create a 20%-off-3-months coupon"*. Works for every gateway section below where you create or verify Stripe objects.
:::

### 2. Configure Stripe — CodeCanyon built-in (recommended where available)

No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns account login, key creation/copy, secret entry, real purchase/refund authorization, and live-key cutover. 🤖 With an authorized browser session, the agent can drive non-secret panel settings, verify product/price/webhook state, and collect evidence without reading secret values.
:::

<Steps>

1. **Toggle Stripe on and paste the test keys.** Log in as Super Admin → **Settings → Payment Setting → Stripe** → Stripe **ON** → paste the **Stripe Key** (`pk_test_…`) and **Stripe Secret Key** (`sk_test_…`), then **Save**.

   - ✅ Stripe is toggled on with the test keys saved.

2. **Run a test purchase.** Log in as a test user → Pricing → pick a plan → pay with `4242 4242 4242 4242` (CVC `123`, expiry `12/34`, ZIP `12345`). Verify the user upgrades and the transaction appears in the Stripe Dashboard.

   - ✅ The test purchase upgrades the user and shows in the Stripe Dashboard.

3. **Run a decline test.** Pay with `4000 0000 0000 0002` → error message shown, user **not** upgraded.

   - ✅ The declined card errors and does not upgrade the user.

4. **Confirm branding.** The app logo, brand colors, and business name appear during checkout and on the receipt email.

   - ✅ Checkout and the receipt are on-brand.

5. **Go live.** Swap sandbox keys for live keys (Stripe Dashboard → Live mode → Developers → API keys), make a small real purchase ($1–5), verify in the Live dashboard, then refund it.

   - ✅ A small live purchase succeeds and is refunded.

</Steps>

:::note[Webhooks often optional here]
Many CodeCanyon SaaS templates with a built-in Stripe module use a **redirect (hosted-checkout) pattern**, so webhooks are **not** required for basic one-off purchases. Confirm yours by checking whether the success path reads the return redirect vs. a webhook event. If you add subscriptions or custom post-payment logic, wire webhooks per [section 9](#9-set-up-webhooks-must).
:::

### 3. Integrate Stripe — from scratch via Cashier (only if no built-in module)

Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.

<Steps>

1. **Install Cashier.**

   ```bash
   composer require laravel/cashier
   php artisan migrate
   # Verify: php artisan migrate:status | grep cashier  → all "Ran"
   # Expected: Cashier migrations show "Ran"
   ```

   - ✅ Cashier is installed and its migrations have run.

2. **Configure env and publish config.** Confirm `STRIPE_KEY`, `STRIPE_SECRET`, `STRIPE_WEBHOOK_SECRET` are set.

   ```bash
   php artisan vendor:publish --tag="cashier-config"
   # Expected: cashier.php published to config/
   ```

   - ✅ The Stripe env vars are set and the Cashier config is published.

3. **Add the Billable trait** to `App\Models\User`.

   ```php
   use Laravel\Cashier\Billable;

   class User extends Authenticatable
   {
       use Billable;
       // ...
   }
   ```

   - ✅ `User` uses the `Billable` trait.

4. **Add the checkout route.** Add `GET /subscribe/{plan}` that maps plan slugs to Stripe price IDs and calls `->newSubscription()->checkout()`.

   - ✅ `/subscribe/{plan}` resolves plan slugs to price IDs and starts checkout.

5. **Add the billing portal.** Add `GET /billing` calling `->redirectToBillingPortal()`; enable the portal at Stripe Dashboard → Settings → Billing → Customer portal.

   - ✅ `/billing` redirects to the customer portal.

6. **Add the webhook handler.** Add `POST /stripe/webhook` → `WebhookController::handleWebhook`, exclude `stripe/*` from CSRF (**Laravel 10:** `$except` in `app/Http/Middleware/VerifyCsrfToken.php`; **Laravel 11+:** `$middleware->validateCsrfTokens(except: ['stripe/*'])` in `bootstrap/app.php`), and optionally extend Cashier's `WebhookController`.

   - ✅ The webhook route is wired and excluded from CSRF.

7. **Add subscription checks.** Use `$user->subscribed('default')`, `$user->subscribedToPrice()`, `$user->onTrial()`; add an `EnsureSubscribed` middleware for gated routes.

   - ✅ Subscription gating works via Cashier helpers + middleware.

8. **Test and commit.** Run `/subscribe/basic-monthly` with `4242 4242 4242 4242`; test the portal at `/billing`; run `stripe listen --forward-to localhost:8000/stripe/webhook`.

   ```bash
   git add composer.json composer.lock database/ app/ routes/ config/
   git commit -m "feat(payments): integrate Stripe via Laravel Cashier"
   # Expected: the Cashier integration is committed
   ```

   - ✅ Checkout, portal, and webhook forwarding work, and the integration is committed.

</Steps>

### 4. Set up PayPal (SHOULD — broad global coverage)

Add PayPal for global reach and buyer trust.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns PayPal account creation, business verification, bank/payout setup, password/2FA, and all secrets. 🤖 With an authorized browser/API session, the agent may create developer apps, register non-secret webhook endpoints/events, create sandbox test accounts, record IDs, and verify configuration. Pause for identity, banking, secret-copy, or live-money decisions.
:::

<Steps>

1. **Create and verify a business account.** Sign up at [paypal.com/business](https://www.paypal.com/business), complete the business profile (legal name, category Software/Technology, address), add a bank account, and finish identity verification until the profile shows **Verified**.

   - ✅ The PayPal business profile shows **Verified**.

2. **Create the API apps.** At [developer.paypal.com](https://developer.paypal.com/) → Apps & Credentials, create a **Sandbox** app (`[PROJECT] Development`, Merchant) and copy the Client ID (`AW…`) + Secret (`EJ…`); switch to **Live** and create `[PROJECT] Production`, copy Client ID (`AR…`) + Secret (`ES…`).

   - ✅ Sandbox and Live Client IDs + Secrets are copied.

3. **Register webhooks.** Add `https://<selected-nonproduction-domain>/paypal/webhook` (sandbox app) and `https://<production-domain>/paypal/webhook` (live app); subscribe to payment-capture and subscription events; copy each Webhook ID.

   - ✅ Both webhook endpoints are registered and the Webhook IDs copied.

4. **Create sandbox test accounts.** A Business (Seller) account ($5000) and a Personal (Buyer) account ($1000).

   - ✅ Sandbox seller + buyer accounts exist.

5. **Create subscription products** (if recurring) — Products & Subscriptions → create a Service/SaaS product, add Monthly and Yearly billing plans, note the Plan IDs (`P-…`).

   - ✅ Subscription products and Plan IDs exist (if recurring).

6. **Wire env.** Add placeholders to `.env.example` (safe to commit) and fill real values in `.env`.

   ```bash
   ## === PAYPAL ===
   PAYPAL_MODE=sandbox
   PAYPAL_SANDBOX_CLIENT_ID=
   PAYPAL_SANDBOX_CLIENT_SECRET=
   PAYPAL_LIVE_CLIENT_ID=
   PAYPAL_LIVE_CLIENT_SECRET=
   PAYPAL_SANDBOX_WEBHOOK_ID=
   PAYPAL_LIVE_WEBHOOK_ID=
   # Expected: placeholders in .env.example; real values in .env (uncommitted)
   ```

   - ✅ The PayPal env block is wired with placeholders committed, real values local.

</Steps>

### 5. Set up Tap Payments for MENA

Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes **1–3 business days**.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns signup, verification documents, banking, passwords/2FA, and legal/tax approvals. 🤖 With an authorized browser/API session, the agent may navigate Tap settings, enable approved non-secret payment methods, register webhook endpoints/events, record IDs, and verify configuration. Pause for document upload, secret-copy, payout, or live-money decisions.
:::

<Steps>

1. **Sign up and submit for verification.** At [tap.company](https://www.tap.company/) → select country → enter business info (legal name, trade-license number, category) → upload documents (Trade License/CR, Owner ID, bank statement) → submit.

   - ✅ The Tap account is submitted for verification.

2. **Copy the API keys** after approval. [dashboard.tap.company](https://dashboard.tap.company/) → Developers → API Keys; copy test (`sk_test_…`, `pk_test_…`) and live (`sk_live_…`, `pk_live_…`).

   - ✅ Test and live Tap keys are copied.

3. **Enable payment methods** per target country. Settings → Payment Methods.

   | Country | Essential methods |
   |---|---|
   | Saudi Arabia | Mada (90%+ usage), Visa/MC, Apple Pay |
   | Kuwait | KNET (80%+ usage), Visa/MC |
   | Bahrain | Benefit (70%+ usage), Visa/MC |
   | UAE | Visa/MC, Apple Pay |

   - ✅ Country-essential methods are enabled.

4. **Register webhooks.** Developers → Webhooks → `https://<domain>/tap/webhook`; subscribe to `CHARGE.CAPTURED`, `CHARGE.FAILED`, `CHARGE.REFUNDED`, `AUTHORIZE.CAPTURED`, `AUTHORIZE.VOIDED`; copy the secret.

   - ✅ The Tap webhook is registered with its secret copied.

5. **Configure VAT.** Settings → Tax Settings: SA 15%, UAE 5%, BH 10%, KW 0%, QA 0%, OM 5%.

   - ✅ VAT rates are set per country.

6. **Wire env.**

   ```bash
   ## === TAP PAYMENTS ===
   TAP_SECRET_KEY=
   TAP_PUBLISHABLE_KEY=
   TAP_WEBHOOK_SECRET=
   TAP_CURRENCY=SAR
   # Expected: the Tap env block is present with placeholders
   ```

   - ✅ The Tap env block is wired.

</Steps>

### 6. Set up LemonSqueezy — Merchant of Record (ALTERNATIVE)

LemonSqueezy is the **legal seller**: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50). Best for solo founders selling globally; **not** ideal for low-margin products, enterprise buyers, or MENA (no Mada/KNET).

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns account creation, payout/identity verification, password/2FA, secret values, and pricing/business approval. 🤖 With an authorized browser/API session, the agent may configure store metadata, create approved products/variants, register webhook endpoints/events, record IDs, and verify test checkout setup. Pause for secret-copy, payout, identity, or live-money decisions.
:::

<Steps>

1. **Create the account.** [lemonsqueezy.com](https://lemonsqueezy.com/) → Get Started Free → onboarding (Software/SaaS, revenue estimate, location) → connect payout (Stripe Connect or PayPal) → verify identity.

   - ✅ The LemonSqueezy account is created with payout connected.

2. **Configure the store.** Settings → General: Store Name, Support Email, Logo, Currency. Optional: add a custom checkout domain.

   - ✅ Store details are set.

3. **Create products.** Store → Products → New Product, Pricing Type **Subscription**, set Monthly + Yearly, add variants (Basic/Pro/Business), note Product ID + Variant IDs.

   - ✅ Subscription products with Variant IDs exist.

4. **Create the API key.** Settings → API → create (`[PROJECT] Production`, Read & Write); copy the key (`lmn_…`, shown once); note the Store ID.

   - ✅ The API key (`lmn_…`) and Store ID are stored.

5. **Register webhooks.** Settings → Webhooks → `https://<domain>/lemonsqueezy/webhook`; subscribe to `order_created`, `order_refunded`, `subscription_created`, `subscription_updated`, `subscription_cancelled`, `subscription_resumed`, `subscription_expired`, `subscription_payment_failed`; copy the signing secret.

   - ✅ The webhook is registered with its signing secret copied.

6. **Pick the integration method** by effort — simple checkout links (low), Lemon.js overlay (medium), or a Laravel package (high/full API).

   - ✅ An integration method is chosen.

7. **Wire env.**

   ```bash
   ## === LEMONSQUEEZY ===
   LEMONSQUEEZY_API_KEY=
   LEMONSQUEEZY_STORE_ID=
   LEMONSQUEEZY_SIGNING_SECRET=
   LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID=
   # Expected: the LemonSqueezy env block is present with placeholders
   ```

   - ✅ The LemonSqueezy env block is wired.

8. **Test the checkout.** Open the checkout link → complete a test purchase → verify the webhook fires and the user gets access.

   - ✅ A test purchase fires the webhook and grants access.

</Steps>

:::danger[Secret handling — the two highest-value keys]
Billing works with `STRIPE_SECRET` (`sk_live_*`/`sk_test_*`) and `STRIPE_WEBHOOK_SECRET` (`whsec_*`). A leaked `sk_live_*` lets an attacker issue refunds, create charges, and read customer data. Never echo the key, never `grep STRIPE .env` into chat, never paste it back "to check it". For a presence check: `grep -qE '^STRIPE_SECRET=sk_(test|live)_' .env && echo "✅ Stripe key present"` — staging should use `sk_test_`, production `sk_live_`. If a key ever lands in chat or `git log`, rotate immediately (Stripe Dashboard → Developers → API keys → Roll) — even "just the test key".
:::

### 7. Assess the billing model (MUST)

Answer these **before** configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.

:::note[Who does this]
👤 **User** answers the billing-model questions — these are product/pricing decisions, not implementation.
:::

<Steps>

1. **Fill the billing-model decision table.**

   | Question | Your answer |
   |---|---|
   | Billing model | one-time / recurring / usage-based / hybrid |
   | Number of tiers | single / 2–3 tiers / 4+ tiers |
   | Intervals offered | monthly / monthly + yearly / + lifetime |
   | Free tier? | feature-limited / usage-limited / none |
   | Trial period | none / N days no card / N days card required |
   | Annual discount | none / X% off / X months free |
   | Currency | single / multi-currency |
   | Tax handling | inclusive / exclusive / auto (Stripe Tax) |
   | Proration on upgrade | immediate charge / next cycle / none |
   | Cancellation | at period end / immediate + refund / immediate no refund |

   - ✅ You can read this table aloud to a non-technical person and they understand the customer experience.

</Steps>

### 8. Set up subscription plans (MUST)

Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.

<Steps>

1. **Check the admin panel first** — look for `Settings → Plans`/`Pricing`, `Subscriptions → Plans`, `Admin → Membership Plans`, or `Finance → Subscription Plans`. If found, configure tiers/prices/features/trial/annual toggle in the UI (~5 min) and skip to substep 3.

   - ✅ Plans are configured in the admin UI (if it exists).

2. **Code fallback** — if no admin UI, seed via `database/seeders/PlansSeeder.php` using Cashier. Each plan needs `name`, `stripe_id` (the Price ID), `stripe_plan`, `billing_interval`, and a `features` JSON.

   :::caution[Back up the plans table before re-seeding a live DB]
   A seeder that `updateOrCreate`s (or worse, truncates and re-inserts) plan rows can **overwrite the `stripe_id` price mappings** that existing subscribers are billed against — silently breaking their renewals. Before running a plans seeder on **any** environment that already has subscriptions, dump the table so you can roll back. On Herd Pro / MariaDB the dump tool is `mariadb-dump` (the renamed `mysqldump`):

   ```bash
   # Back up first — rollback net before any re-seed touches existing plan rows
   mariadb-dump -u <user> -p <db> plans > /tmp/plans-backup-$(date +%F).sql   # or mysqldump on MySQL hosts
   php artisan make:seeder PlansSeeder
   php artisan db:seed --class=PlansSeeder
   # Expected: the plan rows are seeded with non-null stripe_id values; the backup SQL exists as a rollback
   ```

   Prefer an **idempotent** `updateOrCreate` keyed on a stable column (plan slug) over truncate-and-insert, so a re-run never duplicates or re-IDs rows.
   :::

   - ✅ Plans are seeded with Price IDs and a features JSON, and a pre-seed table backup exists if the DB already had subscriptions.

3. **Confirm provider-side Products/Prices (critical).** The Products + Prices must **also** exist in Stripe/Paddle/LemonSqueezy. Your local records only store the `price_id`; they don't create the provider object. A plan that exists in your DB but not in the gateway will **500 at checkout**.

   - ✅ Each DB plan maps to a real provider-side Product/Price.

4. **Map feature gating.** Map each plan to the features it unlocks (character counts, seats, API calls, branding removal). Most apps store this as JSON on the plan row — document the schema in `Admin-Local/1-Project/1-Info/billing-features.md`.

   - ✅ The admin lists all tiers with correct prices; `\App\Models\Plan::all()->pluck('stripe_id')` returns non-null Price IDs; `/pricing` renders every tier correctly.

</Steps>

### 9. Set up webhooks (MUST)

Register the endpoint, store the signing secret, and confirm signature verification — the security-critical step.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns the payment-provider account, login, secret values, and any live-money decision. 🤖 With an authorized browser/API session, the agent may register the endpoint and event subscriptions, then confirms the verification code and runs the `stripe trigger` tests. If the dashboard asks for a password, 2FA, live-mode confirmation, or payment-account verification, pause for the user.
:::

<Steps>

1. **Check the admin panel.** Many apps expose `Settings → Webhooks` or `Integrations → Stripe` with the URL + secret pre-wired. If present, configure there.

   - ✅ The admin webhook surface is used if it exists.

2. **Register the endpoint.** Stripe Dashboard → Developers → Webhooks → Add endpoint → `https://<domain>/stripe/webhook` (confirm with `php artisan route:list | grep stripe`). Subscribe to the minimum set:
   - `checkout.session.completed`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `customer.subscription.trial_will_end`

   - ✅ The endpoint is registered and subscribed to the minimum event set.

3. **Store the signing secret.** Fill the `STRIPE_WEBHOOK_SECRET=whsec_…` placeholder in the production `.env` via your secrets manager.

   - ✅ The signing secret is stored via the secrets manager.

4. **Confirm signature verification (critical security step).** Cashier does this automatically via its `WebhookController`. A custom handler **must** call:

   ```php
   \Stripe\Stripe::setApiKey(config('cashier.secret'));
   $event = \Stripe\Webhook::constructEvent(
       $request->getContent(),
       $request->header('Stripe-Signature'),
       config('cashier.webhook.secret')
   );
   ```

   A handler that trusts unverified POST bodies lets any attacker upgrade themselves to enterprise for free.

   - ✅ Signature verification runs on every webhook (Cashier or `constructEvent`).

5. **Test locally.**

   ```bash
   stripe listen --forward-to http://<project>.test/stripe/webhook
   stripe trigger checkout.session.completed
   # Expected: handler runs, signature verifies, subscription row created/updated
   ```

   - ✅ The triggered event runs the handler, verifies the signature, and updates a row.

6. **Add alerting.** Webhook failures are silent (users pay, your DB doesn't know). Add a Sentry alert for signature failures and 5xx from `/stripe/webhook` (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/) for Sentry setup).

   - ✅ The Stripe endpoint shows "200 OK" for recent deliveries; `stripe trigger invoice.payment_failed` flips a row to `past_due`; Sentry receives a test error on a deliberately invalid signature.

</Steps>

### 10. Configure tax & invoicing (SHOULD)

Pick one tax approach, then verify it on real test purchases.

<Steps>

1. **Pick a tax approach.**

   | Approach | Cost | Coverage | Best for |
   |---|---|---|---|
   | **Stripe Tax** (auto) | 0.5%/txn | 50+ countries, auto VAT/GST/sales tax | Any SaaS selling internationally |
   | **Paddle as MoR** | ~5% + $0.50 | All countries, remits for you | Indie teams wanting zero tax burden (replaces Stripe) |
   | **Manual tax tables** | Free | Only what you configure | Single-country, single-rate |
   | **No tax collection** | Free | N/A | Pre-revenue MVPs (may be illegal past thresholds) |

   - ✅ A tax approach is chosen.

2. **Enable Stripe Tax (recommended default).** Enable at Dashboard → Tax → Settings, then in the Cashier checkout:

   ```php
   $user->newSubscription('default', $priceId)
       ->checkout([
           'automatic_tax' => ['enabled' => true],
           'customer_update' => ['address' => 'auto'],
       ]);
   ```

   For EU B2B, collect VAT IDs so Stripe applies the reverse charge — add `tax_id_collection: ['enabled' => true]` (Cashier 14+). For invoices: Stripe-hosted PDFs come free via `$user->invoice()->download()`; for a branded template, `php artisan vendor:publish --tag=cashier-views` and edit `receipt.blade.php`; if you legally need sequential gapless numbering, generate it on the `invoice.payment_succeeded` webhook.

   - ✅ A VAT-registered EU test purchase shows 0% VAT with a "reverse charge" note; a US purchase shows correct state tax; the invoice PDF downloads with your branding.

</Steps>

### 11. Configure dunning & failed payments (SHOULD)

Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.

<Steps>

1. **Enable Smart Retries.** Stripe Dashboard → Settings → Billing → Subscriptions and emails → "Manage failed payments" → enable **Smart Retries**; set the max retry period (3 weeks typical, 7 days minimum).

   - ✅ Smart Retries are enabled with a retry window set.

2. **Set a grace period** before cancellation.

   | Grace period | Use case |
   |---|---|
   | 3 days | High-churn, low-ARPU consumer |
   | 7 days | Standard SaaS default |
   | 14 days | B2B, ARR > $500 |

   - ✅ A grace period is set for the product's profile.

3. **Enable email notifications.** Stripe's branded dunning emails (Dashboard → Settings → Emails) **or** handle in Laravel from the `invoice.payment_failed` webhook: `$user->notify(new PaymentFailedNotification($invoice));`

   - ✅ Failed-payment emails are wired (Stripe or Laravel).

4. **Document the post-failure behavior.**
   - **Soft downgrade** (recommended) — subscription → `past_due`, feature gates check `$user->subscribed() && !$user->subscription()->pastDue()`, user sees a billing banner + limited access. Easier recovery.
   - **Hard cancel** — subscription deleted, user drops to free. Cleaner, harder to win back.

   - ✅ The chosen post-failure behavior is documented.

5. **Test the failed-payment path.** In test mode use card `4000 0000 0000 0341` (attaches but fails on charge) to walk failed webhook → `past_due` → dunning emails → grace period → cancellation.

   - ✅ A test-mode failed renewal triggers `invoice.payment_failed`; the user gets the email; after the grace period the DB status flips to `canceled` and access revokes.

</Steps>

### 12. Document the payment lifecycle (SHOULD)

The goal: future-you (or a support agent at 2 AM) can look up any subscription's state and know what should happen next.

<Steps>

1. **Write the lifecycle doc.** Create `Admin-Local/1-Project/1-Info/billing-lifecycle.md` with the state machine, a test matrix, alert rules, and a runbook.

   ```mermaid
   stateDiagram-v2
     [*] --> trialing: checkout (trial_days > 0)
     [*] --> active: checkout (trial_days == 0)
     trialing --> active: trial end + payment success
     trialing --> canceled: trial end + no card
     active --> past_due: invoice.payment_failed
     past_due --> active: retry success
     past_due --> canceled: grace expired
     active --> canceled: user cancels → period end
     canceled --> active: user resubscribes
   ```

   - ✅ The lifecycle doc exists with the state diagram.

2. **Record the test matrix** — for each transition, how to reproduce it in Stripe test mode.

   | Transition | Reproduce (test mode) |
   |---|---|
   | new → trialing | Checkout with `trial_days=7`, card `4242…4242` |
   | trialing → active | `stripe trigger invoice.payment_succeeded` |
   | active → past_due | Card `4000…0341` on renewal, then `stripe trigger invoice.payment_failed` |
   | past_due → canceled | Wait out grace, or `stripe trigger customer.subscription.deleted` |
   | canceled → active | Same user resubscribes |

   - ✅ Every test-matrix transition has been executed once.

3. **Add the Sentry alert rules** (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/)) — a `past_due` spike (>5 in 1 hour = payment processing broke); any `SignatureVerificationException` (someone probing, or your secret rotated); a churn threshold (>3% cancel in 24 hours = check for an outage or bad deploy). Append a "what to do when" runbook for the common support cases ("I paid but can't access", refund requests, stuck renewals).

   - ✅ The 3 Sentry rules are active and one has been test-fired.

</Steps>

## Checklist

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

- [ ] **🔀 At least one gateway connected** — test payment succeeds and a declined card is rejected.
- [ ] **👤 Billing model decision record** filled in.
- [ ] **🔀 Plans exist in both the DB and the provider dashboard** — `/pricing` renders correctly.
- [ ] **🔀 Webhook endpoint returns 200** — signature verification confirmed.
- [ ] **🔀 Tax approach chosen** — Stripe Tax (if applicable) verified on EU + US test purchases.
- [ ] **🔀 Dunning configured + tested** — post-failure behavior documented.
- [ ] **🤖 `billing-lifecycle.md` written** — state machine, test matrix, and alert rules.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the billing model, active gateways, non-secret provider/product/price IDs, webhook endpoint paths, mode per environment, and vault item pointers.

:::next[Next step]
[Email infrastructure](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/04-email/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle docs — so billing goes from “a card can charge” to production-ready.

Steps at a glance:

Choose a payment approach — Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.
Configure Stripe — CodeCanyon built-in — No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.
Integrate Stripe — from scratch via Cashier — Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.
Set up PayPal (SHOULD — broad global coverage) — Add PayPal for global reach and buyer trust.
Set up Tap Payments for MENA — Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes 1–3 business days.
Set up LemonSqueezy — Merchant of Record — LemonSqueezy is the legal seller: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50).
Assess the billing model — Answer these before configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.
Set up subscription plans — Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.
Set up webhooks — Register the endpoint, store the signing secret, and confirm signature verification — the security-critical step.
Configure tax & invoicing — Pick one tax approach, then verify it on real test purchases.
Configure dunning & failed payments — Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.
Document the payment lifecycle — The goal: future-you (or a support agent at 2 AM) can look up any subscription’s state and know what should happen next.

🔀 User part — humans own account creation, identity/bank verification, live-money choices, passwords, 2FA, and secret values. With an authorized browser/API session, the agent drives non-secret provider-console work: create developer apps after the account exists, register webhook endpoints/events, configure approved test products/tax/dunning settings, wire env placeholders, install Cashier when needed, seed plans, and run stripe trigger tests. Pause only at password/secret/2FA/payment-account-verification/live-mode gates.

Done when at least one gateway is connected with a successful test charge and a rejected decline, plans exist in both the DB and the provider, the webhook endpoint returns 200 with verified signatures, and tax/dunning/lifecycle are configured and documented. · ⏱ ~2–4 hr · 🔀 mixed (👤 dashboards/keys, 🤖 Cashier + seeders + tests).

Background

Payment configuration is two jobs: (1) establish or authorize the external account(s) and secret material, then (2) wire the non-secret provider objects, keys, webhook endpoint, and app code — and then take billing from “a card can charge” to “subscriptions, webhooks, tax, dunning, and lifecycle are production-ready.”

Read Zaj-PROJECT.md before provider work so the environment URLs, gateway choices, billing model, non-secret provider IDs, webhook endpoint paths, and vault pointers come from one place. Update it after each provider is verified; secrets, signing secrets, and live keys stay only in the vault/provider dashboard.

Steps

1. Choose a payment approach

Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.

Pick the approach(es) from the matrix.

Approach	Best for	Fee	Tax handling
Stripe (CodeCanyon built-in)	Apps that ship a Stripe module — just paste keys	~3%	Yours (or Stripe Tax)
Stripe (from scratch)	Apps with no Stripe module — via Laravel Cashier	~3%	Yours
PayPal	Global coverage, buyer trust	2.9% + $0.30	Yours
Tap Payments	MENA region (Mada, KNET, Benefit)	2.75% + AED 1.00	Partial (VAT config)
LemonSqueezy (MoR)	Solo founders wanting zero tax burden	5% + $0.50	They handle everything

flowchart TD
  Q{"App ships a Stripe module?"}
  Q -- Yes --> CC["Stripe (CodeCanyon)<br/>paste keys, no code"]
  Q -- No --> S{"Want zero tax burden?"}
  S -- Yes --> LS["LemonSqueezy (MoR)"]
  S -- No --> ST["Stripe (Cashier, from scratch)"]
  CC --> M{"Selling in GCC?"}
  ST --> M
  LS --> M
  M -- "Mada / KNET needed" --> TAP["Add Tap Payments"]
  M -- No --> PP["Add PayPal for global reach"]

✅ At least one approach chosen, with regional gateways added where the market demands.

Whichever gateway you pick, the object-creation steps below can be automated rather than clicked.

2. Configure Stripe — CodeCanyon built-in (recommended where available)

No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.

Toggle Stripe on and paste the test keys. Log in as Super Admin → Settings → Payment Setting → Stripe → Stripe ON → paste the Stripe Key (pk_test_…) and Stripe Secret Key (sk_test_…), then Save.
- ✅ Stripe is toggled on with the test keys saved.
Run a test purchase. Log in as a test user → Pricing → pick a plan → pay with 4242 4242 4242 4242 (CVC 123, expiry 12/34, ZIP 12345). Verify the user upgrades and the transaction appears in the Stripe Dashboard.
- ✅ The test purchase upgrades the user and shows in the Stripe Dashboard.
Run a decline test. Pay with 4000 0000 0000 0002 → error message shown, user not upgraded.
- ✅ The declined card errors and does not upgrade the user.
Confirm branding. The app logo, brand colors, and business name appear during checkout and on the receipt email.
- ✅ Checkout and the receipt are on-brand.
Go live. Swap sandbox keys for live keys (Stripe Dashboard → Live mode → Developers → API keys), make a small real purchase ($1–5), verify in the Live dashboard, then refund it.
- ✅ A small live purchase succeeds and is refunded.

3. Integrate Stripe — from scratch via Cashier (only if no built-in module)

Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.

Install Cashier.

composer require laravel/cashier
php artisan migrate
# Verify: php artisan migrate:status | grep cashier  → all "Ran"
# Expected: Cashier migrations show "Ran"

✅ Cashier is installed and its migrations have run.

Configure env and publish config. Confirm STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET are set.
Terminal window
```
php artisan vendor:publish --tag="cashier-config"
# Expected: cashier.php published to config/
```
- ✅ The Stripe env vars are set and the Cashier config is published.

Add the Billable trait to App\Models\User.

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
    // ...
}

✅ User uses the Billable trait.

Add the checkout route. Add GET /subscribe/{plan} that maps plan slugs to Stripe price IDs and calls ->newSubscription()->checkout().
- ✅ /subscribe/{plan} resolves plan slugs to price IDs and starts checkout.
Add the billing portal. Add GET /billing calling ->redirectToBillingPortal(); enable the portal at Stripe Dashboard → Settings → Billing → Customer portal.
- ✅ /billing redirects to the customer portal.
Add the webhook handler. Add POST /stripe/webhook → WebhookController::handleWebhook, exclude stripe/* from CSRF (Laravel 10: $except in app/Http/Middleware/VerifyCsrfToken.php; Laravel 11+: $middleware->validateCsrfTokens(except: ['stripe/*']) in bootstrap/app.php), and optionally extend Cashier’s WebhookController.
- ✅ The webhook route is wired and excluded from CSRF.
Add subscription checks. Use $user->subscribed('default'), $user->subscribedToPrice(), $user->onTrial(); add an EnsureSubscribed middleware for gated routes.
- ✅ Subscription gating works via Cashier helpers + middleware.
Test and commit. Run /subscribe/basic-monthly with 4242 4242 4242 4242; test the portal at /billing; run stripe listen --forward-to localhost:8000/stripe/webhook.
Terminal window
```
git add composer.json composer.lock database/ app/ routes/ config/
git commit -m "feat(payments): integrate Stripe via Laravel Cashier"
# Expected: the Cashier integration is committed
```
- ✅ Checkout, portal, and webhook forwarding work, and the integration is committed.

4. Set up PayPal (SHOULD — broad global coverage)

Add PayPal for global reach and buyer trust.

Create and verify a business account. Sign up at paypal.com/business, complete the business profile (legal name, category Software/Technology, address), add a bank account, and finish identity verification until the profile shows Verified.
- ✅ The PayPal business profile shows Verified.
Create the API apps. At developer.paypal.com → Apps & Credentials, create a Sandbox app ([PROJECT] Development, Merchant) and copy the Client ID (AW…) + Secret (EJ…); switch to Live and create [PROJECT] Production, copy Client ID (AR…) + Secret (ES…).
- ✅ Sandbox and Live Client IDs + Secrets are copied.
Register webhooks. Add https://<selected-nonproduction-domain>/paypal/webhook (sandbox app) and https://<production-domain>/paypal/webhook (live app); subscribe to payment-capture and subscription events; copy each Webhook ID.
- ✅ Both webhook endpoints are registered and the Webhook IDs copied.
Create sandbox test accounts. A Business (Seller) account ($5000) and a Personal (Buyer) account ($1000).
- ✅ Sandbox seller + buyer accounts exist.
Create subscription products (if recurring) — Products & Subscriptions → create a Service/SaaS product, add Monthly and Yearly billing plans, note the Plan IDs (P-…).
- ✅ Subscription products and Plan IDs exist (if recurring).

Wire env. Add placeholders to .env.example (safe to commit) and fill real values in .env.

## === PAYPAL ===
PAYPAL_MODE=sandbox
PAYPAL_SANDBOX_CLIENT_ID=
PAYPAL_SANDBOX_CLIENT_SECRET=
PAYPAL_LIVE_CLIENT_ID=
PAYPAL_LIVE_CLIENT_SECRET=
PAYPAL_SANDBOX_WEBHOOK_ID=
PAYPAL_LIVE_WEBHOOK_ID=
# Expected: placeholders in .env.example; real values in .env (uncommitted)

✅ The PayPal env block is wired with placeholders committed, real values local.

5. Set up Tap Payments for MENA

Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes 1–3 business days.

Sign up and submit for verification. At tap.company → select country → enter business info (legal name, trade-license number, category) → upload documents (Trade License/CR, Owner ID, bank statement) → submit.
- ✅ The Tap account is submitted for verification.
Copy the API keys after approval. dashboard.tap.company → Developers → API Keys; copy test (sk_test_…, pk_test_…) and live (sk_live_…, pk_live_…).
- ✅ Test and live Tap keys are copied.
Enable payment methods per target country. Settings → Payment Methods.

Country Essential methods
Saudi Arabia Mada (90%+ usage), Visa/MC, Apple Pay
Kuwait KNET (80%+ usage), Visa/MC
Bahrain Benefit (70%+ usage), Visa/MC
UAE Visa/MC, Apple Pay
- ✅ Country-essential methods are enabled.
Register webhooks. Developers → Webhooks → https://<domain>/tap/webhook; subscribe to CHARGE.CAPTURED, CHARGE.FAILED, CHARGE.REFUNDED, AUTHORIZE.CAPTURED, AUTHORIZE.VOIDED; copy the secret.
- ✅ The Tap webhook is registered with its secret copied.
Configure VAT. Settings → Tax Settings: SA 15%, UAE 5%, BH 10%, KW 0%, QA 0%, OM 5%.
- ✅ VAT rates are set per country.

Country	Essential methods
Saudi Arabia	Mada (90%+ usage), Visa/MC, Apple Pay
Kuwait	KNET (80%+ usage), Visa/MC
Bahrain	Benefit (70%+ usage), Visa/MC
UAE	Visa/MC, Apple Pay

Wire env.

## === TAP PAYMENTS ===
TAP_SECRET_KEY=
TAP_PUBLISHABLE_KEY=
TAP_WEBHOOK_SECRET=
TAP_CURRENCY=SAR
# Expected: the Tap env block is present with placeholders

✅ The Tap env block is wired.

6. Set up LemonSqueezy — Merchant of Record (ALTERNATIVE)

LemonSqueezy is the legal seller: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50). Best for solo founders selling globally; not ideal for low-margin products, enterprise buyers, or MENA (no Mada/KNET).

Create the account. lemonsqueezy.com → Get Started Free → onboarding (Software/SaaS, revenue estimate, location) → connect payout (Stripe Connect or PayPal) → verify identity.
- ✅ The LemonSqueezy account is created with payout connected.
Configure the store. Settings → General: Store Name, Support Email, Logo, Currency. Optional: add a custom checkout domain.
- ✅ Store details are set.
Create products. Store → Products → New Product, Pricing Type Subscription, set Monthly + Yearly, add variants (Basic/Pro/Business), note Product ID + Variant IDs.
- ✅ Subscription products with Variant IDs exist.
Create the API key. Settings → API → create ([PROJECT] Production, Read & Write); copy the key (lmn_…, shown once); note the Store ID.
- ✅ The API key (lmn_…) and Store ID are stored.
Register webhooks. Settings → Webhooks → https://<domain>/lemonsqueezy/webhook; subscribe to order_created, order_refunded, subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, subscription_expired, subscription_payment_failed; copy the signing secret.
- ✅ The webhook is registered with its signing secret copied.
Pick the integration method by effort — simple checkout links (low), Lemon.js overlay (medium), or a Laravel package (high/full API).
- ✅ An integration method is chosen.

Wire env.

## === LEMONSQUEEZY ===
LEMONSQUEEZY_API_KEY=
LEMONSQUEEZY_STORE_ID=
LEMONSQUEEZY_SIGNING_SECRET=
LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID=
LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID=
LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID=
LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID=
# Expected: the LemonSqueezy env block is present with placeholders

✅ The LemonSqueezy env block is wired.

Test the checkout. Open the checkout link → complete a test purchase → verify the webhook fires and the user gets access.
- ✅ A test purchase fires the webhook and grants access.

7. Assess the billing model (MUST)

Answer these before configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.

Fill the billing-model decision table.

Question	Your answer
Billing model	one-time / recurring / usage-based / hybrid
Number of tiers	single / 2–3 tiers / 4+ tiers
Intervals offered	monthly / monthly + yearly / + lifetime
Free tier?	feature-limited / usage-limited / none
Trial period	none / N days no card / N days card required
Annual discount	none / X% off / X months free
Currency	single / multi-currency
Tax handling	inclusive / exclusive / auto (Stripe Tax)
Proration on upgrade	immediate charge / next cycle / none
Cancellation	at period end / immediate + refund / immediate no refund

✅ You can read this table aloud to a non-technical person and they understand the customer experience.

8. Set up subscription plans (MUST)

Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.

Check the admin panel first — look for Settings → Plans/Pricing, Subscriptions → Plans, Admin → Membership Plans, or Finance → Subscription Plans. If found, configure tiers/prices/features/trial/annual toggle in the UI (~5 min) and skip to substep 3.
- ✅ Plans are configured in the admin UI (if it exists).
Code fallback — if no admin UI, seed via database/seeders/PlansSeeder.php using Cashier. Each plan needs name, stripe_id (the Price ID), stripe_plan, billing_interval, and a features JSON.
Back up the plans table before re-seeding a live DB
A seeder that updateOrCreates (or worse, truncates and re-inserts) plan rows can overwrite the stripe_id price mappings that existing subscribers are billed against — silently breaking their renewals. Before running a plans seeder on any environment that already has subscriptions, dump the table so you can roll back. On Herd Pro / MariaDB the dump tool is mariadb-dump (the renamed mysqldump):
Terminal window
# Back up first — rollback net before any re-seed touches existing plan rows mariadb-dump -u <user> -p <db> plans > /tmp/plans-backup-$(date +%F).sql # or mysqldump on MySQL hosts php artisan make:seeder PlansSeeder php artisan db:seed --class=PlansSeeder # Expected: the plan rows are seeded with non-null stripe_id values; the backup SQL exists as a rollback
Prefer an idempotent updateOrCreate keyed on a stable column (plan slug) over truncate-and-insert, so a re-run never duplicates or re-IDs rows.
- ✅ Plans are seeded with Price IDs and a features JSON, and a pre-seed table backup exists if the DB already had subscriptions.
Confirm provider-side Products/Prices (critical). The Products + Prices must also exist in Stripe/Paddle/LemonSqueezy. Your local records only store the price_id; they don’t create the provider object. A plan that exists in your DB but not in the gateway will 500 at checkout.
- ✅ Each DB plan maps to a real provider-side Product/Price.
Map feature gating. Map each plan to the features it unlocks (character counts, seats, API calls, branding removal). Most apps store this as JSON on the plan row — document the schema in Admin-Local/1-Project/1-Info/billing-features.md.
- ✅ The admin lists all tiers with correct prices; \App\Models\Plan::all()->pluck('stripe_id') returns non-null Price IDs; /pricing renders every tier correctly.

9. Set up webhooks (MUST)

Check the admin panel. Many apps expose Settings → Webhooks or Integrations → Stripe with the URL + secret pre-wired. If present, configure there.
- ✅ The admin webhook surface is used if it exists.
Register the endpoint. Stripe Dashboard → Developers → Webhooks → Add endpoint → https://<domain>/stripe/webhook (confirm with php artisan route:list | grep stripe). Subscribe to the minimum set:
- checkout.session.completed
- invoice.payment_succeeded
- invoice.payment_failed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- customer.subscription.trial_will_end
- ✅ The endpoint is registered and subscribed to the minimum event set.
Store the signing secret. Fill the STRIPE_WEBHOOK_SECRET=whsec_… placeholder in the production .env via your secrets manager.
- ✅ The signing secret is stored via the secrets manager.
Confirm signature verification (critical security step). Cashier does this automatically via its WebhookController. A custom handler must call:
```
\Stripe\Stripe::setApiKey(config('cashier.secret'));
$event = \Stripe\Webhook::constructEvent(
    $request->getContent(),
    $request->header('Stripe-Signature'),
    config('cashier.webhook.secret')
);
```
A handler that trusts unverified POST bodies lets any attacker upgrade themselves to enterprise for free.
- ✅ Signature verification runs on every webhook (Cashier or constructEvent).

Test locally.

stripe listen --forward-to http://<project>.test/stripe/webhook
stripe trigger checkout.session.completed
# Expected: handler runs, signature verifies, subscription row created/updated

✅ The triggered event runs the handler, verifies the signature, and updates a row.

Add alerting. Webhook failures are silent (users pay, your DB doesn’t know). Add a Sentry alert for signature failures and 5xx from /stripe/webhook (see Phase 7 · Observability for Sentry setup).
- ✅ The Stripe endpoint shows “200 OK” for recent deliveries; stripe trigger invoice.payment_failed flips a row to past_due; Sentry receives a test error on a deliberately invalid signature.

10. Configure tax & invoicing (SHOULD)

Pick one tax approach, then verify it on real test purchases.

Pick a tax approach.

Approach	Cost	Coverage	Best for
Stripe Tax (auto)	0.5%/txn	50+ countries, auto VAT/GST/sales tax	Any SaaS selling internationally
Paddle as MoR	~5% + $0.50	All countries, remits for you	Indie teams wanting zero tax burden (replaces Stripe)
Manual tax tables	Free	Only what you configure	Single-country, single-rate
No tax collection	Free	N/A	Pre-revenue MVPs (may be illegal past thresholds)

✅ A tax approach is chosen.

Enable Stripe Tax (recommended default). Enable at Dashboard → Tax → Settings, then in the Cashier checkout:
```
$user->newSubscription('default', $priceId)
    ->checkout([
        'automatic_tax' => ['enabled' => true],
        'customer_update' => ['address' => 'auto'],
    ]);
```
For EU B2B, collect VAT IDs so Stripe applies the reverse charge — add tax_id_collection: ['enabled' => true] (Cashier 14+). For invoices: Stripe-hosted PDFs come free via $user->invoice()->download(); for a branded template, php artisan vendor:publish --tag=cashier-views and edit receipt.blade.php; if you legally need sequential gapless numbering, generate it on the invoice.payment_succeeded webhook.
- ✅ A VAT-registered EU test purchase shows 0% VAT with a “reverse charge” note; a US purchase shows correct state tax; the invoice PDF downloads with your branding.

11. Configure dunning & failed payments (SHOULD)

Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.

Enable Smart Retries. Stripe Dashboard → Settings → Billing → Subscriptions and emails → “Manage failed payments” → enable Smart Retries; set the max retry period (3 weeks typical, 7 days minimum).
- ✅ Smart Retries are enabled with a retry window set.
Set a grace period before cancellation.

Grace period Use case
3 days High-churn, low-ARPU consumer
7 days Standard SaaS default
14 days B2B, ARR > $500
- ✅ A grace period is set for the product’s profile.
Enable email notifications. Stripe’s branded dunning emails (Dashboard → Settings → Emails) or handle in Laravel from the invoice.payment_failed webhook: $user->notify(new PaymentFailedNotification($invoice));
- ✅ Failed-payment emails are wired (Stripe or Laravel).
Document the post-failure behavior.
- Soft downgrade (recommended) — subscription → past_due, feature gates check $user->subscribed() && !$user->subscription()->pastDue(), user sees a billing banner + limited access. Easier recovery.
- Hard cancel — subscription deleted, user drops to free. Cleaner, harder to win back.
- ✅ The chosen post-failure behavior is documented.
Test the failed-payment path. In test mode use card 4000 0000 0000 0341 (attaches but fails on charge) to walk failed webhook → past_due → dunning emails → grace period → cancellation.
- ✅ A test-mode failed renewal triggers invoice.payment_failed; the user gets the email; after the grace period the DB status flips to canceled and access revokes.

Grace period	Use case
3 days	High-churn, low-ARPU consumer
7 days	Standard SaaS default
14 days	B2B, ARR > $500

12. Document the payment lifecycle (SHOULD)

The goal: future-you (or a support agent at 2 AM) can look up any subscription’s state and know what should happen next.

Write the lifecycle doc. Create Admin-Local/1-Project/1-Info/billing-lifecycle.md with the state machine, a test matrix, alert rules, and a runbook.

stateDiagram-v2
  [*] --> trialing: checkout (trial_days > 0)
  [*] --> active: checkout (trial_days == 0)
  trialing --> active: trial end + payment success
  trialing --> canceled: trial end + no card
  active --> past_due: invoice.payment_failed
  past_due --> active: retry success
  past_due --> canceled: grace expired
  active --> canceled: user cancels → period end
  canceled --> active: user resubscribes

✅ The lifecycle doc exists with the state diagram.

Record the test matrix — for each transition, how to reproduce it in Stripe test mode.

Transition	Reproduce (test mode)
new → trialing	Checkout with `trial_days=7`, card `4242…4242`
trialing → active	`stripe trigger invoice.payment_succeeded`
active → past_due	Card `4000…0341` on renewal, then `stripe trigger invoice.payment_failed`
past_due → canceled	Wait out grace, or `stripe trigger customer.subscription.deleted`
canceled → active	Same user resubscribes

✅ Every test-matrix transition has been executed once.

Add the Sentry alert rules (see Phase 7 · Observability) — a past_due spike (>5 in 1 hour = payment processing broke); any SignatureVerificationException (someone probing, or your secret rotated); a churn threshold (>3% cancel in 24 hours = check for an outage or bad deploy). Append a “what to do when” runbook for the common support cases (“I paid but can’t access”, refund requests, stuck renewals).
- ✅ The 3 Sentry rules are active and one has been test-fired.

Checklist

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

🔀 At least one gateway connected — test payment succeeds and a declined card is rejected.
👤 Billing model decision record filled in.
🔀 Plans exist in both the DB and the provider dashboard — /pricing renders correctly.
🔀 Webhook endpoint returns 200 — signature verification confirmed.
🔀 Tax approach chosen — Stripe Tax (if applicable) verified on EU + US test purchases.
🔀 Dunning configured + tested — post-failure behavior documented.
🤖 billing-lifecycle.md written — state machine, test matrix, and alert rules.
🤖 Project state updated — Zaj-PROJECT.md records the billing model, active gateways, non-secret provider/product/price IDs, webhook endpoint paths, mode per environment, and vault item pointers.

Email infrastructure

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 3 · Payments & billing
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/03-payments-billing/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 8
- part_number: 3 (legacy stepNumber frontmatter)
- legacy_step_number: 3
- est_time: ~2–4 hr (varies heavily by gateway count)
- description: Choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle documentation.
- tags: codecanyon, laravel, payments, billing, stripe, tax

## Execution rules (binding)
- This is Part 3 of phase 8 (~2–4 hr (varies heavily by gateway count)) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 3 · Payments & billing

## TL;DR

**Objective** — choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle docs — so billing goes from "a card can charge" to production-ready.

**Steps at a glance:**
1. **Choose a payment approach** — Pick at least one. Stripe + PayPal is the most common combination; add Tap
   for GCC markets, or LemonSqueezy to offload tax compliance entirely.
2. **Configure Stripe — CodeCanyon built-in** — No custom code — the app already has the Stripe module wired.
   Paste keys, test, and go live.
3. **Integrate Stripe — from scratch via Cashier** — Skip this if the CodeCanyon built-in above applies.
   Otherwise wire Cashier end-to-end.
4. **Set up PayPal (SHOULD — broad global coverage)** — Add PayPal for global reach and buyer trust.
5. **Set up Tap Payments for MENA** — Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets.
   Approval takes 1–3 business days.
6. **Set up LemonSqueezy — Merchant of Record** — LemonSqueezy is the legal seller: they handle all tax
   compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50).
7. **Assess the billing model** — Answer these before configuring plans anywhere — wrong answers cascade into
   every later task. Stripe Products/Prices are hard to rename after customers subscribe, and
   proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.
8. **Set up subscription plans** — Define tiers/prices/features in the admin panel where it exists, otherwise
   seed them in code — then confirm the provider-side objects exist.
9. **Set up webhooks** — Register the endpoint, store the signing secret, and confirm signature verification —
   the security-critical step.
10. **Configure tax & invoicing** — Pick one tax approach, then verify it on real test purchases.
11. **Configure dunning & failed payments** — Dunning is the retry + notification sequence when a recurring
   charge fails. Without it, MRR silently leaks.
12. **Document the payment lifecycle** — The goal: future-you (or a support agent at 2 AM) can look up any
   subscription's state and know what should happen next.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, identity/bank verification, live-money choices, passwords, 2FA, and secret values. With an authorized browser/API session, the agent drives non-secret provider-console work: create developer apps after the account exists, register webhook endpoints/events, configure approved test products/tax/dunning settings, wire env placeholders, install Cashier when needed, seed plans, and run `stripe trigger` tests. Pause only at password/secret/2FA/payment-account-verification/live-mode gates.

**Done when** at least one gateway is connected with a successful test charge and a rejected decline, plans exist in both the DB and the provider, the webhook endpoint returns 200 with verified signatures, and tax/dunning/lifecycle are configured and documented. &nbsp;·&nbsp; **⏱ ~2–4 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards/keys, 🤖 Cashier + seeders + tests).
:::

## Background

Payment configuration is two jobs: **(1)** establish or authorize the external account(s) and secret material, then **(2)** wire the non-secret provider objects, keys, webhook endpoint, and app code — and then take billing from "a card can charge" to "subscriptions, webhooks, tax, dunning, and lifecycle are production-ready."

Read `Zaj-PROJECT.md` before provider work so the environment URLs, gateway choices, billing model, non-secret provider IDs, webhook endpoint paths, and vault pointers come from one place. Update it after each provider is verified; secrets, signing secrets, and live keys stay only in the vault/provider dashboard.

:::caution[Check the admin panel first]
CodeCanyon SaaS templates almost always ship a built-in payment manager (`Settings → Payment Setting`) and a plans manager (`Settings → Plans`). Configure there when it exists — it is faster and authoritative. Only fall back to code when no admin surface exists.
:::

## Steps

### 1. Choose a payment approach

Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.

:::note[Who does this]
👤 **User** decides which gateway(s) to run — a business/scope decision based on markets and tax tolerance.
:::

<Steps>

1. **Pick the approach(es)** from the matrix.

   | Approach | Best for | Fee | Tax handling |
   |---|---|---|---|
   | **Stripe (CodeCanyon built-in)** | Apps that ship a Stripe module — just paste keys | ~3% | Yours (or Stripe Tax) |
   | **Stripe (from scratch)** | Apps with no Stripe module — via Laravel Cashier | ~3% | Yours |
   | **PayPal** | Global coverage, buyer trust | 2.9% + $0.30 | Yours |
   | **Tap Payments** | MENA region (Mada, KNET, Benefit) | 2.75% + AED 1.00 | Partial (VAT config) |
   | **LemonSqueezy (MoR)** | Solo founders wanting zero tax burden | 5% + $0.50 | They handle everything |

   ```mermaid
   flowchart TD
     Q{"App ships a Stripe module?"}
     Q -- Yes --> CC["Stripe (CodeCanyon)<br/>paste keys, no code"]
     Q -- No --> S{"Want zero tax burden?"}
     S -- Yes --> LS["LemonSqueezy (MoR)"]
     S -- No --> ST["Stripe (Cashier, from scratch)"]
     CC --> M{"Selling in GCC?"}
     ST --> M
     LS --> M
     M -- "Mada / KNET needed" --> TAP["Add Tap Payments"]
     M -- No --> PP["Add PayPal for global reach"]
   ```

   - ✅ At least one approach chosen, with regional gateways added where the market demands.

</Steps>

:::tip[Stripe does not cover MENA rails]
Card-only gateways do not support Mada or KNET. Without a regional gateway you lose **80–90%** of Saudi/Kuwaiti transactions. Add Tap if those markets matter.
:::

Whichever gateway you pick, the object-creation steps below can be automated rather than clicked.

:::note[Stripe MCP automation]
With the Stripe MCP server connected, create products/prices from your AI assistant instead of the dashboard — e.g. *"create a product 'Pro' with a $19 monthly price"*, *"list all products and prices to verify"*, or *"create a 20%-off-3-months coupon"*. Works for every gateway section below where you create or verify Stripe objects.
:::

### 2. Configure Stripe — CodeCanyon built-in (recommended where available)

No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns account login, key creation/copy, secret entry, real purchase/refund authorization, and live-key cutover. 🤖 With an authorized browser session, the agent can drive non-secret panel settings, verify product/price/webhook state, and collect evidence without reading secret values.
:::

<Steps>

1. **Toggle Stripe on and paste the test keys.** Log in as Super Admin → **Settings → Payment Setting → Stripe** → Stripe **ON** → paste the **Stripe Key** (`pk_test_…`) and **Stripe Secret Key** (`sk_test_…`), then **Save**.

   - ✅ Stripe is toggled on with the test keys saved.

2. **Run a test purchase.** Log in as a test user → Pricing → pick a plan → pay with `4242 4242 4242 4242` (CVC `123`, expiry `12/34`, ZIP `12345`). Verify the user upgrades and the transaction appears in the Stripe Dashboard.

   - ✅ The test purchase upgrades the user and shows in the Stripe Dashboard.

3. **Run a decline test.** Pay with `4000 0000 0000 0002` → error message shown, user **not** upgraded.

   - ✅ The declined card errors and does not upgrade the user.

4. **Confirm branding.** The app logo, brand colors, and business name appear during checkout and on the receipt email.

   - ✅ Checkout and the receipt are on-brand.

5. **Go live.** Swap sandbox keys for live keys (Stripe Dashboard → Live mode → Developers → API keys), make a small real purchase ($1–5), verify in the Live dashboard, then refund it.

   - ✅ A small live purchase succeeds and is refunded.

</Steps>

:::note[Webhooks often optional here]
Many CodeCanyon SaaS templates with a built-in Stripe module use a **redirect (hosted-checkout) pattern**, so webhooks are **not** required for basic one-off purchases. Confirm yours by checking whether the success path reads the return redirect vs. a webhook event. If you add subscriptions or custom post-payment logic, wire webhooks per [section 9](#9-set-up-webhooks-must).
:::

### 3. Integrate Stripe — from scratch via Cashier (only if no built-in module)

Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.

<Steps>

1. **Install Cashier.**

   ```bash
   composer require laravel/cashier
   php artisan migrate
   # Verify: php artisan migrate:status | grep cashier  → all "Ran"
   # Expected: Cashier migrations show "Ran"
   ```

   - ✅ Cashier is installed and its migrations have run.

2. **Configure env and publish config.** Confirm `STRIPE_KEY`, `STRIPE_SECRET`, `STRIPE_WEBHOOK_SECRET` are set.

   ```bash
   php artisan vendor:publish --tag="cashier-config"
   # Expected: cashier.php published to config/
   ```

   - ✅ The Stripe env vars are set and the Cashier config is published.

3. **Add the Billable trait** to `App\Models\User`.

   ```php
   use Laravel\Cashier\Billable;

   class User extends Authenticatable
   {
       use Billable;
       // ...
   }
   ```

   - ✅ `User` uses the `Billable` trait.

4. **Add the checkout route.** Add `GET /subscribe/{plan}` that maps plan slugs to Stripe price IDs and calls `->newSubscription()->checkout()`.

   - ✅ `/subscribe/{plan}` resolves plan slugs to price IDs and starts checkout.

5. **Add the billing portal.** Add `GET /billing` calling `->redirectToBillingPortal()`; enable the portal at Stripe Dashboard → Settings → Billing → Customer portal.

   - ✅ `/billing` redirects to the customer portal.

6. **Add the webhook handler.** Add `POST /stripe/webhook` → `WebhookController::handleWebhook`, exclude `stripe/*` from CSRF (**Laravel 10:** `$except` in `app/Http/Middleware/VerifyCsrfToken.php`; **Laravel 11+:** `$middleware->validateCsrfTokens(except: ['stripe/*'])` in `bootstrap/app.php`), and optionally extend Cashier's `WebhookController`.

   - ✅ The webhook route is wired and excluded from CSRF.

7. **Add subscription checks.** Use `$user->subscribed('default')`, `$user->subscribedToPrice()`, `$user->onTrial()`; add an `EnsureSubscribed` middleware for gated routes.

   - ✅ Subscription gating works via Cashier helpers + middleware.

8. **Test and commit.** Run `/subscribe/basic-monthly` with `4242 4242 4242 4242`; test the portal at `/billing`; run `stripe listen --forward-to localhost:8000/stripe/webhook`.

   ```bash
   git add composer.json composer.lock database/ app/ routes/ config/
   git commit -m "feat(payments): integrate Stripe via Laravel Cashier"
   # Expected: the Cashier integration is committed
   ```

   - ✅ Checkout, portal, and webhook forwarding work, and the integration is committed.

</Steps>

### 4. Set up PayPal (SHOULD — broad global coverage)

Add PayPal for global reach and buyer trust.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns PayPal account creation, business verification, bank/payout setup, password/2FA, and all secrets. 🤖 With an authorized browser/API session, the agent may create developer apps, register non-secret webhook endpoints/events, create sandbox test accounts, record IDs, and verify configuration. Pause for identity, banking, secret-copy, or live-money decisions.
:::

<Steps>

1. **Create and verify a business account.** Sign up at [paypal.com/business](https://www.paypal.com/business), complete the business profile (legal name, category Software/Technology, address), add a bank account, and finish identity verification until the profile shows **Verified**.

   - ✅ The PayPal business profile shows **Verified**.

2. **Create the API apps.** At [developer.paypal.com](https://developer.paypal.com/) → Apps & Credentials, create a **Sandbox** app (`[PROJECT] Development`, Merchant) and copy the Client ID (`AW…`) + Secret (`EJ…`); switch to **Live** and create `[PROJECT] Production`, copy Client ID (`AR…`) + Secret (`ES…`).

   - ✅ Sandbox and Live Client IDs + Secrets are copied.

3. **Register webhooks.** Add `https://<selected-nonproduction-domain>/paypal/webhook` (sandbox app) and `https://<production-domain>/paypal/webhook` (live app); subscribe to payment-capture and subscription events; copy each Webhook ID.

   - ✅ Both webhook endpoints are registered and the Webhook IDs copied.

4. **Create sandbox test accounts.** A Business (Seller) account ($5000) and a Personal (Buyer) account ($1000).

   - ✅ Sandbox seller + buyer accounts exist.

5. **Create subscription products** (if recurring) — Products & Subscriptions → create a Service/SaaS product, add Monthly and Yearly billing plans, note the Plan IDs (`P-…`).

   - ✅ Subscription products and Plan IDs exist (if recurring).

6. **Wire env.** Add placeholders to `.env.example` (safe to commit) and fill real values in `.env`.

   ```bash
   ## === PAYPAL ===
   PAYPAL_MODE=sandbox
   PAYPAL_SANDBOX_CLIENT_ID=
   PAYPAL_SANDBOX_CLIENT_SECRET=
   PAYPAL_LIVE_CLIENT_ID=
   PAYPAL_LIVE_CLIENT_SECRET=
   PAYPAL_SANDBOX_WEBHOOK_ID=
   PAYPAL_LIVE_WEBHOOK_ID=
   # Expected: placeholders in .env.example; real values in .env (uncommitted)
   ```

   - ✅ The PayPal env block is wired with placeholders committed, real values local.

</Steps>

### 5. Set up Tap Payments for MENA

Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes **1–3 business days**.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns signup, verification documents, banking, passwords/2FA, and legal/tax approvals. 🤖 With an authorized browser/API session, the agent may navigate Tap settings, enable approved non-secret payment methods, register webhook endpoints/events, record IDs, and verify configuration. Pause for document upload, secret-copy, payout, or live-money decisions.
:::

<Steps>

1. **Sign up and submit for verification.** At [tap.company](https://www.tap.company/) → select country → enter business info (legal name, trade-license number, category) → upload documents (Trade License/CR, Owner ID, bank statement) → submit.

   - ✅ The Tap account is submitted for verification.

2. **Copy the API keys** after approval. [dashboard.tap.company](https://dashboard.tap.company/) → Developers → API Keys; copy test (`sk_test_…`, `pk_test_…`) and live (`sk_live_…`, `pk_live_…`).

   - ✅ Test and live Tap keys are copied.

3. **Enable payment methods** per target country. Settings → Payment Methods.

   | Country | Essential methods |
   |---|---|
   | Saudi Arabia | Mada (90%+ usage), Visa/MC, Apple Pay |
   | Kuwait | KNET (80%+ usage), Visa/MC |
   | Bahrain | Benefit (70%+ usage), Visa/MC |
   | UAE | Visa/MC, Apple Pay |

   - ✅ Country-essential methods are enabled.

4. **Register webhooks.** Developers → Webhooks → `https://<domain>/tap/webhook`; subscribe to `CHARGE.CAPTURED`, `CHARGE.FAILED`, `CHARGE.REFUNDED`, `AUTHORIZE.CAPTURED`, `AUTHORIZE.VOIDED`; copy the secret.

   - ✅ The Tap webhook is registered with its secret copied.

5. **Configure VAT.** Settings → Tax Settings: SA 15%, UAE 5%, BH 10%, KW 0%, QA 0%, OM 5%.

   - ✅ VAT rates are set per country.

6. **Wire env.**

   ```bash
   ## === TAP PAYMENTS ===
   TAP_SECRET_KEY=
   TAP_PUBLISHABLE_KEY=
   TAP_WEBHOOK_SECRET=
   TAP_CURRENCY=SAR
   # Expected: the Tap env block is present with placeholders
   ```

   - ✅ The Tap env block is wired.

</Steps>

### 6. Set up LemonSqueezy — Merchant of Record (ALTERNATIVE)

LemonSqueezy is the **legal seller**: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50). Best for solo founders selling globally; **not** ideal for low-margin products, enterprise buyers, or MENA (no Mada/KNET).

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns account creation, payout/identity verification, password/2FA, secret values, and pricing/business approval. 🤖 With an authorized browser/API session, the agent may configure store metadata, create approved products/variants, register webhook endpoints/events, record IDs, and verify test checkout setup. Pause for secret-copy, payout, identity, or live-money decisions.
:::

<Steps>

1. **Create the account.** [lemonsqueezy.com](https://lemonsqueezy.com/) → Get Started Free → onboarding (Software/SaaS, revenue estimate, location) → connect payout (Stripe Connect or PayPal) → verify identity.

   - ✅ The LemonSqueezy account is created with payout connected.

2. **Configure the store.** Settings → General: Store Name, Support Email, Logo, Currency. Optional: add a custom checkout domain.

   - ✅ Store details are set.

3. **Create products.** Store → Products → New Product, Pricing Type **Subscription**, set Monthly + Yearly, add variants (Basic/Pro/Business), note Product ID + Variant IDs.

   - ✅ Subscription products with Variant IDs exist.

4. **Create the API key.** Settings → API → create (`[PROJECT] Production`, Read & Write); copy the key (`lmn_…`, shown once); note the Store ID.

   - ✅ The API key (`lmn_…`) and Store ID are stored.

5. **Register webhooks.** Settings → Webhooks → `https://<domain>/lemonsqueezy/webhook`; subscribe to `order_created`, `order_refunded`, `subscription_created`, `subscription_updated`, `subscription_cancelled`, `subscription_resumed`, `subscription_expired`, `subscription_payment_failed`; copy the signing secret.

   - ✅ The webhook is registered with its signing secret copied.

6. **Pick the integration method** by effort — simple checkout links (low), Lemon.js overlay (medium), or a Laravel package (high/full API).

   - ✅ An integration method is chosen.

7. **Wire env.**

   ```bash
   ## === LEMONSQUEEZY ===
   LEMONSQUEEZY_API_KEY=
   LEMONSQUEEZY_STORE_ID=
   LEMONSQUEEZY_SIGNING_SECRET=
   LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID=
   # Expected: the LemonSqueezy env block is present with placeholders
   ```

   - ✅ The LemonSqueezy env block is wired.

8. **Test the checkout.** Open the checkout link → complete a test purchase → verify the webhook fires and the user gets access.

   - ✅ A test purchase fires the webhook and grants access.

</Steps>

:::danger[Secret handling — the two highest-value keys]
Billing works with `STRIPE_SECRET` (`sk_live_*`/`sk_test_*`) and `STRIPE_WEBHOOK_SECRET` (`whsec_*`). A leaked `sk_live_*` lets an attacker issue refunds, create charges, and read customer data. Never echo the key, never `grep STRIPE .env` into chat, never paste it back "to check it". For a presence check: `grep -qE '^STRIPE_SECRET=sk_(test|live)_' .env && echo "✅ Stripe key present"` — staging should use `sk_test_`, production `sk_live_`. If a key ever lands in chat or `git log`, rotate immediately (Stripe Dashboard → Developers → API keys → Roll) — even "just the test key".
:::

### 7. Assess the billing model (MUST)

Answer these **before** configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.

:::note[Who does this]
👤 **User** answers the billing-model questions — these are product/pricing decisions, not implementation.
:::

<Steps>

1. **Fill the billing-model decision table.**

   | Question | Your answer |
   |---|---|
   | Billing model | one-time / recurring / usage-based / hybrid |
   | Number of tiers | single / 2–3 tiers / 4+ tiers |
   | Intervals offered | monthly / monthly + yearly / + lifetime |
   | Free tier? | feature-limited / usage-limited / none |
   | Trial period | none / N days no card / N days card required |
   | Annual discount | none / X% off / X months free |
   | Currency | single / multi-currency |
   | Tax handling | inclusive / exclusive / auto (Stripe Tax) |
   | Proration on upgrade | immediate charge / next cycle / none |
   | Cancellation | at period end / immediate + refund / immediate no refund |

   - ✅ You can read this table aloud to a non-technical person and they understand the customer experience.

</Steps>

### 8. Set up subscription plans (MUST)

Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.

<Steps>

1. **Check the admin panel first** — look for `Settings → Plans`/`Pricing`, `Subscriptions → Plans`, `Admin → Membership Plans`, or `Finance → Subscription Plans`. If found, configure tiers/prices/features/trial/annual toggle in the UI (~5 min) and skip to substep 3.

   - ✅ Plans are configured in the admin UI (if it exists).

2. **Code fallback** — if no admin UI, seed via `database/seeders/PlansSeeder.php` using Cashier. Each plan needs `name`, `stripe_id` (the Price ID), `stripe_plan`, `billing_interval`, and a `features` JSON.

   :::caution[Back up the plans table before re-seeding a live DB]
   A seeder that `updateOrCreate`s (or worse, truncates and re-inserts) plan rows can **overwrite the `stripe_id` price mappings** that existing subscribers are billed against — silently breaking their renewals. Before running a plans seeder on **any** environment that already has subscriptions, dump the table so you can roll back. On Herd Pro / MariaDB the dump tool is `mariadb-dump` (the renamed `mysqldump`):

   ```bash
   # Back up first — rollback net before any re-seed touches existing plan rows
   mariadb-dump -u <user> -p <db> plans > /tmp/plans-backup-$(date +%F).sql   # or mysqldump on MySQL hosts
   php artisan make:seeder PlansSeeder
   php artisan db:seed --class=PlansSeeder
   # Expected: the plan rows are seeded with non-null stripe_id values; the backup SQL exists as a rollback
   ```

   Prefer an **idempotent** `updateOrCreate` keyed on a stable column (plan slug) over truncate-and-insert, so a re-run never duplicates or re-IDs rows.
   :::

   - ✅ Plans are seeded with Price IDs and a features JSON, and a pre-seed table backup exists if the DB already had subscriptions.

3. **Confirm provider-side Products/Prices (critical).** The Products + Prices must **also** exist in Stripe/Paddle/LemonSqueezy. Your local records only store the `price_id`; they don't create the provider object. A plan that exists in your DB but not in the gateway will **500 at checkout**.

   - ✅ Each DB plan maps to a real provider-side Product/Price.

4. **Map feature gating.** Map each plan to the features it unlocks (character counts, seats, API calls, branding removal). Most apps store this as JSON on the plan row — document the schema in `Admin-Local/1-Project/1-Info/billing-features.md`.

   - ✅ The admin lists all tiers with correct prices; `\App\Models\Plan::all()->pluck('stripe_id')` returns non-null Price IDs; `/pricing` renders every tier correctly.

</Steps>

### 9. Set up webhooks (MUST)

Register the endpoint, store the signing secret, and confirm signature verification — the security-critical step.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns the payment-provider account, login, secret values, and any live-money decision. 🤖 With an authorized browser/API session, the agent may register the endpoint and event subscriptions, then confirms the verification code and runs the `stripe trigger` tests. If the dashboard asks for a password, 2FA, live-mode confirmation, or payment-account verification, pause for the user.
:::

<Steps>

1. **Check the admin panel.** Many apps expose `Settings → Webhooks` or `Integrations → Stripe` with the URL + secret pre-wired. If present, configure there.

   - ✅ The admin webhook surface is used if it exists.

2. **Register the endpoint.** Stripe Dashboard → Developers → Webhooks → Add endpoint → `https://<domain>/stripe/webhook` (confirm with `php artisan route:list | grep stripe`). Subscribe to the minimum set:
   - `checkout.session.completed`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `customer.subscription.trial_will_end`

   - ✅ The endpoint is registered and subscribed to the minimum event set.

3. **Store the signing secret.** Fill the `STRIPE_WEBHOOK_SECRET=whsec_…` placeholder in the production `.env` via your secrets manager.

   - ✅ The signing secret is stored via the secrets manager.

4. **Confirm signature verification (critical security step).** Cashier does this automatically via its `WebhookController`. A custom handler **must** call:

   ```php
   \Stripe\Stripe::setApiKey(config('cashier.secret'));
   $event = \Stripe\Webhook::constructEvent(
       $request->getContent(),
       $request->header('Stripe-Signature'),
       config('cashier.webhook.secret')
   );
   ```

   A handler that trusts unverified POST bodies lets any attacker upgrade themselves to enterprise for free.

   - ✅ Signature verification runs on every webhook (Cashier or `constructEvent`).

5. **Test locally.**

   ```bash
   stripe listen --forward-to http://<project>.test/stripe/webhook
   stripe trigger checkout.session.completed
   # Expected: handler runs, signature verifies, subscription row created/updated
   ```

   - ✅ The triggered event runs the handler, verifies the signature, and updates a row.

6. **Add alerting.** Webhook failures are silent (users pay, your DB doesn't know). Add a Sentry alert for signature failures and 5xx from `/stripe/webhook` (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/) for Sentry setup).

   - ✅ The Stripe endpoint shows "200 OK" for recent deliveries; `stripe trigger invoice.payment_failed` flips a row to `past_due`; Sentry receives a test error on a deliberately invalid signature.

</Steps>

### 10. Configure tax & invoicing (SHOULD)

Pick one tax approach, then verify it on real test purchases.

<Steps>

1. **Pick a tax approach.**

   | Approach | Cost | Coverage | Best for |
   |---|---|---|---|
   | **Stripe Tax** (auto) | 0.5%/txn | 50+ countries, auto VAT/GST/sales tax | Any SaaS selling internationally |
   | **Paddle as MoR** | ~5% + $0.50 | All countries, remits for you | Indie teams wanting zero tax burden (replaces Stripe) |
   | **Manual tax tables** | Free | Only what you configure | Single-country, single-rate |
   | **No tax collection** | Free | N/A | Pre-revenue MVPs (may be illegal past thresholds) |

   - ✅ A tax approach is chosen.

2. **Enable Stripe Tax (recommended default).** Enable at Dashboard → Tax → Settings, then in the Cashier checkout:

   ```php
   $user->newSubscription('default', $priceId)
       ->checkout([
           'automatic_tax' => ['enabled' => true],
           'customer_update' => ['address' => 'auto'],
       ]);
   ```

   For EU B2B, collect VAT IDs so Stripe applies the reverse charge — add `tax_id_collection: ['enabled' => true]` (Cashier 14+). For invoices: Stripe-hosted PDFs come free via `$user->invoice()->download()`; for a branded template, `php artisan vendor:publish --tag=cashier-views` and edit `receipt.blade.php`; if you legally need sequential gapless numbering, generate it on the `invoice.payment_succeeded` webhook.

   - ✅ A VAT-registered EU test purchase shows 0% VAT with a "reverse charge" note; a US purchase shows correct state tax; the invoice PDF downloads with your branding.

</Steps>

### 11. Configure dunning & failed payments (SHOULD)

Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.

<Steps>

1. **Enable Smart Retries.** Stripe Dashboard → Settings → Billing → Subscriptions and emails → "Manage failed payments" → enable **Smart Retries**; set the max retry period (3 weeks typical, 7 days minimum).

   - ✅ Smart Retries are enabled with a retry window set.

2. **Set a grace period** before cancellation.

   | Grace period | Use case |
   |---|---|
   | 3 days | High-churn, low-ARPU consumer |
   | 7 days | Standard SaaS default |
   | 14 days | B2B, ARR > $500 |

   - ✅ A grace period is set for the product's profile.

3. **Enable email notifications.** Stripe's branded dunning emails (Dashboard → Settings → Emails) **or** handle in Laravel from the `invoice.payment_failed` webhook: `$user->notify(new PaymentFailedNotification($invoice));`

   - ✅ Failed-payment emails are wired (Stripe or Laravel).

4. **Document the post-failure behavior.**
   - **Soft downgrade** (recommended) — subscription → `past_due`, feature gates check `$user->subscribed() && !$user->subscription()->pastDue()`, user sees a billing banner + limited access. Easier recovery.
   - **Hard cancel** — subscription deleted, user drops to free. Cleaner, harder to win back.

   - ✅ The chosen post-failure behavior is documented.

5. **Test the failed-payment path.** In test mode use card `4000 0000 0000 0341` (attaches but fails on charge) to walk failed webhook → `past_due` → dunning emails → grace period → cancellation.

   - ✅ A test-mode failed renewal triggers `invoice.payment_failed`; the user gets the email; after the grace period the DB status flips to `canceled` and access revokes.

</Steps>

### 12. Document the payment lifecycle (SHOULD)

The goal: future-you (or a support agent at 2 AM) can look up any subscription's state and know what should happen next.

<Steps>

1. **Write the lifecycle doc.** Create `Admin-Local/1-Project/1-Info/billing-lifecycle.md` with the state machine, a test matrix, alert rules, and a runbook.

   ```mermaid
   stateDiagram-v2
     [*] --> trialing: checkout (trial_days > 0)
     [*] --> active: checkout (trial_days == 0)
     trialing --> active: trial end + payment success
     trialing --> canceled: trial end + no card
     active --> past_due: invoice.payment_failed
     past_due --> active: retry success
     past_due --> canceled: grace expired
     active --> canceled: user cancels → period end
     canceled --> active: user resubscribes
   ```

   - ✅ The lifecycle doc exists with the state diagram.

2. **Record the test matrix** — for each transition, how to reproduce it in Stripe test mode.

   | Transition | Reproduce (test mode) |
   |---|---|
   | new → trialing | Checkout with `trial_days=7`, card `4242…4242` |
   | trialing → active | `stripe trigger invoice.payment_succeeded` |
   | active → past_due | Card `4000…0341` on renewal, then `stripe trigger invoice.payment_failed` |
   | past_due → canceled | Wait out grace, or `stripe trigger customer.subscription.deleted` |
   | canceled → active | Same user resubscribes |

   - ✅ Every test-matrix transition has been executed once.

3. **Add the Sentry alert rules** (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/)) — a `past_due` spike (>5 in 1 hour = payment processing broke); any `SignatureVerificationException` (someone probing, or your secret rotated); a churn threshold (>3% cancel in 24 hours = check for an outage or bad deploy). Append a "what to do when" runbook for the common support cases ("I paid but can't access", refund requests, stuck renewals).

   - ✅ The 3 Sentry rules are active and one has been test-fired.

</Steps>

## Checklist

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

- [ ] **🔀 At least one gateway connected** — test payment succeeds and a declined card is rejected.
- [ ] **👤 Billing model decision record** filled in.
- [ ] **🔀 Plans exist in both the DB and the provider dashboard** — `/pricing` renders correctly.
- [ ] **🔀 Webhook endpoint returns 200** — signature verification confirmed.
- [ ] **🔀 Tax approach chosen** — Stripe Tax (if applicable) verified on EU + US test purchases.
- [ ] **🔀 Dunning configured + tested** — post-failure behavior documented.
- [ ] **🤖 `billing-lifecycle.md` written** — state machine, test matrix, and alert rules.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the billing model, active gateways, non-secret provider/product/price IDs, webhook endpoint paths, mode per environment, and vault item pointers.

:::next[Next step]
[Email infrastructure](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/04-email/)
:::

# 3 · Payments & billing

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/03-payments-billing/

## TL;DR

**Objective** — choose a payment approach from the gateway matrix (Stripe built-in vs from-scratch, PayPal, Tap for MENA, LemonSqueezy as Merchant of Record), then add the production billing depth — model, plans, verified webhooks, tax, dunning, and lifecycle docs — so billing goes from "a card can charge" to production-ready.

**Steps at a glance:**
1. **Choose a payment approach** — Pick at least one. Stripe + PayPal is the most common combination; add Tap
   for GCC markets, or LemonSqueezy to offload tax compliance entirely.
2. **Configure Stripe — CodeCanyon built-in** — No custom code — the app already has the Stripe module wired.
   Paste keys, test, and go live.
3. **Integrate Stripe — from scratch via Cashier** — Skip this if the CodeCanyon built-in above applies.
   Otherwise wire Cashier end-to-end.
4. **Set up PayPal (SHOULD — broad global coverage)** — Add PayPal for global reach and buyer trust.
5. **Set up Tap Payments for MENA** — Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets.
   Approval takes 1–3 business days.
6. **Set up LemonSqueezy — Merchant of Record** — LemonSqueezy is the legal seller: they handle all tax
   compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50).
7. **Assess the billing model** — Answer these before configuring plans anywhere — wrong answers cascade into
   every later task. Stripe Products/Prices are hard to rename after customers subscribe, and
   proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.
8. **Set up subscription plans** — Define tiers/prices/features in the admin panel where it exists, otherwise
   seed them in code — then confirm the provider-side objects exist.
9. **Set up webhooks** — Register the endpoint, store the signing secret, and confirm signature verification —
   the security-critical step.
10. **Configure tax & invoicing** — Pick one tax approach, then verify it on real test purchases.
11. **Configure dunning & failed payments** — Dunning is the retry + notification sequence when a recurring
   charge fails. Without it, MRR silently leaks.
12. **Document the payment lifecycle** — The goal: future-you (or a support agent at 2 AM) can look up any
   subscription's state and know what should happen next.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, identity/bank verification, live-money choices, passwords, 2FA, and secret values. With an authorized browser/API session, the agent drives non-secret provider-console work: create developer apps after the account exists, register webhook endpoints/events, configure approved test products/tax/dunning settings, wire env placeholders, install Cashier when needed, seed plans, and run `stripe trigger` tests. Pause only at password/secret/2FA/payment-account-verification/live-mode gates.

**Done when** at least one gateway is connected with a successful test charge and a rejected decline, plans exist in both the DB and the provider, the webhook endpoint returns 200 with verified signatures, and tax/dunning/lifecycle are configured and documented. &nbsp;·&nbsp; **⏱ ~2–4 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards/keys, 🤖 Cashier + seeders + tests).
:::

## Background

Payment configuration is two jobs: **(1)** establish or authorize the external account(s) and secret material, then **(2)** wire the non-secret provider objects, keys, webhook endpoint, and app code — and then take billing from "a card can charge" to "subscriptions, webhooks, tax, dunning, and lifecycle are production-ready."

Read `Zaj-PROJECT.md` before provider work so the environment URLs, gateway choices, billing model, non-secret provider IDs, webhook endpoint paths, and vault pointers come from one place. Update it after each provider is verified; secrets, signing secrets, and live keys stay only in the vault/provider dashboard.

:::caution[Check the admin panel first]
CodeCanyon SaaS templates almost always ship a built-in payment manager (`Settings → Payment Setting`) and a plans manager (`Settings → Plans`). Configure there when it exists — it is faster and authoritative. Only fall back to code when no admin surface exists.
:::

## Steps

### 1. Choose a payment approach

Pick at least one. Stripe + PayPal is the most common combination; add Tap for GCC markets, or LemonSqueezy to offload tax compliance entirely.

:::note[Who does this]
👤 **User** decides which gateway(s) to run — a business/scope decision based on markets and tax tolerance.
:::

<Steps>

1. **Pick the approach(es)** from the matrix.

   | Approach | Best for | Fee | Tax handling |
   |---|---|---|---|
   | **Stripe (CodeCanyon built-in)** | Apps that ship a Stripe module — just paste keys | ~3% | Yours (or Stripe Tax) |
   | **Stripe (from scratch)** | Apps with no Stripe module — via Laravel Cashier | ~3% | Yours |
   | **PayPal** | Global coverage, buyer trust | 2.9% + $0.30 | Yours |
   | **Tap Payments** | MENA region (Mada, KNET, Benefit) | 2.75% + AED 1.00 | Partial (VAT config) |
   | **LemonSqueezy (MoR)** | Solo founders wanting zero tax burden | 5% + $0.50 | They handle everything |

   ```mermaid
   flowchart TD
     Q{"App ships a Stripe module?"}
     Q -- Yes --> CC["Stripe (CodeCanyon)<br/>paste keys, no code"]
     Q -- No --> S{"Want zero tax burden?"}
     S -- Yes --> LS["LemonSqueezy (MoR)"]
     S -- No --> ST["Stripe (Cashier, from scratch)"]
     CC --> M{"Selling in GCC?"}
     ST --> M
     LS --> M
     M -- "Mada / KNET needed" --> TAP["Add Tap Payments"]
     M -- No --> PP["Add PayPal for global reach"]
   ```

   - ✅ At least one approach chosen, with regional gateways added where the market demands.

</Steps>

:::tip[Stripe does not cover MENA rails]
Card-only gateways do not support Mada or KNET. Without a regional gateway you lose **80–90%** of Saudi/Kuwaiti transactions. Add Tap if those markets matter.
:::

Whichever gateway you pick, the object-creation steps below can be automated rather than clicked.

:::note[Stripe MCP automation]
With the Stripe MCP server connected, create products/prices from your AI assistant instead of the dashboard — e.g. *"create a product 'Pro' with a $19 monthly price"*, *"list all products and prices to verify"*, or *"create a 20%-off-3-months coupon"*. Works for every gateway section below where you create or verify Stripe objects.
:::

### 2. Configure Stripe — CodeCanyon built-in (recommended where available)

No custom code — the app already has the Stripe module wired. Paste keys, test, and go live.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns account login, key creation/copy, secret entry, real purchase/refund authorization, and live-key cutover. 🤖 With an authorized browser session, the agent can drive non-secret panel settings, verify product/price/webhook state, and collect evidence without reading secret values.
:::

<Steps>

1. **Toggle Stripe on and paste the test keys.** Log in as Super Admin → **Settings → Payment Setting → Stripe** → Stripe **ON** → paste the **Stripe Key** (`pk_test_…`) and **Stripe Secret Key** (`sk_test_…`), then **Save**.

   - ✅ Stripe is toggled on with the test keys saved.

2. **Run a test purchase.** Log in as a test user → Pricing → pick a plan → pay with `4242 4242 4242 4242` (CVC `123`, expiry `12/34`, ZIP `12345`). Verify the user upgrades and the transaction appears in the Stripe Dashboard.

   - ✅ The test purchase upgrades the user and shows in the Stripe Dashboard.

3. **Run a decline test.** Pay with `4000 0000 0000 0002` → error message shown, user **not** upgraded.

   - ✅ The declined card errors and does not upgrade the user.

4. **Confirm branding.** The app logo, brand colors, and business name appear during checkout and on the receipt email.

   - ✅ Checkout and the receipt are on-brand.

5. **Go live.** Swap sandbox keys for live keys (Stripe Dashboard → Live mode → Developers → API keys), make a small real purchase ($1–5), verify in the Live dashboard, then refund it.

   - ✅ A small live purchase succeeds and is refunded.

</Steps>

:::note[Webhooks often optional here]
Many CodeCanyon SaaS templates with a built-in Stripe module use a **redirect (hosted-checkout) pattern**, so webhooks are **not** required for basic one-off purchases. Confirm yours by checking whether the success path reads the return redirect vs. a webhook event. If you add subscriptions or custom post-payment logic, wire webhooks per [section 9](#9-set-up-webhooks-must).
:::

### 3. Integrate Stripe — from scratch via Cashier (only if no built-in module)

Skip this if the CodeCanyon built-in above applies. Otherwise wire Cashier end-to-end.

<Steps>

1. **Install Cashier.**

   ```bash
   composer require laravel/cashier
   php artisan migrate
   # Verify: php artisan migrate:status | grep cashier  → all "Ran"
   # Expected: Cashier migrations show "Ran"
   ```

   - ✅ Cashier is installed and its migrations have run.

2. **Configure env and publish config.** Confirm `STRIPE_KEY`, `STRIPE_SECRET`, `STRIPE_WEBHOOK_SECRET` are set.

   ```bash
   php artisan vendor:publish --tag="cashier-config"
   # Expected: cashier.php published to config/
   ```

   - ✅ The Stripe env vars are set and the Cashier config is published.

3. **Add the Billable trait** to `App\Models\User`.

   ```php
   use Laravel\Cashier\Billable;

   class User extends Authenticatable
   {
       use Billable;
       // ...
   }
   ```

   - ✅ `User` uses the `Billable` trait.

4. **Add the checkout route.** Add `GET /subscribe/{plan}` that maps plan slugs to Stripe price IDs and calls `->newSubscription()->checkout()`.

   - ✅ `/subscribe/{plan}` resolves plan slugs to price IDs and starts checkout.

5. **Add the billing portal.** Add `GET /billing` calling `->redirectToBillingPortal()`; enable the portal at Stripe Dashboard → Settings → Billing → Customer portal.

   - ✅ `/billing` redirects to the customer portal.

6. **Add the webhook handler.** Add `POST /stripe/webhook` → `WebhookController::handleWebhook`, exclude `stripe/*` from CSRF (**Laravel 10:** `$except` in `app/Http/Middleware/VerifyCsrfToken.php`; **Laravel 11+:** `$middleware->validateCsrfTokens(except: ['stripe/*'])` in `bootstrap/app.php`), and optionally extend Cashier's `WebhookController`.

   - ✅ The webhook route is wired and excluded from CSRF.

7. **Add subscription checks.** Use `$user->subscribed('default')`, `$user->subscribedToPrice()`, `$user->onTrial()`; add an `EnsureSubscribed` middleware for gated routes.

   - ✅ Subscription gating works via Cashier helpers + middleware.

8. **Test and commit.** Run `/subscribe/basic-monthly` with `4242 4242 4242 4242`; test the portal at `/billing`; run `stripe listen --forward-to localhost:8000/stripe/webhook`.

   ```bash
   git add composer.json composer.lock database/ app/ routes/ config/
   git commit -m "feat(payments): integrate Stripe via Laravel Cashier"
   # Expected: the Cashier integration is committed
   ```

   - ✅ Checkout, portal, and webhook forwarding work, and the integration is committed.

</Steps>

### 4. Set up PayPal (SHOULD — broad global coverage)

Add PayPal for global reach and buyer trust.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns PayPal account creation, business verification, bank/payout setup, password/2FA, and all secrets. 🤖 With an authorized browser/API session, the agent may create developer apps, register non-secret webhook endpoints/events, create sandbox test accounts, record IDs, and verify configuration. Pause for identity, banking, secret-copy, or live-money decisions.
:::

<Steps>

1. **Create and verify a business account.** Sign up at [paypal.com/business](https://www.paypal.com/business), complete the business profile (legal name, category Software/Technology, address), add a bank account, and finish identity verification until the profile shows **Verified**.

   - ✅ The PayPal business profile shows **Verified**.

2. **Create the API apps.** At [developer.paypal.com](https://developer.paypal.com/) → Apps & Credentials, create a **Sandbox** app (`[PROJECT] Development`, Merchant) and copy the Client ID (`AW…`) + Secret (`EJ…`); switch to **Live** and create `[PROJECT] Production`, copy Client ID (`AR…`) + Secret (`ES…`).

   - ✅ Sandbox and Live Client IDs + Secrets are copied.

3. **Register webhooks.** Add `https://<selected-nonproduction-domain>/paypal/webhook` (sandbox app) and `https://<production-domain>/paypal/webhook` (live app); subscribe to payment-capture and subscription events; copy each Webhook ID.

   - ✅ Both webhook endpoints are registered and the Webhook IDs copied.

4. **Create sandbox test accounts.** A Business (Seller) account ($5000) and a Personal (Buyer) account ($1000).

   - ✅ Sandbox seller + buyer accounts exist.

5. **Create subscription products** (if recurring) — Products & Subscriptions → create a Service/SaaS product, add Monthly and Yearly billing plans, note the Plan IDs (`P-…`).

   - ✅ Subscription products and Plan IDs exist (if recurring).

6. **Wire env.** Add placeholders to `.env.example` (safe to commit) and fill real values in `.env`.

   ```bash
   ## === PAYPAL ===
   PAYPAL_MODE=sandbox
   PAYPAL_SANDBOX_CLIENT_ID=
   PAYPAL_SANDBOX_CLIENT_SECRET=
   PAYPAL_LIVE_CLIENT_ID=
   PAYPAL_LIVE_CLIENT_SECRET=
   PAYPAL_SANDBOX_WEBHOOK_ID=
   PAYPAL_LIVE_WEBHOOK_ID=
   # Expected: placeholders in .env.example; real values in .env (uncommitted)
   ```

   - ✅ The PayPal env block is wired with placeholders committed, real values local.

</Steps>

### 5. Set up Tap Payments for MENA

Only needed for Saudi Arabia, Kuwait, Bahrain, or other GCC markets. Approval takes **1–3 business days**.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns signup, verification documents, banking, passwords/2FA, and legal/tax approvals. 🤖 With an authorized browser/API session, the agent may navigate Tap settings, enable approved non-secret payment methods, register webhook endpoints/events, record IDs, and verify configuration. Pause for document upload, secret-copy, payout, or live-money decisions.
:::

<Steps>

1. **Sign up and submit for verification.** At [tap.company](https://www.tap.company/) → select country → enter business info (legal name, trade-license number, category) → upload documents (Trade License/CR, Owner ID, bank statement) → submit.

   - ✅ The Tap account is submitted for verification.

2. **Copy the API keys** after approval. [dashboard.tap.company](https://dashboard.tap.company/) → Developers → API Keys; copy test (`sk_test_…`, `pk_test_…`) and live (`sk_live_…`, `pk_live_…`).

   - ✅ Test and live Tap keys are copied.

3. **Enable payment methods** per target country. Settings → Payment Methods.

   | Country | Essential methods |
   |---|---|
   | Saudi Arabia | Mada (90%+ usage), Visa/MC, Apple Pay |
   | Kuwait | KNET (80%+ usage), Visa/MC |
   | Bahrain | Benefit (70%+ usage), Visa/MC |
   | UAE | Visa/MC, Apple Pay |

   - ✅ Country-essential methods are enabled.

4. **Register webhooks.** Developers → Webhooks → `https://<domain>/tap/webhook`; subscribe to `CHARGE.CAPTURED`, `CHARGE.FAILED`, `CHARGE.REFUNDED`, `AUTHORIZE.CAPTURED`, `AUTHORIZE.VOIDED`; copy the secret.

   - ✅ The Tap webhook is registered with its secret copied.

5. **Configure VAT.** Settings → Tax Settings: SA 15%, UAE 5%, BH 10%, KW 0%, QA 0%, OM 5%.

   - ✅ VAT rates are set per country.

6. **Wire env.**

   ```bash
   ## === TAP PAYMENTS ===
   TAP_SECRET_KEY=
   TAP_PUBLISHABLE_KEY=
   TAP_WEBHOOK_SECRET=
   TAP_CURRENCY=SAR
   # Expected: the Tap env block is present with placeholders
   ```

   - ✅ The Tap env block is wired.

</Steps>

### 6. Set up LemonSqueezy — Merchant of Record (ALTERNATIVE)

LemonSqueezy is the **legal seller**: they handle all tax compliance (VAT, GST, sales tax), invoicing, and refunds, and pay you out minus their fee (5% + $0.50). Best for solo founders selling globally; **not** ideal for low-margin products, enterprise buyers, or MENA (no Mada/KNET).

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns account creation, payout/identity verification, password/2FA, secret values, and pricing/business approval. 🤖 With an authorized browser/API session, the agent may configure store metadata, create approved products/variants, register webhook endpoints/events, record IDs, and verify test checkout setup. Pause for secret-copy, payout, identity, or live-money decisions.
:::

<Steps>

1. **Create the account.** [lemonsqueezy.com](https://lemonsqueezy.com/) → Get Started Free → onboarding (Software/SaaS, revenue estimate, location) → connect payout (Stripe Connect or PayPal) → verify identity.

   - ✅ The LemonSqueezy account is created with payout connected.

2. **Configure the store.** Settings → General: Store Name, Support Email, Logo, Currency. Optional: add a custom checkout domain.

   - ✅ Store details are set.

3. **Create products.** Store → Products → New Product, Pricing Type **Subscription**, set Monthly + Yearly, add variants (Basic/Pro/Business), note Product ID + Variant IDs.

   - ✅ Subscription products with Variant IDs exist.

4. **Create the API key.** Settings → API → create (`[PROJECT] Production`, Read & Write); copy the key (`lmn_…`, shown once); note the Store ID.

   - ✅ The API key (`lmn_…`) and Store ID are stored.

5. **Register webhooks.** Settings → Webhooks → `https://<domain>/lemonsqueezy/webhook`; subscribe to `order_created`, `order_refunded`, `subscription_created`, `subscription_updated`, `subscription_cancelled`, `subscription_resumed`, `subscription_expired`, `subscription_payment_failed`; copy the signing secret.

   - ✅ The webhook is registered with its signing secret copied.

6. **Pick the integration method** by effort — simple checkout links (low), Lemon.js overlay (medium), or a Laravel package (high/full API).

   - ✅ An integration method is chosen.

7. **Wire env.**

   ```bash
   ## === LEMONSQUEEZY ===
   LEMONSQUEEZY_API_KEY=
   LEMONSQUEEZY_STORE_ID=
   LEMONSQUEEZY_SIGNING_SECRET=
   LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID=
   LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID=
   # Expected: the LemonSqueezy env block is present with placeholders
   ```

   - ✅ The LemonSqueezy env block is wired.

8. **Test the checkout.** Open the checkout link → complete a test purchase → verify the webhook fires and the user gets access.

   - ✅ A test purchase fires the webhook and grants access.

</Steps>

:::danger[Secret handling — the two highest-value keys]
Billing works with `STRIPE_SECRET` (`sk_live_*`/`sk_test_*`) and `STRIPE_WEBHOOK_SECRET` (`whsec_*`). A leaked `sk_live_*` lets an attacker issue refunds, create charges, and read customer data. Never echo the key, never `grep STRIPE .env` into chat, never paste it back "to check it". For a presence check: `grep -qE '^STRIPE_SECRET=sk_(test|live)_' .env && echo "✅ Stripe key present"` — staging should use `sk_test_`, production `sk_live_`. If a key ever lands in chat or `git log`, rotate immediately (Stripe Dashboard → Developers → API keys → Roll) — even "just the test key".
:::

### 7. Assess the billing model (MUST)

Answer these **before** configuring plans anywhere — wrong answers cascade into every later task. Stripe Products/Prices are hard to rename after customers subscribe, and proration/cancellation rules must match your Terms of Service (Phase 6 / Phase 7) or you create legal risk.

:::note[Who does this]
👤 **User** answers the billing-model questions — these are product/pricing decisions, not implementation.
:::

<Steps>

1. **Fill the billing-model decision table.**

   | Question | Your answer |
   |---|---|
   | Billing model | one-time / recurring / usage-based / hybrid |
   | Number of tiers | single / 2–3 tiers / 4+ tiers |
   | Intervals offered | monthly / monthly + yearly / + lifetime |
   | Free tier? | feature-limited / usage-limited / none |
   | Trial period | none / N days no card / N days card required |
   | Annual discount | none / X% off / X months free |
   | Currency | single / multi-currency |
   | Tax handling | inclusive / exclusive / auto (Stripe Tax) |
   | Proration on upgrade | immediate charge / next cycle / none |
   | Cancellation | at period end / immediate + refund / immediate no refund |

   - ✅ You can read this table aloud to a non-technical person and they understand the customer experience.

</Steps>

### 8. Set up subscription plans (MUST)

Define tiers/prices/features in the admin panel where it exists, otherwise seed them in code — then confirm the provider-side objects exist.

<Steps>

1. **Check the admin panel first** — look for `Settings → Plans`/`Pricing`, `Subscriptions → Plans`, `Admin → Membership Plans`, or `Finance → Subscription Plans`. If found, configure tiers/prices/features/trial/annual toggle in the UI (~5 min) and skip to substep 3.

   - ✅ Plans are configured in the admin UI (if it exists).

2. **Code fallback** — if no admin UI, seed via `database/seeders/PlansSeeder.php` using Cashier. Each plan needs `name`, `stripe_id` (the Price ID), `stripe_plan`, `billing_interval`, and a `features` JSON.

   :::caution[Back up the plans table before re-seeding a live DB]
   A seeder that `updateOrCreate`s (or worse, truncates and re-inserts) plan rows can **overwrite the `stripe_id` price mappings** that existing subscribers are billed against — silently breaking their renewals. Before running a plans seeder on **any** environment that already has subscriptions, dump the table so you can roll back. On Herd Pro / MariaDB the dump tool is `mariadb-dump` (the renamed `mysqldump`):

   ```bash
   # Back up first — rollback net before any re-seed touches existing plan rows
   mariadb-dump -u <user> -p <db> plans > /tmp/plans-backup-$(date +%F).sql   # or mysqldump on MySQL hosts
   php artisan make:seeder PlansSeeder
   php artisan db:seed --class=PlansSeeder
   # Expected: the plan rows are seeded with non-null stripe_id values; the backup SQL exists as a rollback
   ```

   Prefer an **idempotent** `updateOrCreate` keyed on a stable column (plan slug) over truncate-and-insert, so a re-run never duplicates or re-IDs rows.
   :::

   - ✅ Plans are seeded with Price IDs and a features JSON, and a pre-seed table backup exists if the DB already had subscriptions.

3. **Confirm provider-side Products/Prices (critical).** The Products + Prices must **also** exist in Stripe/Paddle/LemonSqueezy. Your local records only store the `price_id`; they don't create the provider object. A plan that exists in your DB but not in the gateway will **500 at checkout**.

   - ✅ Each DB plan maps to a real provider-side Product/Price.

4. **Map feature gating.** Map each plan to the features it unlocks (character counts, seats, API calls, branding removal). Most apps store this as JSON on the plan row — document the schema in `Admin-Local/1-Project/1-Info/billing-features.md`.

   - ✅ The admin lists all tiers with correct prices; `\App\Models\Plan::all()->pluck('stripe_id')` returns non-null Price IDs; `/pricing` renders every tier correctly.

</Steps>

### 9. Set up webhooks (MUST)

Register the endpoint, store the signing secret, and confirm signature verification — the security-critical step.

:::note[Who does this]
🔀 **Authorized agent + user gate** — 👤 **User** owns the payment-provider account, login, secret values, and any live-money decision. 🤖 With an authorized browser/API session, the agent may register the endpoint and event subscriptions, then confirms the verification code and runs the `stripe trigger` tests. If the dashboard asks for a password, 2FA, live-mode confirmation, or payment-account verification, pause for the user.
:::

<Steps>

1. **Check the admin panel.** Many apps expose `Settings → Webhooks` or `Integrations → Stripe` with the URL + secret pre-wired. If present, configure there.

   - ✅ The admin webhook surface is used if it exists.

2. **Register the endpoint.** Stripe Dashboard → Developers → Webhooks → Add endpoint → `https://<domain>/stripe/webhook` (confirm with `php artisan route:list | grep stripe`). Subscribe to the minimum set:
   - `checkout.session.completed`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `customer.subscription.trial_will_end`

   - ✅ The endpoint is registered and subscribed to the minimum event set.

3. **Store the signing secret.** Fill the `STRIPE_WEBHOOK_SECRET=whsec_…` placeholder in the production `.env` via your secrets manager.

   - ✅ The signing secret is stored via the secrets manager.

4. **Confirm signature verification (critical security step).** Cashier does this automatically via its `WebhookController`. A custom handler **must** call:

   ```php
   \Stripe\Stripe::setApiKey(config('cashier.secret'));
   $event = \Stripe\Webhook::constructEvent(
       $request->getContent(),
       $request->header('Stripe-Signature'),
       config('cashier.webhook.secret')
   );
   ```

   A handler that trusts unverified POST bodies lets any attacker upgrade themselves to enterprise for free.

   - ✅ Signature verification runs on every webhook (Cashier or `constructEvent`).

5. **Test locally.**

   ```bash
   stripe listen --forward-to http://<project>.test/stripe/webhook
   stripe trigger checkout.session.completed
   # Expected: handler runs, signature verifies, subscription row created/updated
   ```

   - ✅ The triggered event runs the handler, verifies the signature, and updates a row.

6. **Add alerting.** Webhook failures are silent (users pay, your DB doesn't know). Add a Sentry alert for signature failures and 5xx from `/stripe/webhook` (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/) for Sentry setup).

   - ✅ The Stripe endpoint shows "200 OK" for recent deliveries; `stripe trigger invoice.payment_failed` flips a row to `past_due`; Sentry receives a test error on a deliberately invalid signature.

</Steps>

### 10. Configure tax & invoicing (SHOULD)

Pick one tax approach, then verify it on real test purchases.

<Steps>

1. **Pick a tax approach.**

   | Approach | Cost | Coverage | Best for |
   |---|---|---|---|
   | **Stripe Tax** (auto) | 0.5%/txn | 50+ countries, auto VAT/GST/sales tax | Any SaaS selling internationally |
   | **Paddle as MoR** | ~5% + $0.50 | All countries, remits for you | Indie teams wanting zero tax burden (replaces Stripe) |
   | **Manual tax tables** | Free | Only what you configure | Single-country, single-rate |
   | **No tax collection** | Free | N/A | Pre-revenue MVPs (may be illegal past thresholds) |

   - ✅ A tax approach is chosen.

2. **Enable Stripe Tax (recommended default).** Enable at Dashboard → Tax → Settings, then in the Cashier checkout:

   ```php
   $user->newSubscription('default', $priceId)
       ->checkout([
           'automatic_tax' => ['enabled' => true],
           'customer_update' => ['address' => 'auto'],
       ]);
   ```

   For EU B2B, collect VAT IDs so Stripe applies the reverse charge — add `tax_id_collection: ['enabled' => true]` (Cashier 14+). For invoices: Stripe-hosted PDFs come free via `$user->invoice()->download()`; for a branded template, `php artisan vendor:publish --tag=cashier-views` and edit `receipt.blade.php`; if you legally need sequential gapless numbering, generate it on the `invoice.payment_succeeded` webhook.

   - ✅ A VAT-registered EU test purchase shows 0% VAT with a "reverse charge" note; a US purchase shows correct state tax; the invoice PDF downloads with your branding.

</Steps>

### 11. Configure dunning & failed payments (SHOULD)

Dunning is the retry + notification sequence when a recurring charge fails. Without it, MRR silently leaks.

<Steps>

1. **Enable Smart Retries.** Stripe Dashboard → Settings → Billing → Subscriptions and emails → "Manage failed payments" → enable **Smart Retries**; set the max retry period (3 weeks typical, 7 days minimum).

   - ✅ Smart Retries are enabled with a retry window set.

2. **Set a grace period** before cancellation.

   | Grace period | Use case |
   |---|---|
   | 3 days | High-churn, low-ARPU consumer |
   | 7 days | Standard SaaS default |
   | 14 days | B2B, ARR > $500 |

   - ✅ A grace period is set for the product's profile.

3. **Enable email notifications.** Stripe's branded dunning emails (Dashboard → Settings → Emails) **or** handle in Laravel from the `invoice.payment_failed` webhook: `$user->notify(new PaymentFailedNotification($invoice));`

   - ✅ Failed-payment emails are wired (Stripe or Laravel).

4. **Document the post-failure behavior.**
   - **Soft downgrade** (recommended) — subscription → `past_due`, feature gates check `$user->subscribed() && !$user->subscription()->pastDue()`, user sees a billing banner + limited access. Easier recovery.
   - **Hard cancel** — subscription deleted, user drops to free. Cleaner, harder to win back.

   - ✅ The chosen post-failure behavior is documented.

5. **Test the failed-payment path.** In test mode use card `4000 0000 0000 0341` (attaches but fails on charge) to walk failed webhook → `past_due` → dunning emails → grace period → cancellation.

   - ✅ A test-mode failed renewal triggers `invoice.payment_failed`; the user gets the email; after the grace period the DB status flips to `canceled` and access revokes.

</Steps>

### 12. Document the payment lifecycle (SHOULD)

The goal: future-you (or a support agent at 2 AM) can look up any subscription's state and know what should happen next.

<Steps>

1. **Write the lifecycle doc.** Create `Admin-Local/1-Project/1-Info/billing-lifecycle.md` with the state machine, a test matrix, alert rules, and a runbook.

   ```mermaid
   stateDiagram-v2
     [*] --> trialing: checkout (trial_days > 0)
     [*] --> active: checkout (trial_days == 0)
     trialing --> active: trial end + payment success
     trialing --> canceled: trial end + no card
     active --> past_due: invoice.payment_failed
     past_due --> active: retry success
     past_due --> canceled: grace expired
     active --> canceled: user cancels → period end
     canceled --> active: user resubscribes
   ```

   - ✅ The lifecycle doc exists with the state diagram.

2. **Record the test matrix** — for each transition, how to reproduce it in Stripe test mode.

   | Transition | Reproduce (test mode) |
   |---|---|
   | new → trialing | Checkout with `trial_days=7`, card `4242…4242` |
   | trialing → active | `stripe trigger invoice.payment_succeeded` |
   | active → past_due | Card `4000…0341` on renewal, then `stripe trigger invoice.payment_failed` |
   | past_due → canceled | Wait out grace, or `stripe trigger customer.subscription.deleted` |
   | canceled → active | Same user resubscribes |

   - ✅ Every test-matrix transition has been executed once.

3. **Add the Sentry alert rules** (see [Phase 7 · Observability](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/05-observability/)) — a `past_due` spike (>5 in 1 hour = payment processing broke); any `SignatureVerificationException` (someone probing, or your secret rotated); a churn threshold (>3% cancel in 24 hours = check for an outage or bad deploy). Append a "what to do when" runbook for the common support cases ("I paid but can't access", refund requests, stuck renewals).

   - ✅ The 3 Sentry rules are active and one has been test-fired.

</Steps>

## Checklist

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

- [ ] **🔀 At least one gateway connected** — test payment succeeds and a declined card is rejected.
- [ ] **👤 Billing model decision record** filled in.
- [ ] **🔀 Plans exist in both the DB and the provider dashboard** — `/pricing` renders correctly.
- [ ] **🔀 Webhook endpoint returns 200** — signature verification confirmed.
- [ ] **🔀 Tax approach chosen** — Stripe Tax (if applicable) verified on EU + US test purchases.
- [ ] **🔀 Dunning configured + tested** — post-failure behavior documented.
- [ ] **🤖 `billing-lifecycle.md` written** — state machine, test matrix, and alert rules.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the billing model, active gateways, non-secret provider/product/price IDs, webhook endpoint paths, mode per environment, and vault item pointers.

:::next[Next step]
[Email infrastructure](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/04-email/)
:::