README

Stripe integration package for Laravel projects that need a practical repository-based API for:

Checkout Sessions
Customers
Products and Prices
Refunds
Stripe Connect onboarding
webhook verification
country-aware payment method selection

Laravel 10-13 on PHP 8.1+.

Features

repository-style Stripe API wrapper,
Checkout Session creation with support for Stripe-hosted checkout parameters,
customer, product, price and invoice helpers,
Stripe Connect support for Express onboarding flows,
webhook signature verification middleware,
currency normalization and minimum amount validation,
payment method selection helper based on customer country and presentment currency,
optional policy filters for customer type, MCC / branch, project type and explicit allow / deny lists.

Compatibility

Current compatibility targets:

Laravel 10 on PHP 8.1+
Laravel 11 on PHP 8.2+
Laravel 12 on PHP 8.2+
Laravel 13 on PHP 8.3+

Installation

composer require dominservice/laravel-stripe

Add your Stripe credentials in .env:

STRIPE_KEY=pk_live_xxx
STRIPE_SECRET=sk_live_xxx
STRIPE_WEBHOOK_CHECKOUT=whsec_xxx

Publish config:

php artisan vendor:publish --provider="Dominservice\\LaraStripe\\ServiceProvider" --tag=stripe

Publish migrations:

php artisan vendor:publish --provider="Dominservice\\LaraStripe\\ServiceProvider" --tag=stripe-migrations

Run migrations:

php artisan migrate

Configuration

Main configuration file:

config/stripe.php

Important sections:

stripe.key
stripe.secret
stripe.webhooks.*
stripe.currencies
stripe.minimum_charge_amounts
stripe.zero_decimal_currencies
stripe.three_decimal_currencies
stripe.payment_method_policies

Allowed currencies

If your application only supports specific currencies, list them in:

'currencies' => ['PLN', 'EUR', 'USD', 'GBP'],

If a currency is not declared there, helper validation will reject it.

User model mapping

Check whether the package config matches your project:

stripe.model
stripe.email_key
stripe.name_key

Webhooks

Attach the middleware stripe.verify:{name} to routes that receive Stripe webhook calls.

Example:

Route::middleware(['stripe.verify:checkout'])->group(function () {
    Route::post('/webhook/payments', [WebhookController::class, 'payments']);
});

{name} maps to:

config('stripe.webhooks.signing_secrets.checkout')

Basic Usage

use Dominservice\LaraStripe\Client as StripeClient;

$stripe = new StripeClient();

Create a customer

$customer = $stripe->customers()
    ->setName($user->name)
    ->setEmail($user->email)
    ->setPhone($user->phone)
    ->setAddress([
        'country' => 'PL',
        'city' => 'Warszawa',
        'postal_code' => '00-000',
        'line1' => 'ul. Kopernika 1/2',
    ])
    ->create($user);

Create a product with price

$productStripe = $stripe->products()
    ->setName($product->name)
    ->setActive(true)
    ->setExtendPricesCurrency('pln')
    ->setExtendPricesUnitAmount((float) $amount)
    ->setExtendPricesBillingScheme('per_unit')
    ->create($product);

Create a Checkout Session

$session = $stripe->checkoutSessions()
    ->setSuccessUrl(route('payment.afterTransaction', $order->ulid) . '?session_id={CHECKOUT_SESSION_ID}')
    ->setCancelUrl(route('payment.canceled', $order->ulid))
    ->setMode('payment')
    ->setClientReferenceId($order->ulid)
    ->setCustomer($customer->id)
    ->setLineItems([
        [
            'price' => $productStripe->default_price->id,
            'quantity' => 1,
        ],
    ])
    ->create();

Stripe Checkout Support

The package allows passing Stripe Checkout parameters such as:

allow_promotion_codes
automatic_tax
billing_address_collection
cancel_url
consent_collection
customer_creation
customer_update
invoice_creation
locale
payment_method_collection
payment_method_configuration
payment_method_options
payment_method_types
phone_number_collection
shipping_address_collection
success_url
tax_id_collection
ui_mode

These are handled in the Checkout Session repository and forwarded to Stripe if valid.

Currency Helpers

Normalize currency code

use Dominservice\LaraStripe\Helpers\PaymentHelper;

$currency = PaymentHelper::normalizeCurrencyCode('eur', true); // eur

Validate and normalize amount

$unitAmount = PaymentHelper::getValidAmount('EUR', 49.99); // 4999

The helper:

validates configured currencies,
handles zero-decimal and three-decimal currencies,
validates Stripe minimum charge amounts.

Payment Methods by Country

The package contains a helper that can build manual payment_method_types for Stripe Checkout.

use Dominservice\LaraStripe\Helpers\PaymentHelper;

$methods = PaymentHelper::getPaymentMethodsByCountry('PL', 'PLN');
// ['card', 'blik', 'klarna', 'p24', 'paypal']

Another example:

$methods = PaymentHelper::getPaymentMethodsByCountry('DE', 'EUR');
// ['card', 'klarna', 'paypal', 'sepa_debit']

What the helper currently does

It:

always keeps card,
adds methods supported for the customer country,
applies presentment currency restrictions,
excludes deprecated methods such as giropay and sofort,
optionally filters by project policies.

Current optional third argument

$methods = PaymentHelper::getPaymentMethodsByCountry('PL', 'PLN', [
    'customer_type' => 'private',
    'mcc' => '7991',
    'project_type' => 'travel',
    'allowed_methods' => ['card', 'blik', 'paypal'],
    'forbidden_methods' => ['klarna'],
]);

Supported context keys:

customer_type
mcc
project_type
business_type
allowed_methods
forbidden_methods

This third argument is optional. If you do not pass it, older integrations keep working as before.

Payment Method Policies

The policy layer is configured in:

stripe.payment_method_policies

It is optional by design. If you leave it empty, the helper falls back to country + currency only.

1. Allowed methods for project / business type

'allowed_methods_by_project_type' => [
    'travel' => ['card', 'paypal'],
    'hotel' => ['card', 'paypal', 'klarna'],
    'saas' => ['card', 'paypal', 'sepa_debit'],
],

If your project prefers business_type naming, the package also supports:

'allowed_methods_by_business_type' => [
    'tourism' => ['card', 'paypal'],
    'saas' => ['card', 'paypal', 'sepa_debit'],
],

2. Forbidden methods for project / business type

'forbidden_methods_by_project_type' => [
    'travel' => ['p24'],
],

The same alias exists for:

'forbidden_methods_by_business_type' => [
    'regulated' => ['klarna'],
],

3. Forbidden methods for customer type

By default the package excludes klarna for:

'customer_type' => 'company'

because Klarna does not support B2B flows in the same way as private consumer checkout.

4. Forbidden MCC by payment method

The package now ships with a default MCC restriction map for p24, based on the current Stripe documentation.

This matters especially for projects in categories such as:

travel agencies,
tour operators,
hotels,
transport,
software,
healthcare,
advertising,
real estate,
gambling,
higher education.

The restriction list is configurable, so the host project can override or extend it.

5. Forbidden methods by MCC / branch

If the host project prefers a category-first policy view instead of the method-first forbidden_mcc_by_method, it can also define:

'forbidden_methods_by_mcc' => [
    '4722' => ['p24'],
    '7011-7012' => ['p24'],
],

Both policy styles can coexist. The helper merges them.

Backward compatibility

All policy layers are optional:

if you do not configure project type policies, nothing changes,
if you do not configure business type policies, nothing changes,
if you do not pass customer_type, no customer-type filtering happens,
if you do not pass mcc, MCC rules are not evaluated,
if you do not pass allow / deny lists, they are ignored.

This keeps older integrations working without forced refactors.

Stripe Connect

The package supports the base repositories required for Stripe Connect onboarding:

accounts()
accountLinks()
loginLinks()

Typical platform flow:

use Dominservice\LaraStripe\Client as StripeClient;

$stripe = new StripeClient();

$account = $stripe->accounts()
    ->setType('express')
    ->setCountry('PL')
    ->setEmail($expert->email)
    ->setCapabilities([
        'transfers' => ['requested' => true],
    ])
    ->create($expert);

$onboarding = $stripe->accountLinks()
    ->setAccount($account->id)
    ->setRefreshUrl(route('expert.billing.refresh'))
    ->setReturnUrl(route('expert.billing.return'))
    ->setType('account_onboarding')
    ->create();

$loginLink = $stripe->loginLinks()->create($account->id);

For marketplace split payments handled on the platform account, create Checkout Sessions with:

payment_intent_data.application_fee_amount
payment_intent_data.transfer_data.destination

Notes for DominPress-family Projects

This package is already useful for:

public booking flows such as 44Islands,
marketplace and panel billing flows,
future SaaS-style projects in the DominPress family,
DPS-related projects that need:
- Checkout Sessions,
- Connect onboarding,
- invoice-compatible payment metadata,
- project-specific payment method policies.

For projects with strongly regulated payment availability, the host application should pass:

customer country,
presentment currency,
customer type,
MCC,
project type or business type.

That gives the helper enough context to avoid showing methods that should not be available.

Recommended Host-Project Strategy

For Checkout-based implementations:

collect billing country in the public form,
determine presentment currency before session creation,
pass customer_type if the checkout distinguishes private vs company,
pass mcc or project_type if the business has method restrictions,
build payment_method_types through PaymentHelper::getPaymentMethodsByCountry(...).

This is especially relevant when a single codebase serves:

public tourism booking,
B2B SaaS checkout,
expert / partner payouts through Connect.

Support

Support this project (Ko-fi)

If this package saves you time, consider buying me a coffee:

https://ko-fi.com/dominservice

Thank you.

License

MIT

dominservice / laravel-stripe

Maintainers

Package info

Statistics

Security