PayPal Pay Later banner Q1-23

  1. Documentation /
  2. 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, including PayPal Pay later.

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.2 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 Account Setup section 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:
    • 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
    • Advanced Card Processing:
  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, you can create a new one from this window.
  1. After the onboarding was completed and the site is refreshed, ensure the checkbox next to Enable/Disable in the Standard Payments tab is checked and click Save changes. The PayPal gateway and smart buttons should now appear in the Checkout page.

Complete setup guide for PayPal Payments

How to Integrate PayPal Payments into WooCommerce

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

This video explains how to create a REST App on the PayPal developer website:

How to Create a PayPal App

Plugin Configuration

↑ Back to top

The plugin configuration is explained in the sections below.

Connection

↑ Back to top

The Connection tab presents the plugin configuration relevant to the connected PayPal account. This includes the API credentials, the activation status for advanced features, or the webhook status.

Account Setup

↑ Back to top

After following the steps outlined in Connect a PayPal account, the REST API credentials for the connected PayPal account are displayed in this section.

Toggle the Sandbox checkbox to switch from live to sandbox accounts for testing purposes.

To connect a different PayPal account, click Disconnect Account and connect your account via the onboarding wizard.

Feature Onboarding

↑ Back to top

The Advanced feature availability & sign-up section displays the activation status for advanced features for the connected PayPal account.


Advanced features could be signed up for from this page if the account was not already enabled.

General integration configuration

↑ Back to top

The integration configuration includes the configuration for the invoice prefix and logging.
When using a PayPal seller account on multiple websites, a distinct prefix should separate those installations, as PayPal only accepts unique invoice numbers by default.

Logging should be enabled when transactions fail for unknown reasons or general troubleshooting purposes.

Webhook Status

↑ Back to top

While previous PayPal integrations primarily relied on IPN, PayPal Payments transmits events from and to PayPal via webhooks. The onboarding wizard automatically configures the relevant webhooks. Manually connecting the REST API credentials requires webhooks to be registered manually via the Webhooks Status section. This section 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 after refunds have been processed at PayPal.
Alternative Payment Methods rely on webhooks to be configured correctly to capture the funds.

Standard Payments

↑ Back to top

General Settings for PayPal Payments

↑ Back to top
  • Enable/Disable – Enable the PayPal Gateway checkbox to display PayPal smart buttons in your shop.
  • Title – The title for the PayPal gateway 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 can 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.
  • Subscription capture behavior if Vault fails – By default, subscription payments are captured only when saving the payment method was successful. Without a saved payment method, automatic renewal payments are not possible.
  • Card billing data handling – Using the WC form data increases convenience for the customers but can cause issues if card details do not match the billing data in the checkout form.
  • Separate Card Button from PayPal gateway – By default, the Debit or Credit Card button is displayed in the PayPal Checkout payment gateway. This setting creates a separate gateway only for the Card button.

PayPal Buttons

↑ Back to top

PayPal Payments implements the PayPal smart buttons on various pages of your site. The buttons can be configured individually for the Checkout page, single product page, Cart page, and Mini Cart.

Checkout Buttons

↑ Back to top

The Checkout Buttons must be enabled to display the PayPal gateway on the Checkout page. This PayPal gateway presents the buyer with PayPal smart buttons and eligible Alternative Payment Methods, such as Venmo or Pay Later.
Which set of buttons is loaded depends on multiple factors like the customer’s location or button configuration.

The button preview assists with the button styling for your shop but presented payment buttons may vary for customers on your site.

  • Enable buttons on Checkout – Enable/Disable PayPal buttons at Checkout. Disabling this removes the PayPal Checkout gateway.
  • 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.

PayPal Payments implements the PayPal Smart Button styling options as demonstrated in this video:

Smart Button styling options

Single Product Page Buttons

↑ Back to top

This section controls the smart buttons on the Single Product Page and 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.

Cart Buttons

↑ Back to top

This section controls the smart buttons on the Cart page and 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.

Mini Cart Buttons

↑ Back to top

This section controls the smart buttons on the Mini Cart and has the same styling options as the Buttons on Checkout settings above with an additional Button Height setting.
The Mini Cart Buttons are disabled by default. Enabling this section results in the PayPal scripts loading on (almost) every page on the website.

  • 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.

Pay Later

↑ Back to top

Pay Later allows customers to pay over time while you get paid upfront — at no additional cost.
This feature is available in selected locations and consists of the Pay Later button for the Checkout and Pay Later Messaging to advertise Pay Later offerings to eligible buyers.

Pay Later Button

↑ Back to top

To enable the Pay Later button, the PayPal smart buttons must be enabled. The Pay Later button can only be displayed together with the PayPal button, but can be controlled for individual button locations.

Pay Later Messaging

↑ Back to top

Pay Later messaging lets your buyers know they can buy now and pay later, if they check out with PayPal. Adding messaging to your website can help improve conversion, attract new customers, and increase order values.

Pay Later messages are dynamic, enabling you to show your customers their specific Pay Later offer, based on the contents of their shopping cart.

The messaging can be configured in the text format with these settings

  • Messaging layout – The layout of the Pay Later message.
  • Messaging logo – What logo does the Pay Later message contain. Only applicable when the Text layout style is selected.
  • Messaging logo position – The position of the Pay Later logo. Only applicable, when the Text layout style is selected.
  • Messaging text color – The color of the text. Only applicable, when the layout style Text is used.
  • Messaging layout – The layout of the Pay Later message.
  • Messaging Color – The color of the banner. Only applicable, when the layout style Banner is used.
  • Messaging Ratio – The width/height ratio of the banner. Only applicable, when the layout style Banner is used.

Pay Later messaging customization options are explained here.

Customize Messaging Per Location

↑ Back to top

By default, all Pay Later Messaging locations share the same styling configuration. The Customize Messaging Per Location setting enables customizations to the messaging for each enabled location.

Advanced Card Processing

↑ Back to top

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

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

The following settings can be configured for Advanced 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 Advanced Card Processing – Advanced Credit and Debit Card payments for more information about advanced card payments.

Standard Card Button

↑ Back to top

When enabling the Separate Card Button from PayPal gateway setting, the Standard Card Payments button is extracted from the PayPal gateway into a separate gateway called Standard Card Button.

Standard Card Button gateway settings
Standard Card Button gateway on the Checkout page

OXXO

↑ Back to top

OXXO is a Mexican chain of convenience stores with +19,800 stores in Latin America. It represents nearly 20% of online transactions in Mexico and allows customers to pay bills and online purchases in-store with cash. OXXO payments have a low risk of fraud or unrecognized payments because the customer must provide the payment in person.

This gateway only appears for merchants with their store location in Mexico.

Permission required

Get PayPal account permission to use OXXO payment functionality by contacting PayPal at (+52) 800-925-0304

OXXO gateway settings
OXXO gateway on the Checkout page

Pay upon Invoice

↑ Back to top

Pay upon Invoice (or Rechnungskauf mit Ratepay in German) is an invoice payment method only available for merchants in Germany.

Read Pay upon Invoice – Rechnungskauf for more information about the Pay upon Invoice requirements and configuration. After completing the onboarding process for Pay upon Invoice, follow these steps to navigate to the Pay upon Invoice settings:

  1. Go to WooCommerce  > Settings > Payments > PayPal.
  2. Click the Pay upon Invoice tab.
  3. All visible fields including Brand name and Customer service instructions must be filled with your information.
  4. Check Enable/Disable to activate the Pay upon Invoice gateway.
Pay upon Invoice settings page
  • Enable/Disable – Once enabled, the Pay upon Invoice option will show up in Checkout.
  • Title – This controls the title that the user sees during Checkout.
  • Description – This controls the description which the user sees during checkout.
  • Brand name – Merchant name displayed in Ratepay’s payment instructions.
  • Logo URL – Logo to be presented on Ratepay’s payment instructions.
  • Customer service instructions – Customer service instructions to be presented on Ratepay’s payment instructions.

Customer Experience

↑ Back to top

Smart buttons, Vaulting, and Advanced 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 pages skip most of the WooCommerce checkout process by transmitting address details from the customer’s PayPal account to the WooCommerce native Checkout form fields. This feature was previously called PayPal Express.

PayPal smart buttons on product and cart pages reduce the amount of data entry required by the customer (address details). To achieve this, PayPal sends the customer’s billing information to the WooCommerce Checkout 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 instead of proceeding to Checkout
  • The customer is presented with a PayPal popup window to which WooCommerce sends the order subtotal, customer information, etc.
  • The 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 the 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. This amount is capped at about $75.The original amount is used if there are no taxes or shipping costs. If there are shipping/taxes, the updated total is used.

Retrieve the buyer’s phone number

By default, PayPal does not transmit the buyer’s phone number from their PayPal account to the Checkout page.
To enable this functionality, log into your PayPal account and navigate here for Live accounts and here for Sandbox accounts: Account Settings > Website payments > Website preferences

Scroll down to the section Contact telephone number and set it either to On (optional field) or On (required field) depending on your Checkout page configuration.

Choose “On” to retrieve the buyer’s phone number

Retrieve the buyer’s billing and shipping details

By default, WooCommerce is configured to handle separate billing and shipping details for your orders.

When utilizing the Express Checkout buttons, PayPal, by default, only transmits the buyer’s shipping details to WooCommerce. Depending on the WooCommerce Checkout configuration, the shipping details will be inserted into the billing details on the WooCommerce Checkout page.

To enable the retrieval of separate shipping and billing information from PayPal to WooCommerce, contact the PayPal Merchant Support via the Call us or Message us option. Request PayPal to enable the billing address feature for your account so your Checkout page can be automatically populated with the complete buyer shipping and billing details.

PayPal on the Checkout page

↑ Back to top

The PayPal smart buttons on the WooCommerce Checkout page replace the “Place order” button. The buyer has to fill all required form fields before the smart buttons can initiate the payment.
Upon clicking any smart button, the form fields are first checked with a basic validation before creating the PayPal order. This basic form field validation checks whether or not the required fields are populated but not whether or not the input is valid. This validation can be disabled with a filter in case of potential compatibility issues with third-party code.
The regular WooCommerce form field validation occurs after the PayPal order has been created and may still display an error message if the buyer provided invalid form data. If the WooCommerce validation fails with an error message, the buyer will not be charged for the attempted payment.

Depending on customer eligibility and plugin configuration, Alternative Payment Methods are automatically presented in the PayPal Payments Checkout gateway.

Plugin features explained

↑ Back to top

Advanced Card Processing – Advanced Credit and Debit Card payments

↑ Back to top

PayPal Payments integrates two different methods of accepting credit card payments via PayPal:

  • Standard Card Payments display the branded Debit or Credit Card smart button and a prebuilt user experience
  • Advanced Credit and Debit Card Payments are called Advanced Card Processing and provide a fully customizable user experience

Advanced Card Processing

The Advanced Card Processing provides unbranded, fully customizable “hosted fields” on the site to enable advanced credit card features such as Vaulting and advanced fraud protection.

Customers can pay with supported debit & credit cards without requiring a PayPal account. With Vaulting enabled, the card can be saved for easier subsequent payments or automatic subscription renewals.

Advanced Card Processing on the Checkout page

The hosted fields can be styled with the theme or custom CSS.

The Advanced Card Processing is available for business accounts operating from these countries: PayPal documentation: Advanced credit and debit country and currency availability

If you do not have a PayPal business account yet or have not been evaluated, head to sign up for Advanced Credit and Debit Card features.

Standard Card Payments with branded Debit or Credit Card smart button

By default, PayPal Payments displays a set of payment methods including a branded credit/debit card smart button. This button is loaded only 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 allows buyers to pay without a PayPal account. But 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 prebuilt experience from the branded smart button makes PayPal the obvious payment processor for this card payment. The button can be hidden with the Hide Funding Source(s) setting or by activating the Advanced Card Processing gateway.

The setting Separate Card Button from PayPal gateway enables a separate payment gateway for the branded PayPal Debit or Credit Card button.

Advanced Card Payments vs. Standard Card Payments

The Advanced Card Processing provides more functionality compared to 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 card fields.
  • Fraud Protection gives you the insight and control you need to balance chargebacks and declines better. Included with Advanced Checkout at no extra cost.
  • Advanced 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.
  • In some markets, lower transaction fees compared to regular PayPal-branded credit card payments.

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 automatically initiate the signup when connecting with the onboarding wizard via Activate PayPal button when selecting the Advanced Card Processing option.

PayPal may request more information about your business before the account is approved for this advanced feature.

When the account was connected manually with API credentials or with Standard Card Processing selected, you can sign up for advanced card payments from here:

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

Activate Advanced Card Processing for Advanced Credit and Debit Card features

Visit the Advanced 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.

Enable the Vaulting feature to allow customers to save their credit cards for future payments.

This new gateway is unbranded and can be fully customized with CSS to integrate seamlessly into your native Checkout page.

Customizing the hosted fields

The default look of the hosted fields from the Advanced Card Processing depends on the active theme. Regardless of the theme, the fields can be customized with custom CSS.
CSS modifications on the hosted fields may not be immediately visible when using the WordPress customizer. Please save the CSS and refresh the site before the changes are visible.

CSS Selectors
FIELDSELECTOR
Button wrapper #id#ppcp-hosted-fields
Button class#ppcp-dcc-order-button
Card number id##ppcp-credit-card-gateway-card-number
Expiry id##ppcp-credit-card-gateway-card-expiry
CVV id##ppcp-credit-card-gateway-card-cvc
Save Credit Card box id# #saved-credit-card
List of CSS selectors for the Advanced Card Processing

Example: Changing the card number fields color and font-size/-weight. Some fields may require the !important attribute for the changes to apply.

#ppcp-credit-card-gateway-card-number {
	color: #7f54b3;
	font-size: 30px !important;
	font-weight: bold;
}

Testing Advanced Credit and Debit Card features with PayPal Sandbox

The Advanced Card Processing implements on-site hosted fields to deliver SCA & PCI compliant payment experiences and supports advanced features like 3D Secure 2 or Vaulting.

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

Note: Credit cards can only be saved in the Vault with the Advanced 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 Advanced 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.

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 for your PayPal account, including Vaulting.

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

Support for WooCommerce Subscriptions is automatically activated when the Vaulting feature is enabled in the plugin settings.

When Vaulting is enabled, the Pay Later button & APMs will be hidden and settings for the Pay Later messaging are disabled.
Vaulting and Pay Later are currently mutually exclusive.

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 Vaulting 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.

Requirements for automatic payments

Your PayPal account has to be approved for Reference Transactions to charge PayPal accounts from the Vault for automatic subscription renewal payments. Credit cards can be saved in the Vault and used for automatic payments without requiring Reference Transactions.

Vaulting a PayPal account

Reference Transactions are required for the merchant to save PayPal accounts in the Vault. Reference Transactions allow merchants to flexibly charge the buyer’s saved PayPal account for future payments. This feature is used for automatic subscription renewals, for example.

Once the Vaulting setting is enabled, PayPal accounts are automatically stored in the secure Vault when a payment is attempted. Once a payment method has been saved, customers can utilize it to complete subsequent PayPal payments with a single click. The customer has effectively logged into their PayPal account automatically when logged into their WordPress user account.
Repeat customers benefit from a simplified checkout process without being required to manually log into their PayPal account.

Vaulting a credit card

The Advanced 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 Advanced 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 saved payment methods from the Vault

Payment methods saved in the Vault can be viewed and deleted on the shop website in the My Account  > PayPal payments section while Vaulting is enabled.

New payment methods can only be saved in the Vault 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 in a secure Vault at PayPal. The vaulted payment method can be used 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.

Billing Agreements are required to save a PayPal payment method for automatic subscription renewals in the Vault, so the PayPal merchant account has to be approved for Reference Transactions. Without Reference Transactions, saving a PayPal payment method in the Vault may fail. In that case, the setting Subscription capture behavior if Vault fails must be configured not to fail & void subscription payments if saving the payment method was unsuccessful so buyers can manually confirm renewal payments via PayPal.

Vaulted credit cards via Advanced Card Processing can be saved in the Vault and used for automatic payments without the buyer being present on the site and without being approved for Reference Transactions.

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

Troubleshooting Vaulting

Saving a payment method in the Vault could potentially fail, but PayPal Payments usually cannot precisely determine the reason for the failure. For example, the lack of Reference Transactions may result in PayPal accounts not being saved in the Vault. Beyond this, unverified PayPal accounts or accounts without a linked payment source may not be eligible to save a payment method in the Vault.

Vaulting-specific limitation

A PayPal buyer account can only be saved in the Vault of the PayPal merchant account for one customer id (unique per WordPress user), not across multiple sites or customer ids. Reusing the same PayPal merchant account on multiple sites with Vaulting is not recommended, as it could lead to potential problems.

When a buyer attempts to buy a subscription product but the payment method could not be saved in the Vault, it may fail with this error: Could not process order because it was not possible to save the payment on PayPal.
The capture behavior for subscription orders can be controlled with the Subscription capture behavior if Vault fails setting.

Please contact the PayPal Merchant Technical Support with a copy of your plugin log files to request more details about why a payment method could not be saved for a specific case.

Subscriptions FAQ

↑ Back to top

Requirements for subscriptions

  • The official WooCommerce Subscriptions plugin is supported
  • Vaulting must be enabled in the plugin settings (can only be enabled when it is active for the PayPal REST application)
  • Reference Transactions are required to save PayPal accounts in the Vault for automatic subscription renewal payments
  • A feature to allow automatic PayPal renewals without requiring Reference Transactions is in development for early 2023
  • Automatic subscription renewal payments via Advanced Card Processing are possible without being enabled for Reference Transactions

Supported subscription features

Basic FeaturesFeature supported
Subscription Suspension
Subscription Cancellation
Subscription Reactivation
Advanced FeaturesFeature supported
Multiple Subscriptions
Recurring total changes
Payment date changes
Subscription Switching
Customer payment method changes
(requires saved payment method)
Store manager payment method changes
(requires saved payment method)
Free trial Subscriptions
Synchronized or prorated payments
Features supported with the WooCommerce Subscriptions plugin

Subscription flow

PayPal Payments uses Vaulting to save a payment method and applies special handling for WooCommerce Subscriptions products (Simple Subscription & Variable Subscription) to ensure successful renewal payments. Subscription products with a free trial period have a special checkout flow as the payment method is saved in the Vault without an actual payment.

Regardless of the configured Intent setting, subscription products are handled with payment authorizations. When the customer completes the subscription payment, the payment is first authorized, and a WooCommerce order is created in the “On-hold” status. If the intent Capture is configured, the authorized payment may be captured automatically within three minutes. During this time, a webhook should be received, which confirms whether or not the payment method was successfully saved in the PayPal Vault.

  • The subscription payment is automatically captured if the intent is configured with Capture and the payment method was successfully saved in the PayPal Vault. The payment authorization can be captured manually while waiting for the webhook confirmation, but this is not recommended.
  • If the intent is configured with Capture and the payment method could not be saved in the PayPal Vault, the behavior is determined with the Subscription capture behavior if Vault fails setting.

Subscription capture behavior if Vault fails

Saving a payment method in the Vault may fail under certain circumstances. The Subscription capture behavior if Vault fails option determines how these failure scenarios are handled.
The default configuration prevents subscription payments when the payment method was not saved in the Vault.

  1. Void authorization & fail the order/subscription (default)
    The authorized subscription payment is voided, and the order is set to Failed. This configuration prevents subscription signups and payments without a saved payment method.
    In this case, subscription orders would fail with the message “Could not process order because it was not possible to save the payment on PayPal. Order status changed from On hold to Failed.“
  2. Capture authorized payment & set subscription to Manual Renewal
    The authorized subscription payment is captured, and the subscription activates but is set to Manual Renewal. The failure to save the payment method is logged in an order note, and the payment confirmation mail for the customer includes additional information.
    The customer has to manually confirm the renewal payment until a new payment method was saved in the Vault. Once a payment method was saved in the Vault, the subscription payment method could be changed to automatically renew via PayPal Payments.
  3. Capture authorized payment & disregard missing payment method
    The authorized subscription payment is captured, and the subscription activates. The failure to save the payment method is disregarded, and WooCommerce Subscriptions will attempt to renew the subscription at the scheduled date. If no payment method was saved in the Vault by the time of the renewal, the automatic renewal payment would fail due to the lack of a saved payment method.

Configuring the intent Authorize prevents the failure of manual subscription payments. The authorized payment can be captured manually, but when the payment method is not saved in the Vault during the authorization, automatic renewal payments are still not possible. Automatic subscription renewal payments require a payment method saved in the Vault.

Read the Troubleshooting Vaulting section for more guidance.

Automatic subscription renewals

Payment methods are saved in the secure PayPal Vault. If Reference Transactions are enabled for the merchant PayPal account, the saved payment method can be used for automatic renewal payments without the customer being present on the site.

Once a WordPress user has saved a payment method in the Vault, it can be reused for multiple concurrent subscriptions (varying amounts or renewal dates). Subscriptions can be canceled without impacting the saved payment method or automatic renewals from active subscriptions.

If Reference Transactions are not enabled for the merchant account, customers can still save their payment method in the Vault. But renewal payments require the buyer to be logged in and manually confirm the (one-click) payment on the website. In this case, the Subscriptions plugin creates a new order in the “Pending payment” status for which the customer must manually confirm the payment.

A feature to allow automatic PayPal renewals without requiring Reference Transactions is in development for late 2022.

Automatic subscription renewals for credit card payments via Advanced Card Processing do not require Reference Transactions since no billing agreement will be created for such transactions.

Manual subscription renewals

The customer can use payment methods saved in the Vault while being present on the site to manually process a payment for a subscription renewal with a single click. The saved payment method in the Vault 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. Customers can buy subscription products and renew them manually without having a saved payment method in the Vault.
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.

Adding or changing a subscription payment method

Subscriptions from different payment gateways using automatic recurring payments can be updated to use PayPal Payments as a payment method instead.

Note:

A saved payment method is required to successfully switch existing subscriptions to PayPal Payments. A separate payment, e.g. for a pending renewal order, is required to save the payment method in the Vault.
Automatic renewal payments will not succeed when the subscription payment method is changed to PayPal Payments without a saved payment method in the Vault.

Customer Payment Method Changes: The payment gateway is presented as an option when a customer changes the recurring payment method used for a subscription. This allows the customer to update the payment method used for future recurring payments when a previous payment failed or when it was set to “Manual Renewal”.

Store Manager Payment Method Changes: The payment gateway is presented to the store manager as an option when changing the recurring payment method used for a subscription on the Edit Subscription screen.

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). Subscriptions can be canceled without impacting the saved payment method in the Vault.

The subscription migration layer in PayPal Payments allows automatic renewals of existing PayPal Checkout subscriptions. When a buyer with a pre-existing subscription makes a manual payment, the PayPal account is automatically saved in the Vault. New subscriptions use the payment method saved in the Vault by PayPal Payments, while the migrated subscription renews using the old billing agreement ID (which does not make a difference for the buyer).

Using the same PayPal merchant account on multiple sites for subscriptions is not recommended. Suppose the buyer already has an ongoing subscription with a saved payment method on site A. In that case, the existing billing agreement must be canceled before the same PayPal account could be saved in the Vault on site B.

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.

The customer can also cancel the billing agreement from their PayPal account: What is an automatic payment and how do I cancel or update one?
Once the billing agreement has been canceled, PayPal Payments will automatically attempt to save the payment method in the Vault with the next purchase.

Free trials & synchronized payment dates

Requirements to save a payment method without a payment

Subscription products with no sign-up costs can only be purchased when the merchant account has Reference Transactions enabled. Without Reference Transactions enabled, buyers attempting to save a payment method for a free trial subscription product may receive an error: UNKNOWN_BUSINESS_ERROR

PayPal Payments includes support for subscriptions with a free trial period or prorated & synchronized payment dates.
To purchase a subscription product with no sign-up costs, the buyer must save a payment method in the Vault. While the customer has a free subscription product in the Cart and the Checkout total is zero, the PayPal button on the Checkout page redirects the customer to the PayPal website, where the PayPal account can be authorized for future transactions.

To save the payment method in the Vault without an initial purchase, PayPal Payments authorizes and then voids a $1 payment.
The subscription cannot be purchased if the buyer has no funds available or no payment method connected to authorize this payment with the PayPal account.

After the $1 payment was authorized and voided, the PayPal account will be 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.

Compatibility with third-party subscriptions plugins/addons

PayPal Payments officially supports Simple Subscription and Variable Subscription product types from the official WooCommerce Subscriptions plugin.

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

Pay upon Invoice – Rechnungskauf

↑ Back to top

What is Pay upon Invoice, and who is it for?

Pay upon Invoice is an invoice payment method in Germany. It’s a local buy now, pay later payment method that allows the buyer to place an order, receive the goods, try them, verify they are in good order, and then pay the invoice within 30 days. No PayPal account is needed for the buyer to use Pay upon Invoice.

PayPal has partnered with Ratepay to provide this service. This payment method is also called Rechnungskauf mit Ratepay in German.

Requirements to use Pay upon Invoice

  • The Pay upon Invoice payment method is available only in Germany to eligible merchants.
  • You must sell goods in the B2C model only.
  • You must ship orders within seven days after the transaction.
  • You must be approved to accept transactions using this payment method. PayPal will ask you to enter a valid VAT ID Number as per EU regulations. Without a valid VAT ID for your business, PayPal is required to collect additional VAT as applicable on PayPal fees.
    Request approval to enable Pay upon Invoice by disconnecting and reconnecting your account from the PayPal Payments plugin settings with Onboard with Pay upon Invoice selected.
    Alternatively, PayPal provides signup links for Sandbox and Live accounts.
  • Pay upon Invoice does not allow digital or virtual goods, including but not limited to any form of vouchers (gift vouchers, gift cards, and cash codes), and any transactions outside of PayPal’s Acceptable Use Policy.

Onboarding

01
Pay upon Invoice onboarding Checkbox
  • To see this checkbox, the WooCommerce store location must be set to Germany and the currency to Euro in the General WooCommerce settings tab.
  • Disconnect (if you are already onboarded) and onboard using a German PayPal business account while Onboard with Pay upon Invoice is selected.
  • Enable Pay upon Invoice payment gateway.

Pay upon Invoice onboarding video

Onboard with Pay upon Invoice to activate it for the PayPal account

Taxes

  • In the WooCommerce General settings, Tax calculation should be enabled and have at least one tax rate configured for Germany.
  • If no tax rate is configured or applied to the product, the integration attempts to send 0% tax for Pay upon Invoice payments.

Product requirements

  • Products used for Pay upon Invoice payments should have a tax class assigned, otherwise, they are automatically handled with 0% tax.
  • Paying for digital or virtual goods, including, but not limited to any form of vouchers, such as gift vouchers, gift cards, and cash codes, and any transactions outside of PayPal’s Acceptable Use Policy is not allowed with Pay upon Invoice.
  • The Pay upon Invoice gateway will be hidden on the Checkout page when the cart contains invalid product types such as virtual or downloadable products.

Checkout flow

  • Buyers are automatically requested to provide a birth date to use the Pay upon Invoice payment method.
  • The birth date can be entered numerically or with a popup calendar generated by the browser.
03
Pay upon Invoice Checkout with mandatory Birth date field
  • Add (non-virtual & non-downloadable) product(s) to the Cart and navigate to the Checkout page.
  • PayPal requires a nameemailphone number, and billing address for Pay upon Invoice payments.
  • Ensure the checkout total is between 5€ and 2500€.
  • Ensure billing address information is from Germany.
  • Ensure filling the Birth date form field.
  • Click the “Place order” button.

Email Notification

  • After the buyer has placed the order, a webhook with payment instructions will be received from PayPal. This can take a minute or two and the order will remain in the status On-hold in the meantime.
  • If this webhook (PAYMENT.CAPTURE.COMPLETED) does not arrive within five minutes, the WooCommerce order will be set to a Failed status and the buyer receives a failed order notification.
  • Once the webhook is received, the WooCommerce order moves to the status Processing and a notification email is sent to the customer which automatically includes RatePay payment instructions.
04
Example email with Pay upon Invoice payment instructions
  • The same payment instructions will be stored in the WooCommerce order and are accessible to the store owner.
    Resending the processing notification mail automatically resends the instructions again.

Shipment tracking

↑ Back to top

PayPal Payments integrates the PayPal shipment tracking feature, enabling you to update tracking information on PayPal. This feature allows you to add tracking numbers and other relevant information to your PayPal orders. The information can be added with or without a tracking number using the Tracking Information metabox.

Tracking Information metabox

The tracking integration in PayPal Payments comes with a list of supported carriers and countries. However, the carriers or statuses can be customized to fit specific needs. The customization process is explained in detail in the developer documentation. Additionally, if you need to programmatically modify the tracking data, you can find the relevant information here.


Enabling the Pay upon Invoice payment gateway also automatically activates tracking.
Additionally, the tracking integration interfaces with certain third-party plugins such as Germanized to automatically send your provided tracking data to PayPal without having to manually add it via the Tracking Information metabox.

How to enable tracking for your account

Before you can add tracking information to orders, the feature must be enabled for your PayPal account.
The easiest way to enable tracking is to disconnect your PayPal account from the integration and reconnect it using the onboarding wizard.
Alternatively, get in touch with the PayPal Merchant Support and request Tracking to be enabled for your account.

FraudNet

↑ Back to top

FraudNet is a PayPal-developed, JavaScript library embedded into your web page to collect browser-based customer data to help reduce fraud. Upon checkout, data elements are sent to PayPal Risk Services for fraud and risk assessment. FraudNet is for desktop browsers only.

Data collected by FraudNet is used for risk analysis and authentication. PayPal does not share FraudNet data with third parties for their own independent benefit.

When enabled, the FraudNet library is automatically loaded on all pages with enabled PayPal buttons. FraudNet is automatically enabled when Pay upon Invoice is active.

Pay Later

↑ Back to top

Help boost sales and average order values with PayPal Pay Later.

Pay Later is built into PayPal Payments at no additional cost to you and gives your customers flexible payment options, including short-term interest-free payments and longer term monthly installments with no late fees. Your customers can get what they need now and pay later, while you get paid in full – up front. Pay Later availability and terms vary by country. See details below.

What do I need to do to enable PayPal Pay Later?

When you install the WooCommerce PayPal Payments extension and connect to a PayPal account, Pay Later messaging is enabled by default. 

Once you have installed WooCommerce PayPal Payments, PayPal Pay Later is available in the following regions:

🇺🇸 – Pay in 4 & Pay Monthly; for full details, check the Pay Later details for the US

🇦🇺 – Pay in 4; for full details, check the Pay Later details for Australia

🇩🇪 – PayPal Ratenzahlung & Pay in 30; for full details, check the Pay Later details for Germany

🇪🇸 – Pay in 3 instalments; for full details, check the Pay Later details for Spain

🇫🇷 – Pay in 4X; for full details, check the Pay Later details for France

🇮🇹 – Pay in 3 instalments; for full details, check the Pay Later details for Italy

🇬🇧 – Pay in 3 & PayPal Credit; for full details, check the Pay Later details for the UK

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

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

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.

Customize Pay later messaging

The Pay later messaging can be customized with several different styles per Pay Later messaging configuration.

How to Setup Pay Later Messaging in WooCommerce

More details can be found in the PayPal documentation: Pay Later messaging

How to disable Pay Later features?

The Pay Later messaging can be individually enabled or disabled for the single product, Cart, and Checkout page.
The Pay Later button is loaded independently of the messaging and can be hidden with the Hide Funding Source(s) setting (which also disables the Pay Later messaging).

All Pay Later features are automatically disabled when the Vaulting feature is active.

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 account.

Venmo checkout flow

When eligible, your buyers can use Venmo on the same pages they can use PayPal, including your product page, Cart page, and Checkout page. 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, are supported by PayPal business and 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?

The Venmo button is automatically displayed for eligible customers by default but can be hidden in different ways:

Alternative Payment Methods

↑ Back to top

Alternative Payment Methods (APMs) are supported by PayPal business and personal seller accounts.
These payment methods appear automatically for eligible buyers, primarily on the Checkout page. The funds will be received by your connected PayPal merchant account without requiring additional configuration.

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 the latest version, 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 is available in the PayPal documentation – APM Availability.

How to disable Alternative Payment Methods?

Alternative Payment Methods are displayed by default but can be hidden in different ways:

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 remaining 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

Connecting a personal PayPal account

↑ Back to top

Personal PayPal accounts can be connected using the onboarding wizard with the Standard Card Processing option. Onboarding with Advanced Card Processing will automatically prompt a business signup form as the Advanced Card Processing requires a business account.

Does PayPal Payments support Subscriptions?

↑ Back to top

Yes, PayPal Payments supports automatic recurring payments 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 via Advanced Card Processing do not require Reference Transactions.

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

PayPal Payments also comes with 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 or by WooCommerce if Reference Transactions were used.

Does PayPal Payments support WooCommerce Blocks?

↑ Back to top

PayPal Payments does not yet support the new Cart & Checkout Blocks. This means the PayPal smart buttons or Pay Later messaging will not display on the Block Cart page, and no payment gateway is loaded on the Block Checkout page.

For the time being, PayPal Payments can only be used with the regular WooCommerce shortcode cart &checkout pages.

Support for the new Block Cart & Checkout in development for early 2023. Early access to a Block feature preview can be requested by reaching out to the support.

PayPal Payments Smart Buttons are not displaying on my Single Product/Cart/Checkout page

↑ Back to top

The regular “Place order” button on the Checkout page is hidden and replaced by a spinner while the PayPal Smart Buttons are loading. It may take a few seconds until the buttons are loaded on the first page load after connecting a new PayPal account or saving the plugin settings.

On pages built with page builders like the Divi Theme Builder or Elementor Pro, the PayPal smart buttons may not load in the correct position or at all. In that case, a filter can help to render the buttons in the desired position. This example filter renders the buttons below the “Add to cart” button on the single product page:

add_filter('woocommerce_paypal_payments_single_product_renderer_hook', function() {
    return 'woocommerce_after_add_to_cart_form';
});

See Change button placement via render hooks for a complete list with all available render hooks.

Caching or JavaScript minification can impact PayPal Payments and should be disabled on pages where the PayPal scripts are loaded. Otherwise, eventual site optimizations should exclude scripts from the PayPal Payments integration. When using minification features from third-party plugins, make sure to exclude/whitelist at least the JavaScript in this directory:

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

These additional directories could be whitelisted as well if any issues persist while using site optimizations:

/woocommerce-paypal-payments/modules/ppcp-vaulting/assets/js/myaccount-payments.js
/woocommerce-paypal-payments/modules/ppcp-wc-gateway/assets/js/oxxo.js
/woocommerce-paypal-payments/modules/ppcp-wc-gateway/assets/js/pay-upon-invoice.js
/woocommerce-paypal-payments/modules/ppcp-wc-gateway/assets/js/gateway-settings.js

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

Why are PayPal scripts loading on every page of my site (front end)?

↑ Back to top

PayPal Payments loads the PayPal scripts only on pages with enabled smart buttons or Pay Later messaging.
When the Mini Cart button is enabled, the scripts will be loaded on all non-Cart, and non-Checkout pages of the site as the Mini Cart is usually a global feature.
Disabling the Mini Cart button prevents the scripts from being loaded on the above-mentioned pages.

When performance matters

Unload Event Listener warnings on sites like GTmetrix may be caused by the PayPal scripts loading on your main page, e.g. due to the Mini Cart button being enabled.

Which currencies does PayPal support?

↑ Back to top

The PayPal REST API supports merchants in several countries and 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, for example, India.
The full currency coverage through the PayPal REST API is listed here: PayPal documentation: Currency codes.

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

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

Translating PayPal Payments

↑ Back to top

PayPal Payments automatically displays the PayPal smart buttons and the Pay Later messaging in a language relevant to the buyer.
The language is determined by PayPal and cannot be controlled through the integration.
The displayed language is primarily determined by PayPal cookies on the device or the browser/system language configuration.
A buyer with a browser configured with “German (Germany)” will see German labels, while a buyer with a browser configured with “French (France)” will see French button labels without you having to set anything up in the integration.

The plugin translation files can translate other strings from the settings or certain frontend fields (Advanced Card Payments hosted fields).
The wordpress.org community maintains the plugin translations, and translation contributions are welcome.

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.
  • Activating Logging via the plugin settings to collect more information about payments.
  • Temporarily activating the default theme Storefront and disabling all other plugins except for WooCommerce and PayPal Payments may help isolate a potential plugin conflict. The article 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.

Advanced Troubleshooting

↑ Back to top

If you’re facing difficulties, reach out to the support team for assistance or to gain a better understanding of the issue, you may also find these additional suggestions helpful.

Common errors

↑ Back to top

Frequently reported errors and potential ways to resolve them are listed here on GitHub.

Get Help

↑ Back to top

The troubleshooting steps above are aimed at helping you to help yourself. If you did not find a solution to your problem or answer to your question, please get in touch with the support team.

The support team can be reached here on WooCommerce.com. PayPal Payments must be added to your WooCommerce account before it can be selected from My Account > Support > Help with my purchased products > PayPal Payments

This requires an account on WooCommerce.com.
After submitting your request, the support team will get back to you as soon as possible.

Help can also be requested in the WordPress.org community support forums here. The community forums are frequently checked by the support team. In some cases, we may ask you to create a support request with more details about your request.

Feedback

↑ Back to top

Feedback about your experience with PayPal Payments is welcome.
What do you like or dislike about PayPal Payments, or do you have suggestions on how it could be improved?
Feedback can be shared by reaching out to the support team or by leaving a review on the plugin pages here:

New features can be requested here if you want additional functionality in PayPal Payments.
Popular feature requests may be integrated with future PayPal Payments versions.

Bugs can be reported in the PayPal Payments GitHub repository.
If you are unsure whether or not you found a new bug or encountered a different kind of problem, please contact the support team instead.

↑ Back to top

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 and secure online payment