Commerce Stripe
Provides Drupal Commerce integration for Stripe payment processing, supporting both the modern Payment Element and legacy Card Element with features like 3D Secure, webhooks, and Stripe Connect.
commerce_stripe
Install
composer require 'drupal/commerce_stripe:^2.1'
composer require 'drupal/commerce_stripe:8.x-1.3'
Overview
Commerce Stripe integrates Drupal Commerce with Stripe's payment processing platform, enabling merchants to accept credit cards, digital wallets (Apple Pay, Google Pay), and alternative payment methods (Klarna, Affirm, Alipay, etc.) through Stripe's secure payment infrastructure.
The module provides two payment gateway plugins: the recommended Stripe Payment Element which renders Stripe's modern, fully-hosted payment form supporting multiple payment methods, and the legacy Stripe Card Element for credit card-only integrations. Both support Strong Customer Authentication (3D Secure) for PSD2 compliance.
Key features include automatic payment intent synchronization when order totals change, webhook support for real-time payment status updates, and Stripe Connect OAuth for simplified merchant account configuration. The module uses Stripe.js to ensure sensitive card data never touches your server, reducing PCI compliance scope.
Features
- Stripe Payment Element integration supporting multiple payment methods including credit cards, digital wallets, and buy-now-pay-later options
- Legacy Stripe Card Element for credit card-only checkout flows
- Strong Customer Authentication (SCA) and 3D Secure 2.0 support for PSD2 compliance
- Full payment lifecycle management: authorization, capture, void, and refund operations
- Stripe Connect OAuth for simplified API key configuration without manual key entry
- Webhook support for real-time payment synchronization between Stripe and Drupal
- Automatic payment intent amount updates when cart totals change
- Advanced fraud detection with optional user interaction signal collection
- Customizable checkout display labels with payment method logo support
- Optional submodule for webhook event logging and troubleshooting
Use Cases
Standard E-commerce Checkout
Use Stripe Payment Element for a modern checkout experience supporting credit cards, Apple Pay, Google Pay, and other payment methods. Configure 'automatic' capture method for immediate payment collection and 'on_session' usage for single-purchase scenarios.
Subscription Commerce
Configure 'off_session' payment method usage to allow the site to charge customers for recurring subscriptions without their active participation. Payment methods will be stored and reusable for future charges.
Authorization and Capture Workflow
Use 'manual' capture method to place holds on customer cards at checkout, then capture funds later when orders are fulfilled. Supports partial captures and void operations through the order admin interface.
Multi-currency International Sales
Stripe Payment Element automatically handles currency conversion and displays appropriate payment methods based on the customer's location and the configured currency.
Buy Now Pay Later
Enable Klarna or Affirm payment methods through Stripe Payment Element to offer customers installment payment options. These are single-use payment methods configured automatically.
High-volume Webhook Processing
Install the commerce_stripe_webhook_event submodule with Advanced Queue to defer webhook processing. Webhooks are logged immediately and processed in the background, improving response times and reliability.
Platform/Marketplace with Stripe Connect
Use Stripe Connect OAuth authentication to allow marketplace sellers to connect their Stripe accounts without sharing API keys. The module handles OAuth flow and token storage automatically.
Tips
- Store production API credentials in settings.php using $config['commerce_payment.commerce_payment_gateway.your_gateway']['configuration']['secret_key'] to keep them out of the database.
- Use Stripe Connect authentication for easier key management and the ability to revoke access without changing API keys.
- Install the commerce_stripe_webhook_event submodule for visibility into webhook delivery and processing, especially useful during development and troubleshooting.
- For local development, use the Stripe CLI to forward webhooks: stripe listen --forward-to your.ddev.site/payment/notify/your_gateway
- The Payment Element is recommended over Card Element for new integrations as it supports more payment methods and receives continued updates from Stripe.
- Set 'capture_method' to 'automatic_async' for improved checkout performance as it reduces latency compared to synchronous capture.
- Load Stripe.js on every page (in global settings) for improved fraud detection scores, especially for high-risk businesses.
Technical Details
Admin Pages 3
/admin/commerce/config/stripe
Configure global Commerce Stripe settings that apply to all Stripe payment gateways.
/admin/commerce/config/payment-gateways/manage/{gateway_id}
Configure a Stripe Payment Element payment gateway with authentication, webhook settings, payment options, and appearance customization.
/admin/commerce/config/stripe-webhook-events
View and manage webhook events sent to your site by Stripe. Useful for troubleshooting payment issues and monitoring webhook delivery. (Requires commerce_stripe_webhook_event submodule)
Permissions 2
Hooks 1
hook_js_settings_alter
Allows customization of JavaScript settings passed to Stripe elements before initialization.
Troubleshooting 7
Ensure the 'Stripe review' checkout pane is enabled on the 'Review' step in your checkout flow configuration at /admin/commerce/config/checkout-flows.
The Stripe review pane must be enabled even for Card Element integrations. Without it, the JavaScript required for 3D Secure modal display won't be loaded.
Verify the webhook endpoint URL matches /payment/notify/[gateway_id], ensure the signing secret is correctly copied from Stripe dashboard, and check that your server's firewall allows incoming requests from Stripe's IP ranges.
Ensure your API keys match the selected mode (test vs. live). If using placeholder keys, uncheck 'Validate API keys upon form submission'. For production, store keys in settings.php using configuration overrides.
The OrderPaymentIntentSubscriber handles this automatically. Ensure the module is properly installed and the event subscriber service is registered. Check commerce_stripe logs for any errors.
Enable the commerce_stripe_webhook_event submodule to recover from return failures. The payment_intent.succeeded webhook can complete orders when the return route fails.
Apple Pay requires domain verification in your Stripe dashboard. Upload the verification file to /.well-known/apple-developer-merchantid-domain-association on your web server.
Security Notes 6
- The module uses Stripe.js which ensures sensitive card data never touches your server, significantly reducing PCI DSS compliance requirements.
- Always use HTTPS in production; Stripe.js will fail on insecure connections.
- Store production API keys outside the database using settings.php configuration overrides to prevent exposure in database dumps or configuration exports.
- Enable webhook signature verification by configuring the webhook signing secret to prevent spoofed webhook requests.
- The 'administer commerce stripe' and webhook event permissions should be restricted to trusted administrators only.
- Review Stripe's security documentation at https://stripe.com/docs/security for additional best practices.