How to Integrate Laravel Cashier and Stripe Payment

Laravel Cashier, the elegant bridge between your Laravel application and Stripe's robust payment infrastructure, offers a streamlined approach to managing subscriptions, payments, and customer accounts. This comprehensive guide delves into the intricacies of leveraging Cashier, covering everything from creating and updating customer profiles to handling complex billing scenarios. Forget wrestling with Stripe's API directly – let's unlock the power of seamless integration.

We'll explore the core functionalities of Laravel Cashier, showcasing its capabilities through practical examples. Whether you're a seasoned Laravel developer or just beginning your journey with subscription-based services, this guide will empower you to build sophisticated billing systems with ease.

Often, you'll need to access existing customer information within your application. Laravel Cashier provides a straightforward method to retrieve customer details using their Stripe ID. After running the Cashier migrations (a vital step that adds the stripe_id column and other essential fields to your billable model, usually your User model), you can effortlessly retrieve a customer record using Cashier::findBillable(). This function returns an instance of your billable model, allowing direct access to the associated user data.

Consider this example:

use Laravel\Cashier\Cashier;

// Retrieve the user based on their Stripe ID
$user = Cashier::findBillable('cus_XXXXXXXXXXXXXXX'); // Replace with actual Stripe ID

// Access user attributes
if ($user) {
    echo "User ID: " . $user->id . "\n";
    echo "Email: " . $user->email . "\n";
    // Access other user details as needed
} else {
    echo "User not found.\n";
}
    

This concise snippet demonstrates how to fetch a user's record using their Stripe ID. Error handling is included to gracefully manage situations where the user is not found. This approach is crucial for accessing billing information and managing subscriptions associated with a specific customer. The returned $user object is fully populated, providing immediate access to all user attributes alongside their billing details.

Creating Stripe Customers: Beyond Subscriptions

While subscriptions are a cornerstone of many businesses using Stripe and Cashier, there are scenarios where you need to create Stripe customers without immediately establishing a subscription. Perhaps you're collecting payment information upfront or handling one-time purchases. Cashier doesn't explicitly offer a "create customer without subscription" function, but we can achieve this elegantly using Stripe's API directly while maintaining the integrity of your Cashier integration.

Let’s illustrate this with an example where a user provides their payment details during the registration process but doesn't sign up for a recurring subscription yet.

use Laravel\Cashier\Cashier;
use Stripe\Stripe;
use Stripe\Customer;

// Set your Stripe Secret Key (ensure this is securely managed, e.g., in environment variables)
Stripe::setApiKey(config('cashier.secret'));

// Function to create a Stripe customer
function createStripeCustomer($user, $paymentMethodId) {
    try {
        $customer = Customer::create([
            'email' => $user->email, // Using the user's email address
            'payment_method' => $paymentMethodId, // The payment method ID received from Stripe's elements
            'invoice_settings' => [
                'default_payment_method' => $paymentMethodId, // Automatically sets this as default
            ],
        ]);

        // Update the user's Stripe ID
        $user->stripe_id = $customer->id;
        $user->save();

        return $customer;

    } catch (\Exception $e) {
        // Handle Stripe API errors appropriately (log, display error message, etc.)
        Log::error('Stripe Customer Creation Error: ' . $e->getMessage());
        return null;
    }
}


// Example usage (assuming you have a registered user and a payment method ID)
$user = User::find(1); // Replace with your user ID
$paymentMethodId = request('paymentMethodId'); // Get payment method ID from your form submission

$customer = createStripeCustomer($user, $paymentMethodId);

if ($customer) {
    // Customer created successfully, perform any necessary actions
    // e.g., send confirmation email, redirect to dashboard
} else {
    // Handle customer creation failure
}
    

This robust function encapsulates the Stripe customer creation logic, promoting code reusability and maintainability. It leverages error handling to manage potential exceptions during the API interaction and updates the user's stripe_id in your database for subsequent operations. Note the crucial step of securely managing your Stripe secret key—ideally through environment variables rather than hardcoding it directly into your application.

Managing Customer Details: Updates and Beyond

Once a customer is created, you'll need mechanisms to update their information, such as their email address or billing address. Cashier simplifies these updates by providing a pathway to leverage Stripe's API directly. This allows for maintaining consistency and using the features already available within Stripe.

Here’s an example showcasing how to update a customer's email address:

use Stripe\Stripe;
use Stripe\Customer;

Stripe::setApiKey(config('cashier.secret'));

$user = Cashier::findBillable('cus_XXXXXXXXXXXXXXX');  //Fetch the user object using their Stripe ID.
if($user){
    try {
        $customer = Customer::retrieve($user->stripe_id);
        $customer->email = 'new_email@example.com';
        $customer->save();
        //Update your database accordingly if you need to store the email address there as well.
    } catch (\Exception $e) {
        Log::error('Stripe Customer Update Error: ' . $e->getMessage());
    }
}
    

This snippet clearly demonstrates how to retrieve an existing customer, modify their email address, and persist the changes using Stripe's API. Remember to adapt this approach for other customer details you might need to update. Always include comprehensive error handling to manage potential issues during the update process.

Handling Single Charges: Streamlining One-Time Payments

For scenarios requiring a single payment, such as a one-time purchase, Cashier provides a straightforward approach to handling charges. The integration leverages Stripe’s capabilities for creating charges, linking them to customers, and managing the entire process through a concise interface.

use Laravel\Cashier\Cashier;
use Stripe\Stripe;
use Stripe\Charge;

Stripe::setApiKey(config('cashier.secret'));

$user = Cashier::findBillable('cus_XXXXXXXXXXXXXXX'); // Retrieve the user

if ($user) {
    try {
        $charge = Charge::create([
            'amount' => 1000, // Amount in cents
            'currency' => 'usd',
            'customer' => $user->stripe_id,
            'description' => 'One-time purchase',
        ]);

        // Handle the successful charge (e.g., send confirmation)
        // Access charge details using $charge->id, $charge->status, etc.

    } catch (\Exception $e) {
        Log::error('Stripe Charge Creation Error: ' . $e->getMessage());
        // Handle the error (e.g., display an error message)
    }
}
    

This illustrates creating a single charge directly through Stripe’s API within the Cashier context. This maintains clarity and integration with the rest of your billing system. Remember to meticulously handle potential exceptions from the Stripe API, logging errors for debugging and providing appropriate feedback to the user.

Conclusion

Laravel Cashier significantly streamlines the integration of Stripe into your Laravel applications. Its intuitive API empowers you to handle various billing scenarios efficiently, from creating customers and managing subscriptions to handling single charges and updating customer details. By understanding the core functionalities and leveraging the examples provided in this guide, you can build robust and scalable payment systems for your application, confidently integrating the power of Stripe with the elegance of Laravel. Remember to always prioritize secure handling of sensitive information like API keys and payment details.