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
3,691 sites
58
drupal.org
gui api integration
payment Commerce stripe payment gateway credit card 3d secure sca pci webhooks digital wallet apple pay google pay
Drupal 9 Drupal 10 Drupal 11

インストール

Drupal 11, 10 v2.1.0
composer require 'drupal/commerce_stripe:^2.1'
Drupal 9 v8.x-1.3
composer require 'drupal/commerce_stripe:8.x-1.3'

概要

Commerce StripeはDrupal CommerceをStripeの決済処理プラットフォームと統合し、マーチャントがStripeの安全な決済インフラを通じてクレジットカード、デジタルウォレット（Apple Pay、Google Pay）、代替決済手段（Klarna、Affirm、Alipayなど）を受け付けることを可能にします。

このモジュールは2つの決済ゲートウェイプラグインを提供します：推奨されるStripe Payment Elementは、複数の決済手段をサポートするStripeの最新の完全ホスト型決済フォームをレンダリングし、レガシーのStripe Card Elementはクレジットカードのみの統合用です。両方ともPSD2準拠のためのStrong Customer Authentication（3Dセキュア）をサポートしています。

主な機能には、注文合計が変更された際の自動決済インテント同期、リアルタイム決済ステータス更新のためのWebhookサポート、マーチャントアカウント設定を簡素化するStripe Connect OAuthが含まれます。このモジュールはStripe.jsを使用して、機密カードデータがサーバーに触れないようにし、PCIコンプライアンスの範囲を縮小します。

Features

  • クレジットカード、デジタルウォレット、後払いオプションを含む複数の決済手段をサポートするStripe Payment Element統合
  • クレジットカードのみのチェックアウトフロー用のレガシーStripe Card Element
  • PSD2準拠のためのStrong Customer Authentication（SCA）と3Dセキュア2.0サポート
  • 完全な決済ライフサイクル管理：承認、キャプチャ、取消、返金操作
  • 手動でのキー入力なしでAPI設定を簡素化するStripe Connect OAuth
  • StripeとDrupal間のリアルタイム決済同期のためのWebhookサポート
  • カート合計が変更された際の自動決済インテント金額更新
  • オプションのユーザーインタラクションシグナル収集による高度な不正検出
  • 決済方法ロゴサポート付きのカスタマイズ可能なチェックアウト表示ラベル
  • Webhookイベントのログ記録とトラブルシューティング用のオプションサブモジュール

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
Stripe settings /admin/commerce/config/stripe

Configure global Commerce Stripe settings that apply to all Stripe payment gateways.

Payment Gateway Configuration (Stripe Payment Element) /admin/commerce/config/payment-gateways/manage/{gateway_id}

Configure a Stripe Payment Element payment gateway with authentication, webhook settings, payment options, and appearance customization.

Stripe webhook events /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)

権限 2
Administer Commerce Stripe

Allow to access the administration form to configure Commerce Stripe settings.

View Stripe dashboard links

Allow to view Stripe dashboard links in order payment views.

Hooks 1
hook_js_settings_alter

Allows customization of JavaScript settings passed to Stripe elements before initialization.

Troubleshooting 7
Payment Element not appearing on the review page

Ensure the 'Stripe review' checkout pane is enabled on the 'Review' step in your checkout flow configuration at /admin/commerce/config/checkout-flows.

3D Secure authentication not working

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.

Webhooks not being received or verified

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.

API key validation errors on form submission

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.

Payment intent amounts not updating when cart changes

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.

Orders stuck after Payment Element return with 500 error

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 not appearing in Payment Element

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.