VibeFox PayPal for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

HTTPS: your site should use HTTPS for live payments.

PayPal account: a PayPal Business account with a REST API app in the PayPal Developer Dashboard. You need the Client ID and the Secret of the app. Sandbox and live apps have different credentials. No webhook is needed: the plugin confirms each payment on your server while the customer is at the checkout.

Currency: one of the currencies PayPal supports: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD or USD.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_paypal_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. In the PayPal Developer Dashboard create a REST API app (sandbox and/or live) and copy its Client ID and Secret.

4. Open the settings: WooCommerce > Settings > Payments > PayPal (Smart Buttons) > Manage, or click Settings under the plugin name on the Plugins page.

5. Enter your VibeFox license key in the license block at the top of the page and click Activate.

6. Enter the credentials of the mode you use, choose Capture or Authorize, turn on Enable/Disable and save.

7. Test with a PayPal sandbox buyer account, then untick Sandbox mode and enter the live credentials.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PayPal (Smart Buttons). Above the fields the page warns you when the payment method is enabled but the Client ID or Secret of the selected mode is empty, and when PayPal does not support the store currency. In both cases the payment method is hidden at checkout. In the list of payment methods, PayPal shows a Test mode badge in sandbox mode and is marked as needing setup until the credentials of the selected mode are filled in.

General

Enable/Disable: Enable PayPal Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: PayPal.

Description: the text shown under the payment method at checkout. Default: Pay with your PayPal account or a card via PayPal.

API credentials

Create a REST API app in the PayPal Developer Dashboard and copy its Client ID and Secret. The section has links to the sandbox apps and the live apps. Only the fields of the selected mode are shown.

Sandbox mode: Enable sandbox (test) mode. Payments go to the PayPal sandbox with the sandbox credentials; no real money is moved. Default: on. Untick it to accept live payments.

Sandbox Client ID: the Client ID of your sandbox REST API app.

Sandbox Secret: the Secret of your sandbox REST API app.

Live Client ID: the Client ID of your live REST API app.

Live Secret: the Secret of your live REST API app.

Payment

Payment action: what happens when the customer approves the payment. Default: Capture.

Capture: the customer is charged immediately and the order becomes Processing.

Authorize: the funds are only reserved and the order is put On hold. Capture or void the payment from the order screen with the Order actions menu. PayPal authorizations can be captured within 29 days.

Advanced

Debug log: Log API requests (errors are always logged). Entries are stored in WooCommerce > Status > Logs, source wcp_paypal_gateway. Credentials and buyer data are never logged. Default: off.

Delete data on uninstall: Delete the gateway settings when the plugin is deleted. Order payment data (PayPal IDs in the orders) is always kept. Default: off.

Checkout

When the customer chooses PayPal (by default PayPal), the PayPal button replaces Place order. In sandbox mode the checkout shows Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. A click on the button creates a PayPal order on your server for the cart total (or for the order total on the Pay for order page). The amount is always calculated on the server, never in the browser.

The customer approves the payment in the PayPal window with a PayPal account or another funding source PayPal offers. The checkout then shows PayPal payment approved. Completing your order… and submits the order. Your server reads the PayPal order and checks that it is approved, that it was created in this checkout, that it is not used by another order and that its amount and currency match the order. Only then the payment is captured (or authorized), and the customer lands on the order received page.

If the cart total changed after the approval, nothing is captured. The customer sees The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. If a checkout field is missing, the approval is kept: after fixing it the customer clicks Place order to complete the payment. If PayPal declines the payment, the customer is asked to click the PayPal button and choose another way to pay. If the customer closes the PayPal window, the checkout shows You cancelled the PayPal payment.

If PayPal does not answer during the capture, the customer sees We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. A retry uses the same approval, and if PayPal had completed the earlier attempt, that payment is used and the new approval is not captured.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. The PayPal script is loaded in its own namespace, so it does not clash with another PayPal plugin on the page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no PayPal webhooks, no Pay Later messages, no card fields, Venmo settings, Apple Pay, Google Pay or Fastlane, no saved payment methods or subscriptions and no buttons on product or cart pages. The shipping address entered in the WooCommerce checkout is used, not an address from PayPal.

Orders and refunds

Order statuses

Pending payment: the order was created, but the payment is not captured yet, for example after an unknown answer from PayPal.

Processing: the capture is completed. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the amount, the PayPal order and the capture. The transaction ID is the PayPal capture ID, and on the order screen it links to the payment in your PayPal account (sandbox or live).

On hold: the payment was authorized and waits for capture (payment action Authorize); or the capture is PENDING at PayPal, for example under payment review; or the paid amount or currency differs from the order; or the payment could not be read from the PayPal answer. The order note explains it.

Failed: PayPal declined the capture or the authorization.

Cancelled: the authorization was voided with Void PayPal authorization.

Order actions

Open the order, choose an action in Order actions and click the arrow.

Capture PayPal payment: captures an authorized payment for the order total. A completed capture sets the order to Processing. Shown while the authorization is not captured.

Void PayPal authorization: releases the reserved funds and cancels the order.

Check PayPal payment status: reads a PENDING capture again. COMPLETED sets the order to Processing, DECLINED or FAILED to Failed. A capture completed for another amount or currency keeps the order On hold with a mismatch note.

Refunds

Open the order, click Refund, enter the amount and click Refund via PayPal (the button shows your payment method title). Full and partial refunds are supported. The refund is sent to the PayPal environment the payment was made in (sandbox or live), so that environment's credentials must be set. The reason is passed to PayPal as a note to the buyer. If PayPal does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the PayPal refund ID and status; a PENDING refund is completed by PayPal later.

A payment that is only authorized cannot be refunded: use Void PayPal authorization instead. Refunds, disputes and reversals made in your PayPal account are not synced to WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > PayPal (Smart Buttons). Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, PayPal is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: refunds and the order actions keep working.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

PayPal does not appear at checkout: check that the license is active, Enable/Disable is on, the Client ID and Secret of the selected mode are filled in, the store currency is supported by PayPal and the cart total is above zero. The settings page shows a warning when credentials or the currency are the problem. A browser extension that blocks www.paypal.com also hides the button.

The payment went through, but the order stays Pending payment: the plugin has no webhook, so the payment is confirmed only during the checkout. This happens when PayPal did not answer during the capture. Read the order note, check the payment in your PayPal account and complete the order manually, or let the customer try again: a retry never charges twice.

PayPal is not available right now: the credentials are wrong or belong to the other mode. Copy the Client ID and Secret of the right app again.

Your PayPal approval could not be matched to this checkout: the PayPal order was not created in this checkout session, for example after the session expired. The customer clicks the PayPal button again.

The order is On hold after payment: read the order note. The payment was authorized (capture it with Capture PayPal payment), the capture is PENDING at PayPal (use Check PayPal payment status later), or the paid amount or currency did not match the order.

Capture of an authorization fails: the authorization may be older than 29 days or already voided. The order note shows the PayPal error.

Refund fails: the order has no PayPal capture (only an authorization), or the credentials of the environment the payment was made in are missing. Developers can change the currency list with the filter wc_plg_supported_currencies.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the cached PayPal access tokens are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and PayPal IDs.

PayPal is a trademark of its respective owner. This plugin is not affiliated with or endorsed by PayPal.