Stripe

Stripe is the default provider and supports hosted Checkout, Billing Portal, and invoice previews. Use this page if you want the most complete feature set.

Configuration

<?php

return [
  'bnomei.klub.provider.handler' => \Bnomei\Klub\Provider\StripeProvider::class,
  'bnomei.klub.providers.stripe' => [
    'secret' => fn() => env('STRIPE_SECRET_KEY'),
    'webhook' => fn() => env('STRIPE_WEBHOOK_SECRET'),
    'field' => 'stripe',
  ],
];

Environment variables:

STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET

Optional provider keys:

webhook_tolerance (seconds, default 300)
checkout for Checkout Session payload defaults/overrides
metadata callback for checkout metadata

Test mode and API version

Use Stripe Test Mode while integrating and set your API version in the Stripe dashboard. Klub uses direct HTTP calls to the Stripe API (no SDK dependency).

Products, tax, and prices

Create products and prices in Stripe. Recurring prices map to subscriptions; one-time prices map to one-time payments. Configure tax settings early to avoid manual updates later.

Stripe is the only built-in provider that fetches plans/products directly from the provider API. Local plans config is ignored for Stripe checkout.

Portal and invoices

Portal: supported via POST /klub/portal (Stripe Billing Portal).
Invoice preview: supported via POST /klub/invoice/{subscriptionId}.

Checkout customization

Stripe-specific checkout options live under bnomei.klub.providers.stripe.checkout. You can also inject metadata with bnomei.klub.providers.stripe.metadata (the metadata callback receives sanitized checkout request data in built-in routes).

Webhooks

Configure Stripe webhooks to POST /klub/webhooks/stripe.

Stripe sends the Stripe-Signature header. Klub validates it with STRIPE_WEBHOOK_SECRET.

Gotchas

Portal and invoice previews require a stored Stripe customer ID (complete at least one checkout first).
If a price or product is archived in Stripe, subscription actions may fail with “plan/product not found”.
Webhook verification requires the STRIPE_WEBHOOK_SECRET and the Stripe-Signature header.

See Purchases for flow details.

Polar