#Laravel Stripe

A PHP/Laravel client for the Stripe API. Covers customers, subscriptions, products, prices, checkout sessions, the billing portal, invoices, payment intents and events through a simple API built on Laravel's Http client — plus verification of Stripe's webhook signatures.

No stripe/stripe-php dependency: just illuminate/http, so responses come back as plain arrays and are trivial to fake in tests.

#Features

• Customers: list, get, create, update, delete, find by email
• Subscriptions: list, get, create, update, cancel (now or at period end), resume, list for a customer
• Products: list, get, create, update, archive, delete
• Prices: list, get, create, update, archive
• Checkout: create a session, get, list, expire, line items
• Billing portal: create a customer portal session
• Invoices: list, get, list for a customer, pay, send, void
• Payment intents: list, get, create, update, confirm, capture, cancel
• Events: list, get, filter by type (the 30-day log behind webhooks)
• Webhooks: Stripe-Signature verification (HMAC-SHA256, replay-window check, rotation-safe)
• Pin an API version with a single env var
• Throws StripeException (with the original error body, code, type and param) on any non-2xx response
• Throws InvalidArgumentException before hitting the API when a required field is missing

#Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-stripe

Publish the config file:

php artisan vendor:publish --tag=stripe-config

Set your credentials in .env:

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

Find the keys under Developers > API keys and the webhook signing secret under Developers > Webhooks in the Stripe dashboard. Test and live keys are separate — only STRIPE_SECRET is used by this package, STRIPE_KEY is kept in the config for your client-side code.

#Configuration

// config/stripe.php
return [
    'secret' => env('STRIPE_SECRET'),
    'key' => env('STRIPE_KEY'),
    'base_url' => env('STRIPE_BASE_URL', 'https://api.stripe.com'),
    'api_version' => env('STRIPE_API_VERSION'),
    'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
    'default_limit' => env('STRIPE_DEFAULT_LIMIT', 10),
];

#Usage

Use the Stripe facade or inject JeffersonGoncalves\Stripe\Stripe. Each API group is exposed as a method returning a dedicated resource class. Every list() accepts Stripe's own filters (limit, starting_after, ending_before, created, ...) and defaults limit to default_limit.

Amounts are always in the currency's smallest unit — 1990 is US$ 19.90.

#Customers

use JeffersonGoncalves\Stripe\Facades\Stripe;

$customer = Stripe::customers()->create('jane@example.com', ['name' => 'Jane Doe']);

Stripe::customers()->list(['limit' => 10]);
Stripe::customers()->get($customer['id']);
Stripe::customers()->update($customer['id'], ['name' => 'Janet Doe']);
Stripe::customers()->delete($customer['id']);

// First customer with that email, or null — Stripe does not enforce uniqueness
$existing = Stripe::customers()->findByEmail('jane@example.com');

#Products and prices

$product = Stripe::products()->create('Pro Plan', ['description' => 'Everything in one plan']);

$price = Stripe::prices()->create(
    productId: $product['id'],
    unitAmount: 1990,        // US$ 19.90
    currency: 'usd',
    attributes: ['recurring' => ['interval' => 'month']],
);

Stripe::products()->archive($product['id']);   // active = false
Stripe::prices()->archive($price['id']);

#Checkout and the billing portal

$session = Stripe::checkout()->create(
    lineItems: [['price' => $price['id'], 'quantity' => 1]],
    mode: 'subscription',
    successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
    attributes: [
        'customer' => $customer['id'],
        'cancel_url' => 'https://example.com/cancel',
    ],
);

return redirect()->away($session['url']);

$portal = Stripe::billingPortal()->createSession($customer['id'], 'https://example.com/account');

return redirect()->away($portal['url']);

#Subscriptions

$subscription = Stripe::subscriptions()->create($customer['id'], [
    ['price' => $price['id'], 'quantity' => 1],
]);

Stripe::subscriptions()->forCustomer($customer['id'], ['status' => 'active']);

Stripe::subscriptions()->update($subscription['id'], [
    'items' => [['id' => $subscription['items']['data'][0]['id'], 'quantity' => 3]],
    'proration_behavior' => 'always_invoice',
]);

Stripe::subscriptions()->cancel($subscription['id']);                      // immediately
Stripe::subscriptions()->cancel($subscription['id'], atPeriodEnd: true);   // at period end
Stripe::subscriptions()->resume($subscription['id']);                      // undo the above

#Invoices, payment intents and events

Stripe::invoices()->forCustomer($customer['id'], ['status' => 'paid']);
Stripe::invoices()->pay('in_123');
Stripe::invoices()->void('in_123');

$intent = Stripe::paymentIntents()->create(2500, 'brl', [
    'customer' => $customer['id'],
    'automatic_payment_methods' => ['enabled' => 'true'],
]);

Stripe::paymentIntents()->capture($intent['id']);   // capture_method = manual
Stripe::paymentIntents()->cancel($intent['id']);

Stripe::events()->ofType('checkout.session.completed');

#Webhooks

Verify the Stripe-Signature header against the raw request body before trusting a webhook:

use Illuminate\Http\Request;
use JeffersonGoncalves\Stripe\Facades\Stripe;

Route::post('/stripe/webhook', function (Request $request) {
    abort_unless(Stripe::webhooks()->verifyRequest($request), 403);

    $event = $request->json()->all();

    match ($event['type']) {
        'checkout.session.completed' => /* provision access */ null,
        'customer.subscription.deleted' => /* revoke access */ null,
        'invoice.payment_failed' => /* notify the customer */ null,
        default => null,
    };

    return response()->noContent();
})->withoutMiddleware([VerifyCsrfToken::class]);

verify(string $payload, string $signature, int $tolerance = 300) is available when you already hold the raw body. Signatures older than $tolerance seconds are rejected (pass 0 to disable that check). More than one v1 signature in the header is handled, so rotating the signing secret does not drop events. The payload must be the raw body — a re-encoded array will not match.

#Error handling

Any non-2xx API response throws JeffersonGoncalves\Stripe\Exceptions\StripeException, which exposes the decoded error body along with Stripe's code, type and offending parameter:

use JeffersonGoncalves\Stripe\Exceptions\StripeException;

try {
    Stripe::subscriptions()->get('sub_missing');
} catch (StripeException $e) {
    if ($e->errorCode() === 'resource_missing') {
        // ...
    }

    logger()->error($e->getMessage(), $e->errorBody());
}

Missing required fields (e.g. email on customers()->create()) throw InvalidArgumentException before any HTTP call is made.

#Testing

composer test

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

• Jefferson Gonçalves
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.