1. Documentation /
  2. Extensions /
  3. WooCommerce PayPal Payments

WooCommerce PayPal Payments

PayPal Payments is our recommended PayPal extension. If you are using an existing PayPal product, you will find details to upgrade here.

WooCommerce PayPal Payments is a full-stack solution that offers powerful and flexible payment processing capabilities. Set up quickly. Enable payment acceptance easily. Offer your customers a seamless checkout experience and get paid quickly.

WooCommerce PayPal Payments is the only payments extension that includes PayPal, Pay Later, Vaulting, advanced credit and debit card processing, and local payment methods.

By integrating with WooCommerce PayPal Payments, you can:

  • Offer full-stack payment processing – the choice of payment methods for your customers.
  • Smart payment buttons – present relevant payment methods to your customers in specific markets. With one integration, sellers can automatically offer more payment method options as they become available.
  • Fully customizable card fields for Advanced Card Payments.
  • Use the latest PayPal features all in one integration.

Requirements ↑ Back to top

To install WooCommerce PayPal Payments, you need:

  • WordPress Version 5.3 or newer (installed)
  • WooCommerce Version 3.9 or newer (installed and activated)
  • PHP Version 7.1 or newer
  • PayPal business or personal account

Installation ↑ Back to top

  1. Log in to WordPress Admin.
  2. Go to Plugins > Add New.
  3. Search for the WooCommerce PayPal Payments plugin.
  4. Click on Install Now and wait until the plugin is installed successfully.
  5. You can activate the plugin immediately by clicking on Activate now on the success page. If you want to activate it later, you can do so via Plugins >Installed Plugins.

Account Setup and Onboarding ↑ Back to top

Testing in Sandbox ↑ Back to top

NoteAll transactions done in the Sandbox are for testing purposes only and will not receive funds.

  1. Visit https://developer.paypal.com
  2. Log in using your PayPal account credentials.
  3. Go to Sandbox -> Accounts
  4. Either create a new business or personal account or use the existing pre-generated business account.
  5. For the Sandbox account you would like to use, click the under Manage Accounts and select View/Edit Account.
  6. Note down the email address and password for the account.

Connect a PayPal account ↑ Back to top

Once the WooCommerce PayPal Payments plugin has been installed and activated, it needs to be connected to your PayPal account.

The integrated onboarding connects a PayPal account via login credentials (email and password) without the need for API credentials. The onboarding automatically creates a new REST application in the PayPal developer site, registers the webhooks, and enables relevant features such as Vaulting. If desired, the account can also be connected manually.

  1. After installing and activating the WooCommerce PayPal Payments plugin, go to WooCommerce  > Settings.
  2. Click the Payments tab.
  3. The Payment methods list will include two PayPal options.
  4. Click Set Up (or Manage if the extension is already active) next to PayPal. (not PayPal Standard).
  5. The PayPal Checkout tab presents different options for the onboarding process:
  • Enable PayPal Payments — includes PayPal, Venmo, Pay Later — with fraud protection
    • This setting is mandatory as PayPal Payments automatically provides eligible payment methods. Individual funding sources can be hidden after the onboarding is completed.
  • Securely accept all major credit & debit cards on the strength of the PayPal network
    • Enables/disables credit card functionality and can be changed after onboarding. If selected, PayPal Payments provides two different credit card processing options:
    • Advanced Card Processing:
      • PayPal acts as the payment processor for card transactions. Card fields are fully customizable and provide optional features like Vaulting or Chargeback Protection for more security. Additional vetting by PayPal is required and prompted automatically during the onboarding.
    • Standard Card Processing:
      • Card transactions are managed by PayPal in a prebuilt user experience, which simplifies your compliance requirements. Suitable for all business and personal seller accounts
  1. Select either Standard Card Processing or Advanced Card Processing to onboard your account with credit card features enabled.
  2. Click Activate PayPal and follow the prompts to connect your existing live PayPal account and Test payments with PayPal Sandbox to connect a PayPal Sandbox account. If you do not have a PayPal account yet, you can create a new one from this window.
  1. After the onboarding was completed and the site refreshed, ensure the checkbox next to Enable/Disable is checked and click Save changes. The PayPal gateway and smart buttons should now appear in the Checkout page.

Manual credential input ↑ Back to top

If preferred, the PayPal account can also be connected manually with API credentials.

Clicking Toggle to manual credential input reveals the input fields. A REST application must be created on the PayPal developer site to retrieve the API credentials needed to connect the account. The steps below describe how to find the required PayPal Merchant ID, Client ID, and Secret Key.

Note: After connecting the REST API credentials manually, the webhooks must be registered via the Webhook Status settings page and Vaulting must be manually enabled in the REST application on the PayPal developer site to enable it in the plugin settings.

Manual credential input toggled

Obtaining the Merchant ID

PayPal Payments requires the Merchant ID, a unique ID for every PayPal account.

The Merchant ID helps to protect your identity. More information about it is available in the PayPal documentation: How do I find my Secure Merchant ID on my PayPal account?

PayPal Merchant ID

Sandbox accounts can also view the Merchant ID from the same page on the corresponding sandbox.paypal.com website, or from the developer site (Merchant ID may be listed as Account ID on the PayPal developer site).

Obtaining the Client ID & Secret Key

The Client ID & Secret Key can only be obtained from the PayPal Developers Website.
More information about the REST API setup is available in the PayPal documentation.

  1. Visit the PayPal developer dashboard: https://developer.paypal.com/
  2. Log in with your PayPal account. Every PayPal account is automatically a PayPal developer account with access to this site.
  3. In the top left corner, click My Apps & Credentials. From this page, choose between creating a Sandbox or a Live app before clicking Create App.
  4. Fill in your desired name for the new app (e.g. WooCommerce PPCP) and click Create App. Sandbox apps may need to be assigned to a specific Sandbox account on this page.
  5. On the next page, PayPal displays the account email address, the Client ID, and Secret Key.
Client ID & Secret Key

Plugin Configuration ↑ Back to top

General PayPal Checkout Settings ↑ Back to top

General PayPal Checkout Settings
  • Title – The title the user sees during the checkout process.
  • Description – The description the user sees during the checkout process.
  • Intent – The intent is to either capture a payment immediately after an order is created or authorize a payment for later capture.
  • Instant Payments – If you enable this setting, PayPal will be instructed not to allow the buyer to use funding sources that take additional time to complete (e.g., eChecks). Instead, the buyer will be required to use an instant funding source, such as instant transfer, credit/debit card, or Pay Later.
  • Brand Name – Control the name of your shop that customers will see during the payment process.
  • Landing Page – Type of PayPal page to display.
  • Hide Funding Source(s) – All possible funding sources will be shown by default. You have the option to disable funding sources such as Credit Cards, Pay Later, Venmo, or other Alternative Payment Methods.
  • Vaulting – Enable Vaulting to save cards and PayPal accounts. Required to use subscription features on your store.
  • Logging – Enable logging of unexpected behavior. This can also log private data and should only be enabled in a staging environment or if any issues occur.
  • Invoice prefix – If you use your PayPal account with more than one installation, you should use a distinct prefix to separate those installations.

Button on Checkout ↑ Back to top

  • Enable buttons on Checkout – Enable/Disable PayPal buttons at Checkout.
  • Button Layout – If additional funding sources are available to the buyer through PayPal, multiple buttons are displayed in the space provided. Choose “vertical” for a dynamic list of alternative and local payment options or “horizontal” when space is limited.
  • Tagline – Add a tagline. This will only appear if you select a horizontal layout.
  • Button Label – This controls the label on the primary PayPal button.
  • Color – Controls the background color of the primary PayPal button. Use “Gold” to leverage PayPal’s recognition and preference, or change it to match your site design or aesthetic.
  • Shape – The pill-shaped button’s unique and powerful shape signifies PayPal in people’s minds. Use the rectangular button as an alternative when pill-shaped buttons might pose design challenges.

Pay Later Messaging on Checkout ↑ Back to top

  • Enable message on Checkout Enable/Disable the Pay Later message at Checkout.
  • Pay Later Messaging layout – The layout of the Pay Later message.
  • Pay Later Messaging logo – What logo does the Pay Later message contain. Only applicable when the Text layout style is selected.
  • Pay Later Messaging logo position – The position of the Pay Later logo. Only applicable, when the Text layout style is selected.
  • Pay Later Messaging text color – The color of the text. Only applicable, when the layout style Text is used.

Button on Single Product ↑ Back to top

This section has the same styling options as the Buttons on Checkout settings above.

  • Enable buttons on Single Product – Enable/Disable buttons on Single Product.
  • Button Layout – If additional funding sources are available to the buyer through PayPal,  multiple buttons are displayed in the space provided. Choose “vertical” for a dynamic list of alternative and local payment options or “horizontal” when space is limited.
  • Tagline – Add the tagline. This line will only show up if you select a horizontal layout.
  • Button Label – This controls the label on the primary button.
  • Color – Controls the background color of the primary button. Use “Gold” to leverage PayPal’s recognition and preference, or change it to match your site design or aesthetic.
  • Shape – The pill-shaped button’s unique and powerful shape signifies PayPal in people’s minds. Use the rectangular button as an alternative when pill-shaped buttons might pose design challenges.

Pay Later Messaging on Single Product ↑ Back to top

This section has the same styling options as the Pay Later on Checkout settings above.

  • Enable message on Single Product – Enable/Disable Pay Later message on Single Product.
  • Pay Later Messaging layout – The layout of the Pay Later message.
  • Pay Later Messaging logo – What logo does the Pay Later message contain. Only applicable when the layout style Text is used.
  • Pay Later Messaging logo position – The position of the Pay Later logo. Only applicable when the layout style Text is used.
  • Pay Later Messaging text color – The color of the text. Only applicable, when the layout style Text is used.

Buttons on Cart ↑ Back to top

This section has the same styling options as the Buttons on Checkout settings above.

  • Buttons on Cart – Enable/Disable PayPal buttons on a Cart.
  • Button Layout – If additional funding sources are available to the buyer through PayPal, multiple buttons are displayed in the space provided. Choose “vertical” for a dynamic list of alternative and local payment options or “horizontal” when space is limited.
  • Tagline – Add the tagline. This line will only show up if you select a horizontal layout.
  • Button Label – This controls the label on the primary button.
  • Color – Controls the background color of the primary button. Use “Gold” to leverage PayPal’s recognition and preference, or change it to match your site design or aesthetic.
  • Shape – The pill-shaped button’s unique and powerful shape signifies PayPal in people’s minds. Use the rectangular button as an alternative when pill-shaped buttons might pose design challenges.

Pay Later Messaging on Cart ↑ Back to top

This section has the same styling options as the Pay Later on Checkout settings above.

  • Enable message on Cart – Enable/Disable the Pay Later message on Cart.
  • Pay Later Messaging layout – The layout of the Pay Later message.
  • Pay Later Messaging logo – What logo does the Pay Later message contain. Only applicable when the layout style Text is used.
  • Pay Later Messaging logo position – The position of the Pay Later logo. Only applicable when the layout style Text is used.
  • Pay Later Messaging text color – The color of the text. Only applicable when the layout style Text is used.

Buttons on Mini Cart ↑ Back to top

This section has the same styling options as the Buttons on Checkout settings above and an additional Button Height setting.

  • Buttons on Mini Cart – Enable/Disable PayPal buttons on a Mini Cart.
  • Button Layout – If additional funding sources are available to the buyer through PayPal,  multiple buttons are displayed in the space provided. Choose “vertical” for a dynamic list of alternative and local payment options or “horizontal” when space is limited.
  • Tagline – Add the tagline. This line will only show up if you select a horizontal layout.
  • Button Label – This controls the label on the primary button.
  • Color – Controls the background color of the primary button. Use “Gold” to leverage PayPal’s recognition and preference, or change it to match your site design or aesthetic.
  • Shape – The pill-shaped button’s unique and powerful shape signifies PayPal in people’s minds. Use the rectangular button as an alternative when pill-shaped buttons might pose design challenges.
  • Button Height – Set a dedicated button height with a value ranging from 25 to 55.

PayPal Card Processing ↑ Back to top

After completing the onboarding process for Advanced Card Payments, follow these steps to navigate to the PayPal Card Processing settings:

  1. Go to WooCommerce  > Settings > Payments > PayPal.
  2. Click the PayPal Card Processing tab.
  3. Check Enable/Disable to activate advanced card features and a separate checkout gateway exclusively for card payments.
PayPal Card Processing settings page

The following settings can be configured for PayPal Card Processing:

  • Enable/Disable – Once enabled, the Credit Card option will show up in Checkout.
  • Title – This controls the title that the user sees during Checkout.
  • Vaulting – Enable Vaulting to save cards and PayPal accounts. Required to use subscription features on your store.
  • Disable specific credit cards – All possible credit cards will be accepted by default. You have the option to disable certain credit cards.
  • Show logo of the following credit cards – Define which credit card logos you want to display for the gateway.
  • Contingency for 3D Secure – Select a preferred 3D Secure behavior:
    • No 3D Secure – causes transactions to be denied if 3D Secure is required by the bank of the cardholder.
    • 3D Secure when required – returns a 3D Secure contingency when it is a mandate in the region where you operate.
    • Always trigger 3D Secure – triggers 3D Secure for every transaction, regardless of SCA requirements. Learn more about 3D Secure.

Read PayPal Card Processing – Advanced Credit and Debit Card payments for more information about advanced card payments.

Webhook Status ↑ Back to top

PayPal Payments transmits events from and to PayPal via webhooks, while previous PayPal integrations primarily relied on IPN. The onboarding wizard automatically configures the relevant webhooks. Manually connecting the REST API credentials requires webhooks to be registered manually via the Webhooks Status settings page. This page provides an interface to simulate and resubscribe to the webhooks without visiting the PayPal developer site.

Webhooks Status settings page

To ensure the plugin is subscribed to the latest webhooks, click on Resubscribe, and after the page is reloaded, Simulate to verify that the webhooks are received. Follow the steps outlined in the Troubleshooting section if the webhook simulation results in an error popup.

Resubscribing to the webhooks can be helpful, for example, when WooCommerce orders are not changing their status after a completed payment or when refunds have been processed at PayPal.
Most of the provided Alternative Payment Methods rely on the webhooks being configured correctly to capture the funds.

Customer Experience ↑ Back to top

Smart buttons, Vaulting, and PayPal Card Processing ↑ Back to top

Smart buttons on single product, Cart, Mini Cart, Checkout ↑ Back to top

PayPal on non-checkout pages ↑ Back to top

The buttons on the single product and (Mini) Cart page skip most of the WooCommerce checkout process by transmitting address details from the buyer PayPal account to the WooCommerce native Checkout page.

PayPal Payments buttons on product and cart pages are meant to reduce the amount of data entry required by the customer (address details). To achieve this, PayPal sends the customer’s billing information after they log into PayPal and authorize the transaction.

Example scenario:

  • Customer shops on your site
  • Customer adds products to Cart
  • Customer reviews Cart page
  • From the Cart page, the customer selects the PayPal button
  • The customer is presented with a PayPal popup window to which WooCommerce sends the order subtotal, customer information, etc.
  • Customer logs in to the PayPal account and authorizes the transaction*
  • PayPal redirects the customer to the WooCommerce Checkout page with an authorization token and customer’s billing information
  • On the WooCommerce Checkout page, the customer reviews any taxes and chooses a shipping option. Address details are already provided by PayPal.
  • The customer finalizes the order with the “Place order” button in your native Checkout, and the transaction is completed with PayPal

*Order authorization is obtained for an amount that is 150% of the subtotal to anticipate taxes and shipping costs. If there are no taxes or shipping costs, then the original amount is used. If there are shipping/taxes, the updated total is used.

PayPal on Checkout page ↑ Back to top

On the regular WooCommerce Checkout page, the buyer must first provide the required address details before the PayPal button can complete the payment.
As of PayPal Payments version 1.7.0, the WooCommerce form field validation happens after the PayPal order has been created.

Plugin features explained ↑ Back to top

PayPal Card Processing – Advanced Credit and Debit Card payments ↑ Back to top

PayPal Payments comes with two different methods of accepting credit card payments: The regular black credit/debit card smart button, and the new PayPal Card Processing.

Default branded Debit/Credit Card smart button

PayPal Payments provides a branded credit/debit card smart button on the Checkout page when onboarding with Standard Card Processing selected:

PayPal-branded Credit Card button on the Checkout page

The PayPal-branded credit/debit card smart button is available for business and personal seller accounts. In most cases, it provides buyers the option to pay without a PayPal account. PayPal may require the user to create a PayPal account or log in to an existing one to complete a card payment under certain circumstances.

For example, buyers will need to log into a PayPal account for credit card payments with the credit card smart button when the Vaulting feature is enabled.

The branded smart button makes it apparent PayPal is the payment processor for this card payment. The button can be hidden with the Hide Funding Source(s) setting or by activating the PayPal Card Processing.

PayPal Card Processing

The PayPal Card Processing provides unbranded, fully customizable “hosted fields” on the site to enable advanced credit card features such as Vaulting and automatic subscription renewal payments.

PayPal Card Processing on the Checkout page

The PayPal Card Processing implements PayPal’s Advanced Credit and Debit Cards and is available for business accounts operating from these countries: PayPal documentation: Advanced credit and debit country and currency availability

Signing up for Advanced Credit and Debit Card features

Advanced credit and debit card functionality requires that your business account be evaluated and approved by PayPal. You will automatically complete this process when connecting with the onboarding wizard and Advanced Card Processing selected.

The Activate PayPal button automatically prompts the sign-up form for Advanced Credit and Debit Cards. PayPal may request more information about your business before the account is approved.

The feature can also be signed up for after the account was connected with Standard Card Processing selected or manually with API credentials:

Sandbox accounts must follow the same opt-in process to activate advanced card functionality: PayPal documentation: Enable your account for advanced debit and credit card processing

Activate PayPal Card Processing for Advanced Credit and Debit Card features

Visit the PayPal Card Processing tab in the plugin settings and enable the feature to activate advanced credit card functionality.

The default credit/debit card smart button on the Checkout page is automatically replaced by a new payment gateway exclusively for credit and debit cards.

To allow buyers to save their credit cards for future payments, enable the Vaulting feature.

This gateway has no PayPal branding, and its look can be fully customized with CSS to integrate natively into your Checkout page.

Testing Advanced Credit and Debit Card features with PayPal Sandbox

The PayPal Card Processing implements on-site hosted fields to deliver an SCA and PCI compliant payment experience thanks to support for advanced features like Vaulting and 3D Secure 2.

The Vaulting feature requires special cards for testing: PayPal documentation: Vault-ready test cards

Note: Credit cards can only be vaulted with the PayPal Card Processing and not the standard credit card smart button.

3D Secure 2 requires dedicated test cards and older 3d Secure credit cards from the official PayPal documentation may not work anymore since they only cover 3D Secure 1 scenarios.

3D Secure 2 test cards:

These sandbox test cards trigger a successful 3D Secure 2 scenario with the PayPal Card Processing:
4020024518402084
5232106671708398

Regular, non-3D Secure & non-Vaulting payments can be tested with cards from the Card Generator in the PayPal developer dashboard.

Advanced card payments vs. standard card payments

The PayPal Card Processing provides more functionality than the regular credit card smart button. Here are some examples:

  • Users can pay with credit cards without requiring a PayPal account for every application.
  • More streamlined checkout experience through native-looking “hosted fields” integration with no PayPal branding.
  • Fully customizable Checkout fields.
  • PayPal Card Processing supports Vaulting, letting your customers save their credit cards for faster, easier subsequent checkouts or automatic subscription renewals.
  • Supports Strong Customer Authentication (SCA) as required in the European Economic Area (EEA) and other 3D Secure contingencies.
  • Lower transaction fees compared to regular PayPal-branded credit card payments.

Vaulting – Saving a Payment Method ↑ Back to top

The Vaulting feature allows registered buyers to save their credit cards or connect their PayPal accounts for faster, easier subsequent checkouts with a single click.
This feature can be used for automatic WooCommerce Subscription renewals (Reference Transactions required).

Enable Vaulting at PayPal and in the plugin settings

Note: The onboarding wizard is the recommended way to connect your account, as it will automatically configure the most relevant settings, including Vaulting.

The Vaulting feature can also be enabled manually from the PayPal developer dashboard for the REST application. This is only needed when manually connecting the account with previously existing API credentials instead of using the onboarding wizard:

Vaulting must be enabled for the PayPal account and in the plugin settings as well to activate subscription functionality. Vaulting can only be enabled in the plugin when the Pay Later messaging is disabled as both features are currently mutually exclusive:

  1. Once the account is connected, disable the options Pay Later on Checkout, Pay Later on Single Product Page, and Pay Later on Cart.
  2. Save the changes.
  3. Enable the option Vaulting under PayPal Checkout Settings and Save changes.

Enable Vaulting with PayPal Sandbox

Note: Vaulting is automatically enabled for the Sandbox REST App when using the onboarding wizard to connect. Only when connecting an existing REST App via manual credential input, Vaulting must be manually enabled in the PayPal developer dashboard.

To manually enable vaulting on your Sandbox REST App, follow these steps:

  1. Login to developer.paypal.com
  2. Under My Apps & Credentials, click on Default Application.
  3. Under the SANDBOX APP SETTINGS section, click on the Advanced options link displayed after Accept payments Enable one-time and subscription payments.


4. Enable the option Vault and click Save

Now you can enable the setting in the plugin and test automatic payments for subscriptions via PayPal.

Enable Vaulting on your Live Account

Note: Vaulting is automatically enabled for the Live REST App when using the onboarding wizard to connect. Only when connecting an existing REST App via manual credential input, Vaulting must be manually enabled in the PayPal developer dashboard.

To manually enable vaulting on your Live REST App, follow these steps:

  1. Connect your account to WooCommerce (see above).
  2. Visit https://developer.paypal.com.
  3. Login with the same PayPal account connected to WooCommerce.
  4. Click Live under My apps & credentials.
  5. Select the REST App you connected to the plugin.
  6. Scroll down to Live App Settings.
  7. Click Advanced options next to Accept Payments.
  8. Place a checkmark next to Vault.
  9. Click Save at the bottom of the box.

Note: Your PayPal account has to be approved for Reference Transactions to use vaulted PayPal buyer accounts for automatic Subscriptions renewals. Credit cards can be vaulted and used for automatic payments without requiring Reference Transactions.

Vaulting a PayPal account

Once the Vaulting setting is enabled, PayPal accounts are automatically stored in the secure vault. Buyers can then use the vaulted payment method for subsequent payments with a single click while present on your site as they are logged in automatically.

The seller can flexibly charge the vaulted PayPal account without the user being present on the site when Reference Transactions are available for the seller account. This is used for subscription renewals, for example.

Vaulting a credit card

The PayPal Card Processing gateway can vault credit cards for future use. The standard credit/debit card smart button cannot vault a card, but it can display the credit card smart button with an already vaulted card as can be seen in the Customer Experience screenshots.

The Vaulting feature can be tested in the sandbox with these cards: PayPal documentation: Vault-ready test cards

In live mode, all supported credit and debit card types can be vaulted.

Note: Credit cards can only be vaulted with the PayPal Card Processing and not the standard credit card smart button. Regular sandbox credit cards not included in the document above cannot be vaulted at all.

View/delete vaulted payment methods

Vaulted payment methods can be viewed and deleted in the My Account  > PayPal Payments section while Vaulting is active.

New payment methods can only be vaulted by completing a payment.

In a future release, PayPal Payments will receive functionality to add a new payment method from this page without completing a purchase.

Vaulting for subscriptions via WooCommerce Subscriptions

Unlike PayPal Standard, PayPal Payments does not create a subscription at PayPal. Instead, PayPal Payments saves a payment method on the site in a secure Vault. The vaulted payment method can be charged for subsequent checkouts or renewal payments without the buyer being present on the site. Vaulting is a requirement for automatic subscription renewals but not for manual renewals.

Vaulted payment methods allow the buyer to pay for an order or manually confirm a subscription renewal without having to log in to the PayPal account or manually enter the credit or debit card details.

To charge the vaulted payment method for automatic subscription renewals while the buyer is not present on the site, the PayPal merchant account has to be approved for Reference Transactions. Without Reference Transactions, buyers must manually confirm renewal payments for payments with PayPal.

Vaulted credit cards can be charged for automatic payments without the buyer being present on the site and without being approved for Reference Transactions since no billing agreement will be created for credit card transactions.

For more details on how PayPal Payments works with WooCommerce Subscriptions, please view the Subscriptions FAQ.

Troubleshooting Vaulting

Vaulting via PayPal JavaScript SDK is an asynchronous process and can potentially fail for various reasons.

For example: When a billing agreement already exists between a buyer and seller, it will not be possible for the buyer to vault a PayPal account while the existing billing agreement is active.

Vaulting a payment method establishes a new billing agreement between the user and seller, and there can only ever be a single active billing agreement between two users.

After an existing billing agreement has been canceled, a new one can be created right away.

When a payment method could be saved at PayPal for subscription-type products, the order will usually be failed right away to prevent issues with automatic renewal payments not happening.

Subscriptions FAQ ↑ Back to top

Requirements for subscriptions

Supported subscription features

Basic Features:
  • Subscription Suspension
  • Subscription Cancellation
  • Subscription Reactivation
Advanced Features:
  • Multiple Subscriptions
  • Recurring total changes
  • Payment date changes
  • Customer payment method changes (requires vaulted payment method)
  • Store manager payment method changes (requires vaulted payment method)

Automatic subscription renewals

Payment methods are stored in a safe Vault and can be charged for automatic renewals while the buyer is not present on the site. Requires Reference Transactions are enabled for the merchant PayPal account for automatic renewals with PayPal accounts.
Automatic subscription renewals for credit card payments via PayPal Card Processing do not require Reference Transactions since no billing agreement will be created for such transactions.

Manual subscription renewals

The customer can use vaulted payment methods while being present on the site to manually process a payment for a subscription renewal. The vaulted payment method allows the buyer an easier and faster login/payment process by not having to manually log in with the PayPal account credentials.

Vaulting is not a requirement for subscriptions if manual renewals are enabled in the WooCommerce Subscriptions settings. Buyers will be able to buy subscription products and renew them manually without having a vaulted payment method.
When Vaulting is enabled, the plugin ensures a payment method could be saved at PayPal for subscription-type products and will potentially fail the order if no payment method could be saved.

Changing a subscription payment method

Existing subscriptions from other payment gateways can be switched to PayPal Payments when a payment method has already been vaulted for the buyer with PayPal Payments. This requires a separate purchase to vault the payment method before the existing subscription could be switched to the previously saved payment method.

Multiple and pre-existing subscriptions

Once a payment method has been saved in the Vault, it can be used for multiple concurrent subscriptions (varying amounts or renewal dates).
Suppose the buyer already has an ongoing subscription with an active billing agreement at PayPal. In that case, the existing billing agreement must be canceled before a PayPal payment method could be saved with PayPal Payments.

The subscription migration layer in PayPal Payments allows automatic renewals of existing PayPal Checkout subscriptions. Still, as long as the previous billing agreement is active, the same buyer will be unable to vault their PayPal account with the same merchant. Follow these steps to cancel existing billing agreements at PayPal:

  1. Login to merchant PayPal account.
  2. Click on merchant name in top right.
  3. Click on “Account Settings”
  4. Click “Website Payments” on left.
  5. Click Update next to “Automatic Payments”
  6. Select the agreements they want to cancel.
  7. Click “Cancel” link in the “Actions” panel.

Free trials & synchronized payment dates

PayPal Payments version 1.8.0 implements functionality to enable checkouts for subscriptions with a free trial period.
Subscriptions with prorated & synchronized payment dates will be supported with a future update.
To purchase a subscription product with a free trial period, the buyer first must vault a payment method. From the Checkout page, the PayPal button redirects the buyer to the PayPal website where the PayPal account can be authorized for future transactions.

How is the account saved in the Vault?

To save the PayPal account for future payments in the Vault, PayPal Payments authorizes and then voids a $1 payment.
If the buyer has no funds available and no payment method connected to the account, the free trial cannot be purchased.


After the PayPal account has been saved in the Vault for the current user session, the checkout fields may be refreshed when the buyer is returned to the Checkout page. From here, the buyer can complete the subscription purchase with the regular Sign up now button.

PayPal Payments versions before 1.8.0 or setups with prorated & synchronized payment dates must utilize either a sign-up fee or enable “Zero-sum checkouts” in the WooCommerce Subscriptions plugin settings to process subscriptions payments for free trials or synchronized payment dates respectively.

Compatibility with third-party subscriptions plugins/addons

As of version 1.8.0, PayPal Payments officially supports Simple Subscription and Variable Subscription product types from the official WooCommerce Subscriptions plugin.

Custom subscription product types or third-party subscription plugins are not supported and may not yield the expected result. This includes regular products with a subscription plan from the All Products for WooCommerce Subscriptions plugin.
Q: Which issues could occur?
A: In the worst case, the initial subscription payment is captured, and the subscription is started, but subsequent renewals may fail if no payment method has been saved. This behavior could potentially be prevented by setting the Intent to Authorize.

Broader subscription compatibility with third-party plugins and setups relying on manual renewals will be added in a later update.

Pay Later ↑ Back to top

Pay Later is PayPal’s latest innovation to help drive conversion rates up by providing flexible financing options.
Visit the PayPal documentation for more details about Pay Later: PayPal documentation: Pay Later offers

Turn browsers into buyers with Pay Later

Increase sales with Pay Later offers, allowing customers to pay later while you get paid upfront. Merchants in the US can offer their customers Pay in 4 and PayPal Credit, while merchants in the UK, France, Germany, and Australia can offer the Pay Later installments option specific to their country. US businesses with pay-over-time messaging on their site have seen their average order value increase by up to 56%.

Pay Later Buttons

Your existing PayPal buttons change to show a new Pay Later button when eligible. When customers select Pay Later, they can pay with flexible, buy now, pay later offers.

Pay Later button

Advertise it the right way

Pay Later messaging on your site lets your customers know about flexible payment options while browsing, helping convert more sales. In fact, 80% of buy now pay later (BNPL) users in the US agree that seeing a BNPL message while browsing gives allows them to spend more.

Pay Later messaging

Pay Later messaging can be enabled on the single product page, Cart, and Checkout and helps you get the most out of PayPal’s buy now, pay later offers. You can use this onsite messaging to dynamically promote Pay Later offers, which can help grow your sales, attract new customers, and drive customer loyalty.

Pay Later messaging

Customize Pay later messaging

The Pay later messaging can be customized with several different styles to suit your needs: PayPal documentation: Pay Later messaging 

Pay with Venmo ↑ Back to top

Based on eligibility, PayPal Payments automatically provides buyers with a Venmo button.

Add Venmo as a payment button

Pay with Venmo offers a simplified mobile checkout experience with no additional steps to set up or cost to you. Your buyers get:

  • A streamlined checkout process.
  • Splitting and sharing of purchases.

All funds will be automatically forwarded to the connected PayPal business account.

How it works

When eligible, your buyers can use Venmo on the same pages they can use PayPal, including your product page, Cart page, and Checkout page.

Venmo checkout flow

When buyers select Venmo, they can pay in their Venmo app.

The full Venmo checkout flow is described in the PayPal developer documentation: PayPal documentation: Pay with Venmo – Buyer experience

Eligibility

Alternative Payment Methods, including Venmo, require PayPal business accounts and are not supported with personal seller accounts.

More information about the Eligibility for Venmo is available at the PayPal developer documentation: PayPal documentation: Pay with Venmo eligibility

How to disable the Venmo button?

All Alternative Payment Methods, including the Venmo button, can be individually hidden with the Hide Funding Source(s) setting.

Alternative Payment Methods ↑ Back to top

Alternative Payment Methods (APMs) are automatically enabled for all PayPal business accounts. Private seller accounts do not support APMs.

What are Alternative Payment Methods

APMs allow you to accept payments from customers around the globe who use their bank accounts, wallets, and local payment methods. When a buyer pays in a currency different than yours, PayPal handles currency conversion for you and presents conversion information to the buyer during checkout.

For example, a customer in the Netherlands might want to pay using iDEAL, which more than half of consumers in the Netherlands used for online purchases. In contrast, a customer in Belgium on the same website might want to pay using Bancontact, a popular payment method there.

PayPal Payments automatically provides payment methods that are relevant to the user.

Which Alternative Payment Methods are supported?

As of March 2022, PayPal Payments supports the following APMs:

  • Bancontact
  • BLIK
  • eps
  • giropay
  • iDEAL
  • Mercado Pago
  • MyBank
  • Przelewy24 (P24)
  • SEPA Direct Debit
  • SOFORT
  • Venmo

The latest list of supported APMs can be found in the PayPal documentation – APM Availability.

How to disable Alternative Payment Methods?

Alternative Payment Methods can be individually hidden with the Hide Funding Source(s) setting.

Alternative Payment Methods on non-Checkout pages

The credit card smart button renders only on the Checkout page and not on the single product, or Cart page to provide a more consistent user experience.

The following payment methods are available from the non-Checkout pages: PayPal, Pay Later, Venmo, and SEPA Direct Debit.

All other funding sources (including credit cards) are only available from the Checkout page.

WooCommerce PayPal Checkout gateway migration layer

Starting with version 1.5.0, PayPal Payments integrates a migration layer to carry over existing configurations from the no longer supported PayPal Checkout gateway plugin.
Only the PayPal account must be connected once and most of the settings (button styling, etc.) will be automatically migrated from the old to the new plugin.
The migration layer will also take over subscription renewals from PayPal Checkout when the latter is not active. This allows you to completely disable or remove the PayPal Checkout extension, while subscription renewals continue to be processed as usual.
We recommend disabling the PayPal Standard and PayPal Checkout gateways (under WooCommerce > Payments) to prevent customers from purchasing new subscriptions using those gateways.

The Vaulting section describes how new subscriptions are handled with PayPal Payments.

Frequently Asked Questions ↑ Back to top

Does PayPal Payments include support for Subscriptions? ↑ Back to top

Yes, PayPal Payments supports automatic recurring payments when used with WooCommerce Subscriptions (separate purchase).

To process automatic subscription renewals for PayPal payments, Vaulting must be enabled and Reference Transactions must be available. Credit card subscription payments do not require Reference Transactions.

For more details, see: Subscriptions FAQ and Vaulting – Saving a Payment Method

Additionally, PayPal Payments includes a subscription migration layer to renew existing subscriptions created by the previous PayPal Checkout plugin.
Subscriptions created with the old PayPal Standard integration continue to be renewed by PayPal and like existing Checkout subscriptions lock buyers into having one single subscription, preventing additional PayPal subscription purchases with PayPal Payments: Multiple, and pre-existing subscriptions

PayPal Payments Smart Buttons are not displaying on my Single Product/Cart/Checkout page ↑ Back to top

The regular “Place order” button will be hidden and replaced by the PayPal Smart Buttons which can take a few seconds after connecting a new PayPal account or saving the plugin settings.

Caching or CSS/JavaScript modifications can impact the smart button functionality and should exclude code from the PayPal Payments plugin. If using any minification features from third-party plugins, make sure to exclude/whitelist at least the JavaScript in this path:

woocommerce-paypal-payments/modules/ppcp-button/assets/js/button.js

Please follow the steps outlined in Troubleshooting if the buttons are still not loading and get in touch with us if any questions remain.

Why are PayPal scripts loading on every page of my site (frontend)? ↑ Back to top

The PayPal scripts are loaded only on pages with enabled smart buttons.
When the button for the Mini Cart is enabled, the scripts will be loaded on all non-Cart and non-Checkout pages of the site.
Disabling the Mini Cart button prevents the scripts from being loaded on the above-mentioned pages.

Which currencies does PayPal support? ↑ Back to top

The PayPal REST API supports merchants in several countries and supports currencies depending on the payment type for PayPal payments, or direct credit card payments. For country-specific offerings and limitations, see PayPal Offerings Worldwide and visit your country-specific site. PayPal supports merchants operating from certain countries without supporting the local currency.
PayPal Payments provides extensive currency coverage through the PayPal REST API as listed in the PayPal documentation: Currency codes.

The country and currency eligibility page for advanced card payments lists supported countries/currencies for the PayPal Card Processing.

Beyond the customer being from a supported country, Alternative Payment Methods require specific currencies to appear.

Plugin modifications (actions and filters) ↑ Back to top

The PayPal Payments GitHub Wiki lists available actions and filters to extend or modify the plugin. Filters are available for the following use cases:

Troubleshooting ↑ Back to top

Do you encounter a problem? Follow these steps to make sure everything is set up correctly:

  • Please ensure that your site meets the plugin requirements.
  • Preferably connect your PayPal account with the onboarding wizard as this automatically configures the most important settings.
  • You can activate Logging via the plugin settings to collect more information about payments which helps the support to help you.
  • Temporarily activating the default theme Storefront and disabling all other plugins except for WooCommerce and PayPal Payments may help isolate a potential plugin conflict. How to test for conflicts contains more guidance and tips regarding conflict testing.

Read more about plugin and theme conflicts in the WooCommerce Self-Service Guide.

PayPal Payments-related documents:

PayPal API-related documents:

Documents relating to previous PayPal integrations:

Questions ↑ Back to top

Have a question or need some assistance? Get in touch with a Happiness Engineer via the Help Desk.

WooCommerce

The most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment