Skip to main content

Stripe

Stripe is the default gateway in Subscribd and the most feature-complete integration, including native proration, trial extension, and automatic tax.

Configuration

Environment variables

Checkout modes

The Stripe gateway supports two embedded checkout modes controlled by STRIPE_CHECKOUT_MODE:

Elements mode (default)

Uses Stripe’s Payment Element (SetupIntent + card form). The subscriber completes checkout in-page without leaving your application:
Use <livewire:subscribd::subscriber.checkout /> to render the embedded form.

Checkout mode

Redirects to Stripe’s hosted Checkout page. On completion, Stripe redirects back to your return_url:

Webhooks

Register the webhook endpoint

Register https://yourapp.com/subscribd/webhook/stripe as a webhook endpoint in the Stripe Dashboard. Enable the following events:
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed
  • payment_method.attached
  • payment_method.detached
  • customer.updated

Webhook signing

Copy the Signing secret from the webhook endpoint dashboard entry and set it as STRIPE_WEBHOOK_SECRET. Subscribd verifies every webhook signature — unsigned requests are rejected with 400.

Local development

Use the Stripe CLI to forward webhooks to your local environment:
Copy the CLI’s webhook signing secret (starts with whsec_) into your .env.

Automatic tax

Enable Stripe Tax to calculate tax automatically based on the customer’s location:
This requires Stripe Tax to be enabled in your Stripe account. See Tax for the full tax configuration reference.

Native proration

Stripe supports native proration. When the proration strategy is now, Subscribd forwards the proration flag to Stripe rather than computing the adjustment locally. The proration invoice appears in Stripe’s dashboard and in your subscribd_invoices table.

Trial extension

Stripe is the only gateway that supports native trial extension. When you call ExtendTrial, Subscribd pushes the new trial_end timestamp to Stripe directly:

Strong Customer Authentication (SCA)

For cards that require 3DS confirmation, CreateSubscription throws RequiresActionException. Handle it by redirecting the user to the confirmation URL:
In Elements mode, the Payment Element handles 3DS natively in-browser and this exception is not thrown.

Next steps

  • PayPal — Configure PayPal
  • Webhooks — Full webhook reference
  • Tax — Configure tax collection