> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Configure Stripe as your payment gateway, including checkout modes and webhook setup

# Stripe

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

## Configuration

```php theme={null}
// 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

```env theme={null}
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:

```env theme={null}
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`:

```env theme={null}
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](https://dashboard.stripe.com/webhooks). 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](https://stripe.com/docs/stripe-cli) to forward webhooks to your local environment:

```bash theme={null}
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:

```env theme={null}
STRIPE_AUTOMATIC_TAX=true
```

This requires Stripe Tax to be enabled in your Stripe account. See [Tax](/invoices/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:

```php theme={null}
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:

```php theme={null}
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](/gateways/paypal)** — Configure PayPal
* **[Webhooks](/advanced/webhooks)** — Full webhook reference
* **[Tax](/invoices/tax)** — Configure tax collection