larasell-dev / stripe

v0.3.3 2026-09-02 11:18 UTC

Requires

• php: ^8.2
• larasell-dev/larasell: ^1.11
• stripe/stripe-php: ^21.3

Requires (Dev)

• laravel/pao: ^1.1
• laravel/pint: ^1.30
• orchestra/testbench: ^11.0
• pestphp/pest: ^5.1

MIT

Published on Packagist.org on 2026-09-02 11:18 UTC

README

Stripe Checkout payments for Larasell.

Installation

composer require larasell-dev/stripe

Add the Stripe credentials to the application environment:

STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
# Optional when live mode cannot be inferred from STRIPE_SECRET:
STRIPE_LIVEMODE=false

Register the payment method in config/larasell.php:

use Larasell\Stripe\StripePaymentProvider;

'payments' => [
    'default' => 'stripe',
    'methods' => [
        'stripe' => [
            'driver' => 'stripe',
            'provider' => StripePaymentProvider::class,
        ],
    ],
],

Checkout

The storefront supplies its success and cancellation URLs:

$result = $checkout->create(
    cart: $cart,
    data: $customerData,
    paymentMethod: 'stripe',
    paymentOptions: [
        'success_url' => route('checkout.success', absolute: true),
        'cancel_url' => route('checkout.cancel', absolute: true),
    ],
);

return $result->requiresRedirect()
    ? $result->redirect()
    : redirect()->route('orders.show', $result->order);

Additional Stripe Checkout Session options can be supplied under session_options. Larasell-controlled amount, customer, URL, and metadata fields cannot be overridden.

Stripe Checkout receives Larasell's canonical payment breakdown. Each order line is shown separately and shipping is included as its own line when present. The submitted amounts already include the applicable discounts, taxes, and rounding, so Stripe collects the exact persisted payment total.

Stripe receives each entry with a quantity of 1 because a breakdown amount is the final amount for the complete order line. The purchased quantity remains visible in the Stripe item name, for example 2 x Coffee beans. Stripe Tax should not be enabled for these Checkout Sessions because Larasell is the tax authority.

paymentOptions: [
    'success_url' => route('checkout.success', absolute: true),
    'cancel_url' => route('checkout.cancel', absolute: true),
    'session_options' => [
        'locale' => 'de',
        'allow_promotion_codes' => true,
    ],
],

Webhooks

The package registers:

POST /larasell/stripe/webhook

Configure Stripe to deliver these events:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• checkout.session.expired

Webhook signatures are verified and Stripe event IDs are stored to prevent duplicate processing. Before changing a payment, Larasell verifies the Session amount, currency, payment mode, live/test mode, and order/payment metadata. The webhook signing secret binds events to the configured Stripe endpoint. Browser redirects never mark an order as paid.

Also configure Stripe to deliver the refund lifecycle events:

• refund.created
• refund.updated
• refund.failed

Refunds

Create full or partial refunds from a successful Stripe payment:

$refund = $payment->refund();

$refund = $payment->refund(Price::of(2500));

Amounts use the same integer minor units as Larasell prices. Stripe refund options such as a reason can be passed separately:

$refund = $payment->refund(Price::of(2500), [
    'refund_options' => [
        'reason' => 'requested_by_customer',
    ],
]);

The initial Stripe response sets the local refund status. Pending refunds are subsequently finalized by signed webhooks. Refunding never cancels an order; an unfulfilled, fully refunded order can be cancelled explicitly.

To register the webhook route yourself, call this before package providers boot:

use Larasell\Stripe\Stripe;

Stripe::ignoreRoutes();

Publish the configuration or migrations when customization is required:

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