Download the PHP package jiannius/stripe without Composer

Jiannius Stripe SDK Wrapper

A thin Laravel wrapper around the official Stripe PHP SDK. Handles Checkout Sessions, subscription webhooks, and signature verification with sensible defaults.

Requirements

• PHP 8.2+ (8.3+ for Laravel 13)
• Laravel 10, 11, 12, or 13
• stripe/stripe-php 10 through 17

Installation

The service provider is auto-discovered via extra.laravel.providers.

Configuration

Add Stripe keys to config/services.php:

And to .env:

Never commit live keys to source control. Use environment variables or a secrets vault. For production traffic, prefer a restricted API key (rk_*) over a full secret key.

Implement the host controller

The package registers three routes that point at App\Http\Controllers\StripeController. You must implement this controller in your application — the package supplies the routes and contract, your app supplies the behavior.

Minimal controller:

Register your webhook endpoint with Stripe

Once your app is deployed and the controller is in place, register the webhook endpoint:

This deletes any existing endpoint pointing at the same URL, creates a fresh one subscribed to the events the package handles, and returns the new signing secret. Store it as STRIPE_WEBHOOK_SECRET — every call to createWebhook() rotates the secret.

Events subscribed:

• checkout.session.completed
• checkout.session.expired
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• invoice.paid
• invoice.payment_failed

If you'd rather manage the endpoint manually in the Stripe Dashboard, enable the same six events.

Creating a Checkout session

Returns a Laravel RedirectResponse to the Stripe-hosted checkout page.

unit_amount accepts two forms

For zero-decimal currencies (JPY, KRW, etc.), pass an integer — multiplying yen by 100 would be wrong.

Using an existing Stripe Price ID

Pass price instead of price_data and the package leaves the line item untouched:

Metadata flows into success/cancel URLs

Anything you pass under metadata is forwarded as route parameters on the __stripe.success and __stripe.cancel URLs, so your controller can read them off the request.

Handling webhooks

Status reference

Idempotency

Stripe retries failed webhook deliveries for up to 3 days. Always dedupe by $event->id (format evt_xxx) before acting — otherwise a single renewal can mark a customer's account renewed multiple times. Smart Retries can also legitimately send a renew-failed followed by a renew-success for the same invoice; your handler should treat them as a sequence rather than as conflicting outcomes.

Accessing the validated event vs. the raw payload

All three share an internal cache — the signature is verified once per request.

Cancelling subscriptions

Cancels immediately. To cancel at period end (so the customer keeps access until the period they've already paid for ends), call the SDK directly:

Runtime configuration

For multi-tenant apps that need to swap Stripe accounts at runtime, override the configured keys before any call:

Settings cascade: explicit setters take precedence over config('services.stripe.*').

Testing connectivity

Calls accounts->all() on the configured secret key. Useful as a settings-page health check.

Security checklist

• [ ] Store STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in environment variables or a secrets vault, never in source.
• [ ] Use a restricted API key (rk_*) in place of the full secret key.
• [ ] Add a pre-commit hook to block sk_live_ / rk_live_ patterns.
• [ ] Use separate keys per environment (production / staging / local).
• [ ] Rotate keys when teammates with access leave.
• [ ] Optionally allowlist Stripe's webhook IPs on your edge as defense in depth.

Versioning

Upgrading from v0.1 / v1.0

No code changes required — every public method is preserved. Two things to do after upgrading:

1. Re-register the webhook so the renewal events are delivered:

   Or in the Stripe Dashboard, add invoice.paid and invoice.payment_failed to the existing endpoint.

2. Adopt getValidatedEvent() in your webhook controller to drop the second JSON parse and to get the event ID for idempotency.

Webhook idempotency (default-on)

The package dedupes Stripe's retried/duplicate webhook deliveries via the stripe_webhook_events ledger and the EnsureWebhookIdempotency middleware, attached automatically to the __stripe.webhook route. Each delivery is processed at most once; a handler that returns a non-2xx leaves the event unrecorded so Stripe's retry reprocesses it. This is a best-effort gate — the consuming app's domain unique constraint is the authoritative backstop against duplicate side effects.

Run migrations after upgrading (the package ships stripe_webhook_events).

Config (publish with --tag=stripe-config): set stripe.webhook.idempotent to false to disable, or stripe.webhook.ip_allowlist to true to also reject non-Stripe IPs.

License

MIT.