How to handle recurring payments with Laravel Cashier?

Install Laravel Cashier via Composer and configure migration and Billable trait. 2. Create subscription plans in Stripe Dashboard and note plan IDs. 3. Collect payment method using Stripe Checkout and store it via setup intent. 4. Subscribe user to a plan using newSubscription() and default payment method. 5. Manage subscription lifecycle with methods like subscribed(), cancel(), resume(), and swap(). 6. Handle Stripe webhooks to sync events like invoice.paid or payment_failed by setting up webhook routes and using event listeners. 7. Retrieve invoices via $user->invoices() and provide Stripe Customer Portal for user billing management. Always test in Stripe Test Mode, use Cashier’s helper methods, rely on webhooks for accuracy, and consider Cashier Paddle for alternative payment provider integration.

Handling recurring payments in Laravel using Laravel Cashier is straightforward once you understand the flow and setup. Laravel Cashier is a wrapper around payment providers like Stripe and Braintree, making it easy to manage subscriptions, invoices, and payment methods. Here’s how to set up and manage recurring payments effectively.

1. Install and Configure Laravel Cashier

First, install Cashier via Composer. For Stripe (the most common option):

composer require laravel/cashier

Next, publish and run the migration to add the required columns to your users table (or billable model):

php artisan cashier:install
php artisan migrate

Then, add the Billable trait to your user model (or any model that will handle payments):

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Set your Stripe keys in .env:

STRIPE_KEY=your_stripe_key
STRIPE_SECRET=your_stripe_secret

2. Create Subscription Plans in Stripe

Laravel Cashier doesn't define pricing plans—it manages subscriptions to plans you've already created in Stripe.

• Go to the Stripe Dashboard
• Navigate to Products & Services > Plans
• Create a recurring plan (e.g., $10/month)
• Note the plan ID (e.g., price_monthly_10)

You can create multiple plans for different tiers (basic, premium, etc.).

3. Subscribe a User to a Plan

Before creating a subscription, the user must have a payment method (usually a credit card). You can collect and store their payment method using Stripe Checkout or Stripe Elements.

Add Payment Method (Example with Stripe Checkout)

use Laravel\Cashier\Cashier;

return view('checkout', [
    'intent' => $user->createSetupIntent()
]);

In your Blade template, use Stripe.js to collect card details and confirm the setup:

<input id="card-holder-name" type="text">
<div id="card-element"></div>
<button id="card-button">Add Payment Method</button>

<script src="https://js.stripe.com/v3/"></script>
<script>
    const stripe = Stripe('{{ env("STRIPE_KEY") }}');
    const elements = stripe.elements();
    const cardElement = elements.create('card');

    cardElement.mount('#card-element');

    const cardButton = document.getElementById('card-button');
    cardButton.addEventListener('click', async () => {
        const { setupIntent, error } = await stripe.confirmCardSetup(
            '{{ $intent->client_secret }}', {
                payment_method: {
                    card: cardElement,
                    billing_details: { name: document.getElementById('card-holder-name').value }
                }
            }
        );

        if (error) {
            // Show error
        } else {
            // Send payment method to server
            axios.post('/user/payment-method', {
                payment_method: setupIntent.payment_method
            });
        }
    });
</script>

Save the payment method on the user:

// In your controller
public function addPaymentMethod(Request $request)
{
    $paymentMethod = $request->input('payment_method');
    $request->user()->addPaymentMethod($paymentMethod);

    // Optionally set it as default
    $request->user()->updateDefaultPaymentMethod($paymentMethod);

    return back();
}

Create the Subscription

Once a payment method exists:

$user = auth()->user();

$user->newSubscription('default', 'price_monthly_10')->create($user->defaultPaymentMethod());

This creates a recurring subscription using the user’s default payment method.

4. Handle Subscription Lifecycle

Cashier provides methods to manage subscriptions:

• Check subscription status:

  if ($user->subscribed('default')) {
      // User is active on this plan
  }

• Cancel subscription:

  $user->subscription('default')->cancel();

• Resume (if within grace period):

  $user->subscription('default')->resume();

• Change plan (swap):

  $user->subscription('default')->swap('price_annual_100');

• Bill annually vs monthly: Make sure the plan ID matches the correct interval in Stripe.

5. Handle Webhooks for Recurring Events

Stripe will send webhooks for events like invoice.paid, invoice.payment_failed, etc. You must handle these to keep your app in sync.

Add the webhook route:

Route::post('/stripe/webhook', '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook');

Cashier handles common events automatically (e.g., updating subscription status, storing invoices), but you can extend it for custom logic.

To verify webhook signatures, set the STRIPE_WEBHOOK_SECRET in .env:

STRIPE_WEBHOOK_SECRET=whsec_...

You can also listen to events in your app:

// In EventServiceProvider
protected $listen = [
    'Laravel\Cashier\Events\WebhookReceived' => [
        'App\Listeners\HandleStripeWebhook'
    ],
];

6. Display Invoices and Manage Billing

Cashier stores invoices locally. You can retrieve them:

$invoices = $user->invoices();

foreach ($invoices as $invoice) {
    echo $invoice->total(); // Format: $10.00
    echo $invoice->url; // PDF URL
}

Provide a billing portal (Stripe Customer Portal):

$portalSession = $user->stripe()->billingPortal->sessions->create([
    'customer' => $user->stripe_id,
    'return_url' => route('home'),
]);

return redirect()->to($portalSession->url);

This lets users update payment methods, view invoices, and manage subscriptions.

Final Notes

• Always test with Stripe Test Mode.
• Use Cashier’s built-in helpers like subscribed(), onTrial(), onGracePeriod().
• Never rely solely on local state—webhooks are essential for accuracy.
• Consider using Cashier Paddle if you prefer Paddle over Stripe.

With proper setup, Laravel Cashier makes recurring payments reliable and easy to manage. Basically just connect Stripe, store payment methods, subscribe users, and let webhooks keep everything in sync.

The above is the detailed content of How to handle recurring payments with Laravel Cashier?. For more information, please follow other related articles on the PHP Chinese website!