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

// config/subscribd.php
'gateways' => [
    'stripe' => [
        'driver'         => \Pixelworxio\Subscribd\Gateways\StripeGateway::class,
        'secret'         => env('STRIPE_SECRET'),
        'publishable'    => env('STRIPE_KEY'),
        'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
        'api_version'    => env('STRIPE_API_VERSION', '2026-02-25.clover'),
        'automatic_tax'  => env('STRIPE_AUTOMATIC_TAX', false),
        'checkout' => [
            'mode'        => env('STRIPE_CHECKOUT_MODE', 'elements'),
            'success_url' => env('STRIPE_SUCCESS_URL'),
            'cancel_url'  => env('STRIPE_CANCEL_URL'),
            'return_url'  => env('STRIPE_RETURN_URL'),
        ],
    ],
],

​
Environment variables

STRIPE_KEY=pk_live_...
STRIPE_SECRET=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

​
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: 
STRIPE_CHECKOUT_MODE=elements
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: 
STRIPE_CHECKOUT_MODE=checkout
STRIPE_RETURN_URL=https://yourapp.com/billing/return

​
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: 
stripe listen --forward-to localhost/subscribd/webhook/stripe
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: 
STRIPE_AUTOMATIC_TAX=true
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: 
app(\Pixelworxio\Subscribd\Actions\ExtendTrial::class)->execute($subscription, days: 14);

​
Strong Customer Authentication (SCA)

For cards that require 3DS confirmation, CreateSubscription throws RequiresActionException. Handle it by redirecting the user to the confirmation URL: 
use Pixelworxio\Subscribd\Exceptions\RequiresActionException;

try {
    app(CreateSubscription::class)->execute($user, $plan);
} catch (RequiresActionException $e) {
    return redirect($e->redirectUrl());
}
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