Paddle

Paddle supports subscriptions, portal links, and invoice previews. Use this page if you want merchant-of-record billing with a checkout bridge.

Configuration

<?php

return [
  'bnomei.klub.provider.handler' => \Bnomei\Klub\Provider\PaddleProvider::class,
  'bnomei.klub.providers.paddle' => [
    'secret' => fn() => env('PADDLE_API_KEY'),
    'client_token' => fn() => env('PADDLE_CLIENT_TOKEN'),
    'environment' => fn() => env('PADDLE_ENV', 'sandbox'),
    'webhook_secret' => fn() => env('PADDLE_WEBHOOK_SECRET'),
    'webhook_tolerance' => 300,
    'field' => 'paddle',
  ],
];

Environment variables:

PADDLE_API_KEY
PADDLE_CLIENT_TOKEN (optional, only needed for the hosted bridge route)
PADDLE_ENV (sandbox, live, or production)
PADDLE_WEBHOOK_SECRET

Optional provider keys:

proration_billing_mode (default: prorated_immediately) for subscription changes
checkout for provider-specific checkout payload overrides

Webhooks

Configure webhooks to POST /klub/webhooks/paddle.

You can adjust signature tolerance via bnomei.klub.providers.paddle.webhook_tolerance (seconds).

Paddle sends the Paddle-Signature header. Klub validates it with PADDLE_WEBHOOK_SECRET (single value or comma-separated list for secret rotation).

Checkout bridge

Default return flow works without the bridge:

GET /klub/payment/{token} for one-time checkouts
GET /klub/subscribe/{token} for subscription checkouts

If PADDLE_CLIENT_TOKEN is set, Klub can rewrite success URLs to GET /klub/paddle/{token} and open Paddle Checkout in the browser. The bridge expects _ptxn or ptxn query parameters and then redirects to the mapped success/cancel URL.

Portal and invoices

Portal: supported via Paddle management URLs (customer portal / update payment method).
Invoice preview: supported via Paddle invoice URLs.

Gotchas

GET /klub/paddle/{token} is optional and only used when PADDLE_CLIENT_TOKEN is configured.
The portal link is derived from subscription management URLs; if none are available, portal falls back to the provided return URL.
Webhook signatures require PADDLE_WEBHOOK_SECRET.

See Purchases for flow details.

Mollie Paypal