Laravel + Stripe Integration

composer require laravel/cashier:^16.6
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate

STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRO_PRICE_ID=price_...

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Cashier\Billable;

class User extends Model
{
    use Billable;
}

3. Define app routes and secure Cashier's webhook

Checkout and portal routes should be authenticated. Cashier 16.6 automatically registers POST /stripe/webhook and applies signature verification when STRIPE_WEBHOOK_SECRET is configured, so do not register another route at the same URI.

use App\Http\Controllers\Billing\CheckoutController;
use Illuminate\Support\Facades\Route;

Route::middleware(['auth'])->group(function (): void {
    Route::post('/billing/checkout', [CheckoutController::class, 'store'])
        ->name('billing.checkout');

    Route::get('/billing/portal', [CheckoutController::class, 'portal'])
        ->name('billing.portal');

    Route::get('/billing/success', [CheckoutController::class, 'success'])
        ->name('billing.success');
});

Stripe cannot send a Laravel CSRF token. In a fresh Laravel 12 application, exclude only the webhook URI in bootstrap/app.php. If the application retained Laravel 10's structure after upgrading, put the same exact URI in app/Http/Middleware/VerifyCsrfToken.php.

// Fresh Laravel 12 structure: bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->validateCsrfTokens(except: ['stripe/webhook']);
})

// Upgraded Laravel 10 structure: VerifyCsrfToken.php
protected $except = ['stripe/webhook'];

4. Create the checkout controller with API failure handling

The controller creates a hosted Stripe Checkout session and redirects the customer to it. Stripe handles payment authentication on the hosted page; your application handles API failures here and completed or expired sessions through webhooks.

namespace App\Http\Controllers\Billing;

use App\Http\Controllers\Controller;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Stripe\Exception\ApiErrorException;

class CheckoutController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $user = $request->user();

        try {
            return $user
                ->newSubscription('default', config('services.stripe.pro_price_id'))
                ->allowPromotionCodes()
                ->checkout([
                    'success_url' => route('billing.success').'?session_id={CHECKOUT_SESSION_ID}',
                    'cancel_url' => route('billing.portal'),
                    'customer_update' => [
                        'address' => 'auto',
                        'name' => 'auto',
                    ],
                ])
                ->redirect();
        } catch (ApiErrorException $exception) {
            report($exception);

            return back()
                ->with('billing_error', 'Stripe could not start checkout. Please try again or contact support.');
        }
    }

    public function portal(Request $request): RedirectResponse
    {
        try {
            return $request->user()->redirectToBillingPortal(route('billing.success'));
        } catch (ApiErrorException $exception) {
            report($exception);

            return back()
                ->with('billing_error', 'Stripe could not open the billing portal. Please try again.');
        }
    }

    public function success(): RedirectResponse
    {
        return redirect()
            ->route('dashboard')
            ->with('status', 'Your billing details are being confirmed by Stripe.');
    }
}

5. Keep Cashier's webhook and queue application-specific work

Never mark a subscription active only because the browser returned from Checkout. Cashier's controller verifies the signature and synchronizes supported customer and subscription events. Listen for WebhookReceived only for application-specific work such as fulfilling an order or recording a refund; do not replace Cashier's route or duplicate its subscription synchronization.

The persistence invariant: the database, not the application code, must enforce that a Stripe event ID is stored at most once. A unique index on stripe_id is what makes the deduplication correct. Checking exists() and then calling create() is a read-then-write race: two concurrent deliveries of the same event can both pass the check before either inserts, and both will run the side effects. Without the unique index, the job below silently loses its protection.

Schema::create('stripe_events', function (Blueprint $table): void {
    $table->id();
    $table->string('stripe_id')->unique();
    $table->string('type')->index();
    $table->json('payload');
    $table->timestamp('processed_at')->nullable();
    $table->timestamps();
});

Register a listener that dispatches a queued job only for the application-specific events below. The job claims each event with one atomic insertOrIgnore() inside a transaction. On a duplicate the unique index rejects the row, the call affects zero rows, and application handlers are skipped.

use App\Jobs\ProcessStripeEvent;
use App\Jobs\ProvisionSynchronizedSubscription;
use Illuminate\Support\Facades\Event;
use Laravel\Cashier\Events\WebhookHandled;
use Laravel\Cashier\Events\WebhookReceived;

Event::listen(WebhookReceived::class, function (WebhookReceived $event): void {
    if (! in_array($event->payload['type'], [
        'checkout.session.completed',
        'checkout.session.expired',
        'invoice.payment_failed',
        'charge.refunded',
    ], true)) {
        return;
    }

    ProcessStripeEvent::dispatch($event->payload);
});

Event::listen(WebhookHandled::class, function (WebhookHandled $event): void {
    if ($event->payload['type'] !== 'customer.subscription.created') {
        return;
    }

    ProvisionSynchronizedSubscription::dispatch($event->payload);
});

namespace App\Jobs;

use App\Models\StripeEvent;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;

class ProcessStripeEvent implements ShouldQueue
{
    use Queueable;

    /**
     * @param array $payload
     */
    public function __construct(public array $payload) {}

    public function handle(): void
    {
        DB::transaction(function (): void {
            $claimed = StripeEvent::query()->insertOrIgnore([
                'stripe_id' => $this->payload['id'],
                'type' => $this->payload['type'],
                'payload' => json_encode($this->payload, JSON_THROW_ON_ERROR),
                'created_at' => now(),
                'updated_at' => now(),
            ]);

            if ($claimed === 0) {
                return;
            }

            match ($this->payload['type']) {
                'checkout.session.completed' => $this->handleCheckoutCompleted($this->payload['data']['object']),
                'checkout.session.expired' => $this->recordExpiredCheckout($this->payload['data']['object']),
                'invoice.payment_failed' => $this->recordFailedPayment($this->payload['data']['object']),
                'charge.refunded' => $this->recordRefund($this->payload['data']['object']),
                default => null,
            };

            StripeEvent::query()
                ->where('stripe_id', $this->payload['id'])
                ->update(['processed_at' => now()]);
        });
    }
}

Implement the four private handler methods with your own database-only domain changes and use a real asynchronous queue in production. In Cashier 16.6, WebhookHandled is dispatched only when Cashier has a matching controller method; it is not dispatched for the four events handled by this job. A subscription Checkout also produces a separately delivered customer.subscription.created event, and Stripe does not guarantee that it arrives before checkout.session.completed. Keep the Checkout handler scoped to session data. Put work that requires Cashier's local subscription in the filtered WebhookHandled listener shown above, after Cashier synchronizes customer.subscription.created, and deduplicate that job by its own Stripe event ID. Let exceptions escape so Laravel's queue retry policy can retry the job; the transaction rolls back both the claim and database writes. insertOrIgnore() bypasses Eloquent casts and automatic timestamps, so encode the payload and set timestamps explicitly. A transaction cannot undo email or another API call, so dispatch external side effects after commit through an outbox keyed by stripe_id.