SaasForgeKit Docs

Appearance

Stripe Configuration ​

This page explains Stripe connectivity for SaasForgeKit.

SaasForgeKit uses:

  • Laravel Cashier for subscriptions and checkout
  • User model as billable customer (users are Stripe customers)
  • Stripe webhooks to keep subscription and invoice events synced locally

1) Configure Stripe environment variables ​

In your .env:

env
STRIPE_KEY=pk_live_or_test_xxx
STRIPE_SECRET=sk_live_or_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

Where to get them (Stripe Dashboard):

  • STRIPE_KEY and STRIPE_SECRET: Developers -> API keys
  • STRIPE_WEBHOOK_SECRET: Developers -> Webhooks -> [your endpoint] -> Signing secret

STRIPE_KEY and STRIPE_SECRET are used by Cashier (config/cashier.php). STRIPE_WEBHOOK_SECRET secures webhook signature validation.

2) Configure webhook endpoint in Stripe ​

Create a webhook endpoint in Stripe dashboard:

text
https://your-domain.com/stripe/webhook

Why this path: Cashier is configured with CASHIER_PATH=stripe (default), so webhook endpoint is /stripe/webhook.

Events to send ​

To avoid missing anything, use the union of:

  1. App-specific events (used by SaasForgeKit listener for product/price sync + billing emails):
  • product.created
  • product.updated
  • product.deleted
  • price.created
  • price.updated
  • price.deleted
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.paid
  • invoice.payment_failed
  1. Cashier default events:
  • customer.updated
  • customer.deleted
  • payment_method.automatically_updated
  • invoice.payment_action_required
  • invoice.payment_succeeded

If you create the endpoint with php artisan cashier:webhook, Cashier will register its defaults automatically.
In SaasForgeKit, make sure the app-specific events above are also included.

After creating webhook endpoint, copy Stripe's signing secret to:

env
STRIPE_WEBHOOK_SECRET=whsec_xxx

3) Understand subscription flow ​

Customer-facing billing routes:

  • GET /billing (pricing/subscription page)
  • POST /billing/checkout (create Stripe checkout session)
  • POST /billing/portal (open Stripe billing portal)

Important behavior:

  • Billable entity is the current authenticated user.
  • Checkout success redirects back to /billing and attempts local subscription sync.
  • Billing portal is generated via Cashier for the current user.

4) Production checklist ​

  • Stripe keys set correctly (live vs test)
  • Webhook endpoint points to production URL
  • STRIPE_WEBHOOK_SECRET matches endpoint secret
  • Queue worker running in production
  • Pricing page shows products as expected
  • Checkout and portal both work end-to-end

5) Local testing tips ​

Use test keys in .env and run your app locally. For webhook testing, use Stripe CLI to forward events to local app:

bash
stripe listen --forward-to http://127.0.0.1:8000/stripe/webhook

Then copy the CLI signing secret into STRIPE_WEBHOOK_SECRET.