Commerce PayPal
Provides PayPal payment gateway integration for Drupal Commerce, supporting multiple PayPal services including Checkout API, Fastlane, Express Checkout, and Payflow.
commerce_paypal
インストール
composer require 'drupal/commerce_paypal:^2.0'
概要
Commerce PayPalは、Drupal Commerce向けの包括的な決済統合モジュールで、マーチャントがさまざまな形式でPayPal決済を受け入れることを可能にします。このモジュールは、Smart Payment Buttonsを備えた最新のPayPal Checkout API、スムーズなチェックアウト体験のための新しいFastlane by PayPal、そしてExpress Checkout、Payflow Pro、Payflow Linkなどのレガシーオプションをサポートしています。
このモジュールは、さまざまなビジネスニーズに対応する5つの異なる決済ゲートウェイを提供します：PayPal Checkout（推奨）はSmart Payment ButtonsまたはCustom Card Fieldsを提供、Fastlane by PayPalはリピート顧客向けの高速チェックアウトを実現、Express Checkoutは従来のPayPal統合を提供、Payflow Proは直接クレジットカード処理をサポート、Payflow Linkはホスト型決済ページを提供します。
機能には、決済ステータス同期のためのwebhookサポート、PayPal Creditメッセージング統合、カスタマイズ可能なボタンスタイル、PayPalからの配送先住所収集、オーソリゼーションとキャプチャ両方の決済ワークフローのサポートが含まれます。
Features
- PayPal、Pay Later、Venmo、代替決済手段を含むシームレスな決済選択のためのSmart Payment Buttonsを備えたPayPal Checkout API
- PayPalを通じてサイト上で直接クレジットカード決済を受け入れるためのCustom Card Fields統合
- 保存された決済方法と住所認識による高速チェックアウト体験のためのFastlane by PayPal
- NVP APIを使用した従来のPayPal決済フローのためのExpress Checkout（レガシー）
- マーチャントアカウントによる直接クレジットカード処理のためのPayflow Pro統合
- iframeまたはリダイレクトチェックアウトモードを備えたホスト型決済ページのためのPayflow Link
- 分割払いオプションを促進するための商品ページとカートページでのPayPal Creditメッセージング
- 自動決済ステータス同期（キャプチャ、返金、無効化）のためのwebhook統合
- 手動または自動キャプチャオプションを備えたオーソリゼーションとキャプチャ決済ワークフロー
- PayPal顧客データからの請求先・配送先プロファイル更新
- カスタマイズ可能なSmart Payment Buttonスタイル（レイアウト、色、形状、ラベル）
- 複数の資金源サポート（PayPal、クレジットカード、Pay Later、Venmo、Bancontact、iDEALなど）
- Payflow Linkのリファレンストランザクションサポート
- Express CheckoutのIPN（即時支払い通知）処理
- カート表示用のCredit Messagingエリアハンドラーを備えたViews統合
- PayPal CheckoutとFastlane決済方法向けに最適化されたカスタムチェックアウトフロー
Use Cases
Simple PayPal Checkout Integration
For stores wanting to offer PayPal as a payment option with minimal setup, configure the PayPal Checkout gateway with Smart Payment Buttons. Customers can pay with their PayPal account, credit/debit cards, Pay Later, Venmo, or other regional payment methods directly on the checkout page.
Accept Credit Cards via PayPal
Using PayPal Checkout with Custom Card Fields allows merchants to accept credit card payments directly on their site without PCI compliance complexity. Card data is tokenized by PayPal's SDK while the payment form appears native to your site.
Shortcut Flow from Cart Page
Enable Smart Payment Buttons on the cart page to allow customers to start the PayPal checkout directly from the cart. After approval, customers return to a streamlined review step before completing the purchase.
Accelerated Checkout with Fastlane
Use Fastlane by PayPal for returning customers who have opted into Fastlane. The system recognizes customers by email and pre-fills their saved payment and shipping information, dramatically reducing checkout time.
Direct Credit Card Processing with Payflow Pro
Merchants with existing Payflow Pro accounts can accept credit cards directly using on-site card entry forms. Suitable for B2B or subscription scenarios requiring stored payment methods.
Hosted Payment Page with Payflow Link
Use Payflow Link for a hosted payment solution where customers complete payment on PayPal's secure hosted page. Available as iframe embed or full redirect for merchants wanting minimal PCI scope.
Promotional Financing with Credit Messaging
Enable PayPal Credit messaging on product pages and cart to promote 'Pay Later' options. Displays promotional messages like 'Pay in 4' to increase conversion rates on higher-value purchases.
Authorization and Later Capture
Configure payment gateways to authorize payments at checkout and capture later when orders ship. Useful for pre-orders, backordered items, or merchants who verify inventory before charging.
Tips
- Use PayPal Checkout (paypal_checkout) or Fastlane (paypal_fastlane) for new integrations as Express Checkout and Payflow are legacy options.
- Configure webhooks to ensure payment statuses stay synchronized between PayPal and your store, especially for authorizations, refunds, and disputes.
- Enable the 'Show Smart Payment Buttons on the cart page' option to allow customers to start checkout directly from the cart for a streamlined experience.
- Use the Sandbox mode with PayPal Developer test accounts to thoroughly test payment flows before going live.
- The PayPal Credit messaging feature can increase conversion rates by promoting financing options - configure it in the dedicated admin form.
- When using Custom Card Fields, billing information collection is required; PayPal handles the card data securely.
- For Fastlane, ensure the checkout flow configuration has panes in the correct order: contact information, then shipping (if applicable), then payment information.
- Subscribe to PayPal events via event subscribers to customize order data sent to PayPal, such as adding custom metadata or modifying shipping options.
Technical Details
Admin Pages 1
/admin/commerce/config/payment/paypal-credit
Configure PayPal Credit messaging to display promotional financing messages on product and cart pages, encouraging customers to use PayPal Credit for purchases.
Hooks 2
hook_commerce_paypal_express_checkout_request_alter
Allows modules to alter Express Checkout NVP request data via event subscriber.
hook_commerce_paypal_checkout_order_request_alter
Allows modules to alter PayPal Checkout order request data via event subscriber.
Troubleshooting 6
Verify the Client ID is correct, the payment gateway is enabled and available for the order's store, and that the order total is positive. Check browser console for JavaScript errors and ensure no ad blockers are interfering with PayPal scripts.
Ensure the Webhook ID in the gateway configuration matches the webhook ID shown in your PayPal Developer Dashboard. The Webhook URL must be publicly accessible and use HTTPS.
Verify you are using the correct credentials for the selected mode (Sandbox vs Live). For Checkout/Fastlane, use REST API Client ID and Secret. For Express Checkout, use NVP API Username, Password, and Signature.
Check for webhook configuration and ensure the required webhook events are subscribed (Payment capture completed, Payment capture denied, etc.). Enable webhook request logging to debug incoming notifications.
The module automatically deduplicates PayPal Checkout Smart Payment Buttons options. If duplicates appear, ensure only one PayPal Checkout gateway is configured for the store.
Ensure the Payflow Link hosted pages are properly configured in your PayPal Manager account. The module includes iframe error handling that will display messages and reload the page when errors occur.
Security Notes 6
- All PayPal payment gateways use secure API communication over HTTPS. Sensitive credentials (API secrets, passwords) should never be exposed in logs or client-side code.
- Custom Card Fields tokenizes card data client-side through PayPal's SDK, keeping your site out of PCI scope for card data transmission.
- Webhook signatures are verified using PayPal's verification API to ensure notifications are authentic before processing.
- The module uses OAuth 2.0 authentication for the Checkout and Fastlane APIs, with access tokens cached securely in Drupal's state system.
- Enable webhook request logging only for debugging purposes; disable in production to avoid logging sensitive payment data.
- Payflow credentials (password) are stored encrypted in Drupal's configuration system but should still be protected at the server level.