Commerce PayPal
Provides PayPal payment gateway integration for Drupal Commerce, supporting multiple PayPal services including Checkout API, Fastlane, Express Checkout, and Payflow.
commerce_paypal
Install
composer require 'drupal/commerce_paypal:^2.0'
Overview
Commerce PayPal is a comprehensive payment integration module for Drupal Commerce that enables merchants to accept PayPal payments in various forms. The module supports the latest PayPal Checkout API with Smart Payment Buttons, the new Fastlane by PayPal for streamlined checkout experiences, and legacy options like Express Checkout, Payflow Pro, and Payflow Link.
The module provides five distinct payment gateways to suit different business needs: PayPal Checkout (recommended) offers Smart Payment Buttons or Custom Card Fields; Fastlane by PayPal enables rapid checkout for returning customers; Express Checkout provides classic PayPal integration; Payflow Pro supports direct credit card processing; and Payflow Link offers hosted payment pages.
Features include webhook support for payment status synchronization, PayPal Credit messaging integration, customizable button styles, shipping address collection from PayPal, and support for both authorization and capture payment workflows.
Features
- PayPal Checkout API with Smart Payment Buttons for seamless payment selection including PayPal, Pay Later, Venmo, and alternative payment methods
- Custom Card Fields integration for accepting credit card payments directly on your site through PayPal
- Fastlane by PayPal for accelerated checkout experience with saved payment methods and address recognition
- Express Checkout (Legacy) for classic PayPal payment flow with NVP API
- Payflow Pro integration for direct credit card processing with merchant accounts
- Payflow Link for hosted payment pages with iframe or redirect checkout modes
- PayPal Credit messaging on product and cart pages to promote financing options
- Webhook integration for automatic payment status synchronization (captures, refunds, voids)
- Authorization and capture payment workflows with manual or automatic capture options
- Billing and shipping profile updates from PayPal customer data
- Customizable Smart Payment Button styles (layout, color, shape, label)
- Multiple funding source support (PayPal, credit cards, Pay Later, Venmo, Bancontact, iDEAL, etc.)
- Reference transactions support for Payflow Link
- IPN (Instant Payment Notification) handling for Express Checkout
- Views integration with Credit Messaging area handler for cart displays
- Custom checkout flows optimized for PayPal Checkout and Fastlane payment methods
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.