Payum Stripe Checkout Session Bundle Laravel Package

Getting Started

Install the bundle and register it:

composer require prometee/payum-stripe-checkout-session-bundle

// config/bundles.php
return [
    // ...
    Prometee\PayumStripeCheckoutSessionBundle\PayumStripeCheckoutSessionBundle::class => ['all' => true],
];

Set the Stripe credentials in .env:

STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Configure a Payum gateway with the factory provided by the bundle. In Sylius this is usually done by creating a Payment Method in the admin UI and selecting the Stripe Checkout Session gateway factory; the equivalent fixture/config looks like:

# config/packages/_sylius.yaml or a fixtures file
sylius_payment:
    gateways:
        stripe_checkout_session:
            factory: stripe_checkout_session
            publishable_key: '%env(STRIPE_PUBLISHABLE_KEY)%'
            secret_key: '%env(STRIPE_SECRET_KEY)%'

Look first at:

• the bundle’s DependencyInjection/ and Resources/config/ files to see which Payum gateway factory, actions, and API services are registered;
• the gateway factory class (usually StripeCheckoutSessionGatewayFactory) and its createConfig() / create() methods;
• CaptureAction, NotifyAction, SyncAction, and StatusAction — these define the actual payment lifecycle;
• the Sylius payment method configuration and the Payum notify route.

The first use case is a standard redirect checkout: capture a Sylius order payment, create a Stripe Checkout Session, redirect the customer to Stripe, then complete the order on return or via webhook.

use Payum\Core\Request\Capture;
use Payum\Core\Request\GetHumanStatus;

$gateway = $this->get('payum')->getGateway('stripe_checkout_session');

$gateway->execute($capture = new Capture($payment));
$status = new GetHumanStatus($payment);
$gateway->execute($status);

Implementation Patterns

Sylius admin configuration. The day-to-day path is: create a Payment Method, choose the Stripe Checkout Session factory, enter publishable/secret keys, and assign it to a shipping/payment method. Keep one gateway per store/currency if you have multi-store pricing.

Capture → redirect → reconcile. CaptureAction builds the Stripe Checkout Session from the Payum Payment amount and currency, stores the session identifier in $payment->getDetails(), and returns a redirect. After the user returns, do not trust the query string alone: execute Sync and GetHumanStatus against the stored session before transitioning the Sylius order.

$gateway->execute(new Sync($payment));

$status = new GetHumanStatus($payment);
$gateway->execute($status);

if ($status->isCaptured()) {
    // transition the Sylius order/payment state machine
}

Webhook/notify handling. Configure Stripe to send checkout.session.completed and, if you support delayed methods, checkout.session.async_payment_succeeded to the Payum notify URL for the payment. NotifyAction verifies the Stripe-Signature header, retrieves the Checkout Session, writes the payment intent/session details, and marks the payment captured. Webhook handling is what makes the flow reliable when the customer closes the browser after paying.

stripe listen --forward-to https://your-app.test/payment/notify

Customize the session. Extend or replace CaptureAction when you need metadata (order number, customer id), customer_email, line_items, allow_promotion_codes, or a custom success_url/cancel_url. Keep the amount/currency calculation in one place and pass it through the Payum request details so both capture and webhook paths agree.

Multiple actions and gateways. Register a custom gateway factory or override the action services if you need different behavior per channel (e.g. B2B vs B2C, different capture modes). Payum’s ActionInterface + ApiAwareInterface pattern means any custom action must receive the Stripe API service via setApi().

Testing. Use Stripe test keys and the Stripe CLI for webhook forwarding. For unit tests, mock the Stripe API client and assert that CaptureAction stores the session id and that StatusAction maps Stripe session statuses (open, complete, expired) to Payum statuses. Use Stripe test cards for end-to-end tests.

Order state machine integration. In Sylius, hook the payment transition (sylius_order_payment / complete) so the order becomes paid only after GetHumanStatus::STATUS_CAPTURED. Avoid completing orders directly in the controller; route all state changes through the state machine.

Gotchas and Tips

• Amounts are in minor units. Stripe expects integer cents; take care with zero-decimal currencies (JPY, KRW) and currencies with three decimals. A mismatch between Sylius total and Stripe line items causes silent under/overcharges.
• Do not trust the redirect. A user can return to success_url without a completed payment, or close the tab after paying. Always reconcile with Sync/Status and rely on the webhook for finality.
• Webhook signature verification. Use the raw request body and the correct whsec_ secret. Reverse proxies, body parsers, or Symfony listeners that alter the request can break signature checks. Ensure the notify route is public, POST-only, and excluded from CSRF.
• Idempotency. Stripe retries webhooks. Guard against duplicate checkout.session.completed events by checking the current payment status and using an idempotency key when creating sessions.
• Success/cancel URLs. They must be absolute URLs. If you need the session id in the return URL, include {CHECKOUT_SESSION_ID} in success_url; otherwise you must rely on the stored payment token.
• Status mapping. Stripe’s session status is not the same as Payum’s human status. Map complete + payment_status=paid to captured; expired/unpaid should stay pending or failed. Customize StatusAction if your business rules differ.
• Refunds and partial captures. The bundle focuses on Checkout Session capture. Refund, partial refund, and manual capture flows usually require custom actions or direct Stripe API calls; verify before promising them to stakeholders.
• Version compatibility. With a small dependent base, check composer why-not against your Symfony, Payum, Sylius, and stripe/stripe-php versions. Pin versions in production and run the test suite after upgrades.
• Secrets and logging. Never log sk_ keys or full webhook payloads containing customer data. Keep test and live keys in separate environments and rotate webhook secrets when endpoints change.
• Cache and container quirks. After changing gateway config or payment method settings, clear the cache (bin/console cache:clear) and verify the compiled Payum gateway config. Sylius can cache payment method gateway config in the database, so admin changes may need a cache warmup.
• Extension points. Prefer decorating the bundle’s actions or replacing service definitions over forking. The Payum factory/action structure is the intended customization seam; keep custom logic in your app bundle so package upgrades remain possible.
• Local development. Stripe cannot reach localhost; use the Stripe CLI or a tunnel. If webhooks fail locally, payments may still succeed at Stripe while your order remains unpaid until manually reconciled.