commerce_stripe_checkout

Commerce Stripe Checkout integrates Stripe Checkout — Stripe's hosted, pre-built payment page — into the Drupal Commerce checkout flow. Instead of embedding a payment form on
your site, customers are redirected to Stripe's secure hosted page to complete payment. After payment, Stripe redirects them back to your site where the order is automatically confirmed and unlocked through Commerce's standard workflow and event system.
No card details ever pass through your server, making the integration fully PCI-DSS compliant out of the box. With support for 57 payment methods, asynchronous webhook handling, full and partial refunds, zero-decimal currency conversion, and a comprehensive
alter hook for every Stripe session parameter, Commerce Stripe Checkout gives you a production-grade, enterprise-ready payment integration with the minimum possible configuration.

Features

Payment & Checkout

• Stripe Checkout hosted page — customers are redirected to Stripe's secure, pre-built page to complete payment. No card details touch your server; the integration is fully PCI-DSS compliant out of the box.
• 57 payment methods — every Stripe Checkout-supported method is selectable per gateway instance: Card (with Apple Pay & Google Pay), Link, Klarna, iDEAL, SEPA Direct Debit, ACH, Alipay, WeChat Pay, PayPal, Afterpay / Clearpay, Boleto,
  and many more.
• Automatic invalid-method recovery — if a method is checked in the gateway config but not yet activated in your Stripe Dashboard, it is automatically stripped and checkout retries with the remaining methods. An actionable warning-level
  watchdog message is logged with a direct link to fix it. Checkout continues without interruption.
• Mandatory options auto-injection — methods that require extra API parameters are handled automatically: ACSS Debit mandate options are injected, and WeChat Pay's client option is set without any manual configuration.
• Refund support — full and partial refunds are available via Commerce's standard Refund UI on the payment entity. Implements SupportsRefundsInterface.
• Zero-decimal currency support — correct amount conversion for JPY, KRW, VND, and 13 other zero-decimal currencies is handled automatically by StripeAmountTrait. No manual configuration is required.
• CSRF / replay protection — a 256-bit cryptographically random stsess token is generated per checkout, embedded in the Stripe success and cancel URLs, and verified with a strict === comparison on every callback.
  The token is consumed immediately on first valid use, preventing double-payment from a browser refresh or a race condition.
• Idempotency guard — both the success redirect handler and the webhook handler verify the order is still in draft state before creating a payment entity. A webhook arriving after a successful redirect (or vice versa) cannot
  create a duplicate payment.

Webhook Handler

• Asynchronous payment support — a dedicated webhook endpoint at /stripe-pay/webhook/{gateway_id} handles checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed,
  and checkout.session.expired events. Essential for SEPA Direct Debit, ACH, Boleto, and other methods where confirmation arrives after the customer has left checkout.
• Webhook signature verification — when a webhook_secret (whsec_…) is configured, every incoming POST is verified using Stripe's Stripe-Signature HMAC header. Requests with an invalid or missing
  signature return HTTP 400.
• Session expiry handling — checkout.session.expired events unlock the order automatically so the customer can start a new checkout attempt.

Gateway Configuration

• Check / Uncheck All UI — admin JavaScript adds Select All and Uncheck All controls to the payment methods checklist. Card is always locked on as the required minimum.
• Locale support — set the Stripe Checkout page language to any of Stripe's 30+ supported locales, or use auto to let Stripe detect from the browser.
• Promotion codes — optionally display a coupon / promo code field on the Stripe Checkout page. Codes are managed in your Stripe Dashboard.
• Billing address collection — configurable per gateway instance: auto collects only when required by the payment method; required always collects a full billing address.
• Phone number collection — optionally collect the customer's phone number on the Stripe Checkout page.
• Pass customer email — pre-fill the customer's email address on the Stripe Checkout page.
• Session metadata — every Stripe session automatically carries client_reference_id, metadata.drupal_order_id, and metadata.drupal_site for easy reconciliation in the Stripe Dashboard.
• Stripe Session ID stored — the Stripe cs_… Session ID is stored as remote_id on every Commerce payment entity, enabling refunds and Dashboard lookups.

Developer Experience

• Alter hook — hook_commerce_stripe_checkout_alter_session_params() gives complete control over every Stripe Checkout Session parameter before the API call is made. Add shipping options, tax ID collection, consent checkboxes,
  custom text, session expiry, and more.
• Message hooks — hook_commerce_stripe_checkout_success_message() and hook_commerce_stripe_checkout_failure_message() let any module override the user-facing status messages after payment.
• Event system — CommerceStripeCheckoutEvents::PAYMENT_SUCCESS and PAYMENT_FAILURE are dispatched via Symfony's event dispatcher so you can subscribe to payment outcomes from any service.
• PHP 8.1+ typed properties and declare(strict_types=1) throughout. PSR-4 autoloading under the clean Drupal\commerce_stripe_checkout namespace.
• Zero additional JavaScript dependencies — the admin UI enhancement is pure vanilla JavaScript. No jQuery plugins or npm runtime dependencies.

Security

• CSRF and replay attacks are blocked by a per-checkout 256-bit stsess token that is consumed on first use.
• Order ownership is verified on every callback — an authenticated user cannot process or cancel another user's order.
• Hook-sourced messages are sanitised with Xss::filterAdmin() before display.
• API key format is validated at gateway-save time; keys are never written to any log.
• All order state changes go through Commerce's workflow state machine — no direct set('state', …) mutations.

Post-Installation

After enabling the module, follow these steps to accept payments:

1. Add a payment gateway.
   
   Go to Commerce → Configuration → Payment gateways → Add payment gateway (
   /admin/commerce/config/payment-gateways/add). Under Plugin, select
   Stripe Checkout. Set the Mode to Test or Live.
2. Enter your API keys.
   
   Paste your Test Secret key (sk_test_…) and / or
   Live Secret key (sk_live_…) from
   Stripe Dashboard → Developers → API keys. Keys are validated for the correct prefix on save and are never written to any log.
3. Select payment methods.
   
   In the Allowed Payment Methods section, check every method you want to offer. Card is always required and is locked on — it also enables Apple Pay and Google Pay automatically. Every checked method must also
   be activated in
   Stripe Dashboard → Settings → Payment methods before it will appear to customers. Methods that are checked but not yet activated are skipped automatically at checkout with a watchdog
   warning.
4. Configure the checkout page options.
   
   Set the Locale, toggle Allow promotion codes, choose Billing address collection (auto or required), and enable Phone number collection if needed.
5. Configure webhooks (recommended for production).
   
   Copy the Webhook endpoint URL displayed on the gateway edit form (
   https://yoursite.com/stripe-pay/webhook/{gateway_id}). Go to Stripe Dashboard → Developers → Webhooks → Add endpoint, paste the URL, and select these four events:
   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • checkout.session.async_payment_failed
   • checkout.session.expired

   After saving, click Reveal under Signing secret, copy the
   whsec_… value, paste it into the Webhook signing secret field on the gateway form, and save. Without this, webhook signature verification is disabled — acceptable for development, not recommended for production.

6. Save and test.
   
   Save the gateway. Place a test order using one of
   Stripe's test card numbers (e.g. 4242 4242 4242 4242) and verify the order is placed and the payment entity is created at Commerce → Orders → [your order] → Payments.

Payment Methods Reference

All 57 supported methods are grouped below. Availability depends on your Stripe account country, the order currency, and whether the method is activated in your Dashboard.

Cards & global wallets

card (Visa, Mastercard, Amex — always required; includes Apple Pay & Google Pay),
link (Stripe one-click checkout),
amazon_pay, paypal, revolut_pay

Buy now, pay later

affirm (US & CA),
afterpay_clearpay (US, AU, CA, UK),
alma (France & Europe — requires application),
billie (B2B, DE & NL — requires application),
klarna (US, EU, AU, CA),
scalapay (IT, FR, DE, ES — requires application),
zip (AU & US — invite only)

Bank debits

acss_debit (ACSS / Canadian PAD — mandate options auto-injected),
au_becs_debit (Australia),
bacs_debit (UK),
sepa_debit (Europe),
us_bank_account (ACH, US)

Vouchers & cash

boleto (Brazil), konbini (Japan), multibanco (Portugal), oxxo (Mexico)

Bank redirects

bancontact (Belgium), blik (Poland), eps (Austria),
fpx (Malaysia), giropay (Germany — deprecated by Stripe),
ideal (Netherlands), p24 (Poland), pay_by_bank (UK),
payto (Australia), sofort (Europe — deprecated by Stripe),
swish (Sweden), twint (Switzerland)

Mobile wallets & real-time payments

alipay, cashapp (US), grabpay (SG & MY),
mobilepay (DK & FI), paynow (Singapore),
pix (Brazil — invite only), promptpay (Thailand),
satispay (Italy — requires application), upi (India),
wechat_pay (client option auto-injected)

South Korea

kakao_pay, kr_card, naver_pay, payco

Crypto

crypto (US only — invite only, requires Stripe approval)

Additional Requirements

• Drupal 10.x or 11.x
• PHP 8.1 or higher
• Drupal Commerce ^2.40 or ^3
• stripe/stripe-php ^10.0, ^15.0, or ^20.0 (installed automatically via Composer)
• PHP extension: ext-curl

No third-party JavaScript frameworks or external services beyond Stripe itself are required. The module is entirely self-contained.

Installation

composer require drupal/commerce_stripe_checkout
drush en commerce_stripe_checkout
drush cr

stripe/stripe-php is a declared Composer dependency and is installed automatically. If there is a version conflict in your project, pin the library first:

composer require stripe/stripe-php "^20.0"
composer require drupal/commerce_stripe_checkout

Similar Projects

• Commerce Stripe — The official Stripe module for Drupal Commerce uses Stripe Elements or the Payment Intents API to embed the payment form directly on your site. Commerce
  Stripe Checkout differs by using Stripe's fully hosted Checkout page instead, which is faster to set up, requires zero frontend work, and supports a significantly larger set of payment methods — including BNPL, bank redirects, vouchers, and wallets
  — without any additional configuration.
• Commerce PayPal — Provides PayPal Checkout and PayPal Commerce Platform integrations. Commerce Stripe Checkout can include PayPal as one of many payment methods on the
  same Stripe-hosted page, without requiring a separate PayPal module or merchant account.
• Commerce Braintree — Embeds a Braintree Drop-in UI on your site. Commerce Stripe Checkout instead redirects to Stripe's hosted page, removing all PCI compliance burden
  from your server entirely.

Use Cases

Commerce Stripe Checkout is well suited for:

• Stores needing broad payment method coverage — accept cards, wallets, BNPL, bank debits, and local payment methods with a single gateway configuration.
• PCI-DSS compliance without effort — because no card data touches your server, you qualify for the simplest SAQ-A compliance tier.
• International e-commerce — localised payment methods (iDEAL, SEPA, Bancontact, Boleto, Konbini, UPI, etc.) are each one checkbox away.
• Rapid deployment — no custom JavaScript, no payment form theming, no frontend work. Go live with an API key and a webhook URL.
• Subscription and marketplace platforms — use hook_commerce_stripe_checkout_alter_session_params() to add Stripe Billing subscription data, tax ID collection, or custom metadata for reconciliation.
• High-security or regulated environments — the full threat model (CSRF protection, idempotency guard, ownership verification, workflow state machine) is documented and testable out of the box.

Supporting This Module

If Commerce Stripe Checkout saves you time on your project, the best ways to support continued development are:

• Report bugs and suggest features in the project issue queue.
• Contribute patches, additional test coverage, or documentation improvements via the issue queue.
• Post a review on the project page — community ratings help other Drupal developers discover the module.
• Help test release candidates against new Drupal 10 and 11 minor versions and against new stripe/stripe-php major releases.

When reporting an issue, please include your Drupal core version, PHP version, stripe/stripe-php version, the exact steps to reproduce, and any relevant output from Reports → Recent log messages (/admin/reports/dblog)
filtered by the commerce_stripe_checkout channel. If the issue involves a specific payment method, please also include the method key (e.g. sepa_debit) and your Stripe account's country.

Community Documentation

• Full installation, configuration, payment flow, webhook setup, hook, event, security, and troubleshooting documentation is available in the README.md file included in the module.
• A complete payment methods reference — covering all 57 supported method keys, their country and currency requirements, and any methods that need a Stripe application or invite — is included in the README under Payment Methods Reference.
• For an explanation of how the CSRF token, idempotency guard, and order ownership check work together to prevent double-payments and replay attacks, see the Security section of the README.
• Hook and event API documentation stubs with inline examples are in commerce_stripe_checkout.api.php inside the module.
• Video walkthroughs, tutorial articles, and example custom module code (shipping options, B2B tax ID collection, ERP integrations) are welcome contributions — please post them in the issue queue and they will be linked here.