如何通过Stripe与Laravel Cashier实现一次性费用加后续定期扣费

Hey there! I’ve been in your shoes dealing with Stripe’s revamped UI making it tricky to set up that one-time fee plus first month’s subscription charge. Thankfully, Laravel Cashier simplifies this workflow a ton—let’s walk through exactly how to make it work.

Instead of wrestling with Stripe’s UI, we can leverage Cashier’s API to create a subscription and attach a one-time setup fee directly in your code. This way, the user gets a single invoice covering both the setup fee and first month’s subscription, and subsequent charges will auto-process monthly as expected.

1. Confirm Cashier is Properly Configured #

First, make sure you’ve got Cashier installed and your User model uses the Billable trait:

// app/Models/User.php
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
    
    // Rest of your model logic...
}

Double-check that your .env file has your Stripe secret key and webhook secret set up correctly.

2. Create Subscription + Attach One-Time Fee #

You can handle both charges in a single operation using Cashier’s subscription builder. Here’s a practical example:

// Assume you have a Stripe price ID for your monthly subscription plan
$subscriptionPriceId = 'price_123ABC';
// One-time setup fee (in cents, e.g., $50 = 5000)
$setupFeeAmount = 5000;

// Create the subscription and add the setup fee to the initial invoice
$subscription = $user->newSubscription('main', $subscriptionPriceId)
    ->create($paymentMethodId, [
        'email' => $user->email,
    ], function ($invoice) use ($setupFeeAmount) {
        // Add the one-time setup fee as an invoice item
        $invoice->addItem([
            'price_data' => [
                'currency' => 'usd', // Adjust to your currency
                'product_data' => [
                    'name' => 'One-Time Setup Fee',
                ],
                'unit_amount' => $setupFeeAmount,
                'type' => 'one_time',
            ],
        ]);
    });

This code creates the user’s subscription and injects the setup fee into the first invoice. The user will be charged both amounts immediately, and Stripe will automatically handle monthly subscription charges moving forward.

3. Verify Auto-Renewal Behavior #

Once the subscription is active, you don’t need extra code for monthly charges—Stripe takes care of that. You can check subscription status or next payment details with Cashier’s helper methods:

// Check if the user has an active subscription
if ($user->subscribed('main')) {
    // Handle active subscription logic
}

// Get the next scheduled payment date
$nextPayment = $user->subscription('main')->nextPaymentDate();

4. Optional: Handle Subscription Changes #

If you need to let users upgrade/downgrade their plan later, Cashier makes that seamless without breaking auto-renewal:

// Swap to a different subscription price
$user->subscription('main')->swap('price_456DEF');

• Webhooks: Make sure to configure Stripe webhooks in your app (Cashier provides a dedicated /cashier/webhook route) to handle events like payment failures or subscription cancellations. This keeps your app’s subscription data in sync with Stripe.
• Currency Units: Always use the smallest unit for your currency (e.g., cents for USD) to avoid decimal errors.
• Testing: Use Stripe’s test payment methods (like 4242 4242 4242 4242) to validate the flow before going live.

内容的提问来源于stack exchange，提问作者Alex