VibeFox PayPal for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
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 module 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox PayPal Gateway in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. In the PayPal Developer Dashboard create a REST API app (sandbox and/or live) and copy its Client ID and Secret.
5. Enter the credentials of the mode you use, choose Capture or Authorize, turn on Enable/Disable and click Save.
6. Test with a PayPal sandbox buyer account, then turn off Sandbox mode and enter the live credentials.
On install the module creates three order statuses: PayPal payment authorized, Awaiting PayPal payment and PayPal payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox PayPal Gateway > Configure. Each section has its own Save button, which saves the whole page. 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 shop's default currency. In both cases the payment method is hidden at checkout. While sandbox mode is on, the page shows Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. Saving the settings drops the cached PayPal access tokens, so new credentials are used at once.
General
Enable/Disable: Enable PayPal Gateway turns the payment method on or off. Default: off.
Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: PayPal. Required.
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; the credentials of both modes stay saved.
Sandbox mode: payments go to the PayPal sandbox with the sandbox credentials; no real money is moved. Default: on. Turn it off to accept live payments. Captures, voids and refunds always use the environment the order was paid in. While it is on, customers see Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. under the payment method.
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.
Saved secrets are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Clear saved secrets: tick a secret and click Save to remove it. An empty field keeps the saved value.
Payment
Payment action: what happens when the customer approves the payment. Default: Capture.
Advanced
Debug log: logs API requests to logs/wc_plg_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this switch is off. Credentials, tokens and buyer data are never logged. Default: off.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Delete data on uninstall: when on, uninstalling the module removes the gateway settings, the cached tokens and the log. Order payment data (PayPal IDs of the orders, refunds) and the order statuses are always kept. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default PayPal) and the PayPal button appears in place of the payment form. A click on the button creates a PayPal order on your server for the cart total in the cart currency. The amount is always calculated on the server, never in the browser. No order exists yet at this point.
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 places the order. If the terms of service are not accepted yet, the checkout shows PayPal payment approved. Click "Place order" to complete it. If the customer clicks Place order without approving a payment, the message is Please click the PayPal button and approve the payment first.
Your server then reads the PayPal order and checks that it is approved, that it was created for this cart, that it is not used by another cart and that its amount and currency match the cart. Only then the payment is captured (or authorized), the order is created and the customer sees the standard order confirmation 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 PayPal declines the payment, the customer is back at the payment step and is asked to click the PayPal button and choose another way to pay. No order is created. 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. The approval is kept, also after a page reload, and Place order uses it again. If PayPal had completed the earlier attempt, that payment is used and a new approval is not captured. If the payment was taken but the order could not be created, the customer sees Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. The next attempt creates the order from the stored payment without charging again.
The PayPal script is loaded only on the checkout page and in its own namespace, so it does not clash with another PayPal module on the page. The module works with the Classic and Hummingbird themes.
The module has no PayPal webhooks, no Pay Later messages, no card fields, Venmo, Apple Pay, Google Pay or Fastlane, no saved payment methods or subscriptions and no buttons on product or cart pages. The addresses entered in the PrestaShop checkout are used, not an address from PayPal.
Orders and refunds
Order statuses
No order yet: the customer has not approved the payment, or PayPal declined it. Only the cart exists.
Payment accepted: the capture is completed. The order is marked paid only after PayPal confirms it. The payment is recorded with the PayPal capture ID as the transaction ID, and a note shows the amount, the PayPal order and the capture.
PayPal payment authorized: the payment was authorized and waits for capture (payment action Authorize).
Awaiting PayPal payment: the capture is PENDING at PayPal, for example under payment review.
PayPal payment on hold: the paid amount or currency differs from the order, or the payment could not be read from the PayPal answer. The note explains it. When PayPal charged in the order currency, the amount actually paid is recorded as the payment. Check the order and fulfil it or refund the payment.
Canceled: the authorization was voided with Void PayPal authorization.
Payment error: a pending capture was declined or failed.
Refunded: the payment was fully refunded through the module.
If a second payment arrives for a cart that already has an order, the order is not changed. A note asks you to check it in your PayPal account and refund it.
PayPal payment block
The order page shows a PayPal payment block with the PayPal order ID and intent, the capture ID (linked to the payment in your PayPal account, sandbox or live), the authorization ID, the payment status, the amount, the paid and refunded amounts, a Sandbox badge for sandbox payments, the refund history and the PayPal notes of the order. The buttons of the block need the right to edit orders, no access to the Modules pages. The result of each action is shown in the block.
Refunds
In the PayPal payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via PayPal. Confirm the question Refund this amount through PayPal? This cannot be undone. Full and partial refunds are supported. The reason is passed to PayPal as a note to the buyer. Refunds are made in the amount and currency PayPal charged, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent to the PayPal environment the payment was made in (sandbox or live), so that environment's credentials must be set. If PayPal does not accept the refund, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the PayPal refund ID and status; a PENDING refund is completed by PayPal later. A full refund sets the order to Refunded. A partial refund does not change the status.
A payment that is only authorized cannot be refunded: use Void PayPal authorization instead. The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through PayPal. Refunds, disputes and reversals made in your PayPal account are not synced to PrestaShop.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayPal Gateway is the first block on Modules > Module Manager > VibeFox PayPal Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-paypal and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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 shop refuses to create the PayPal order and the customer sees An error occurred during PayPal checkout. Please try again. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: refunds and the actions of the PayPal block keep working.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.
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 cart 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. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. A browser extension that blocks www.paypal.com also hides the button.
The payment went through, but no order was created: the module has no webhook, so the payment is confirmed only during the checkout. This happens when PayPal did not answer during the capture or the order could not be created. Turn on Debug log and look at the Log field, check the payment in your PayPal account, or let the customer try again: a retry never charges twice and creates the order from the stored payment.
PayPal could not be loaded: the PayPal script did not load in the browser, for example because of a blocker or a network problem.
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 for this cart, for example after the session expired. The customer clicks the PayPal button again.
This payment is already being processed: the same cart was submitted twice at the same moment. The customer waits a moment and checks the e-mail before trying again.
The order is on hold after payment: read the notes in the PayPal payment block. 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 (fulfil the order or refund what was paid).
Capture of an authorization fails: the authorization may be older than 29 days or already voided. The block and the notes show the PayPal error.
Refund fails: the order has no PayPal capture (only an authorization), the amount is more than what is left to refund, or the credentials of the environment the payment was made in are missing. The block says which.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox PayPal Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings, the cached PayPal access tokens and the log are removed. If it is off, all settings are kept for a later re-install. The PayPal transactions and refunds and the order statuses PayPal payment authorized, Awaiting PayPal payment and PayPal payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.
PayPal is a trademark of its respective owner. This module is not affiliated with or endorsed by PayPal.