VibeFox PayFast for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Currency: South African rand (ZAR). PayFast settles in rand only, so the cart must be in ZAR. Add the currency in International > Localization > Currencies if your shop does not have it yet. The minimum order total is R5.00.
PayFast account: the Merchant ID and Merchant Key of your PayFast account, from Settings > Developer Settings in the PayFast dashboard. A passphrase is strongly recommended; if one is set in PayFast, the same passphrase must be entered in the module. For tests you need the credentials of the PayFast sandbox.
Reachable shop: the payment notification URL must be reachable from the internet, without basic auth or a firewall block.
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 PayFast Pay 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. Enter the Merchant ID, Merchant Key and passphrase. For testing, keep Test mode on and enter your sandbox credentials.
5. Turn on Enable/Disable and click Save. Make a test payment, then turn Test mode off to take real payments.
On install the module creates two order statuses, Awaiting PayFast payment and PayFast payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; make sure the module stays allowed for the rand.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the credentials of the current mode are empty (PayFast is then hidden at checkout), when the default shop currency is not ZAR, when live mode uses the public sandbox Merchant ID 10000100 and when no passphrase is set. While test mode is on and the module is enabled, it shows Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. An empty Title is refused with Enter a title for the payment method.
PayFast
Enable/Disable: Enable PayFast turns the payment method on or off. Default: off.
Title: the payment method name shown to the customer at checkout. It is also the payment method name stored in the order. Default: PayFast. Required.
Description: the text shown under the payment method at checkout. Default: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
PayFast account (live)
Find your Merchant ID and Merchant Key in the PayFast dashboard under Settings > Developer Settings. If you set a passphrase there, enter exactly the same passphrase here.
Merchant ID: your live PayFast Merchant ID.
Merchant Key: your live PayFast Merchant Key. It is sent to PayFast with every payment form, so it is a normal text field.
Passphrase: the salt passphrase from PayFast, Settings > Developer Settings. Strongly recommended: it signs payments and notifications.
Sandbox (test mode)
In test mode payments go to the PayFast sandbox and no real money is charged. Sandbox credentials are shown after you log in to the PayFast sandbox (the public test merchant is 10000100 / 46f0cd694581a).
Test mode: Use the PayFast sandbox and the sandbox credentials below. While it is on, the customer sees TEST MODE: payments go to the PayFast sandbox, no real money is charged. under the payment method. Default: on.
Sandbox Merchant ID: the Merchant ID of your sandbox account.
Sandbox Merchant Key: the Merchant Key of your sandbox account.
Sandbox Passphrase: only if a passphrase is set in your sandbox account.
Saved passphrases 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 passphrases: tick Passphrase or Sandbox Passphrase and click Save to remove it. An empty field keeps the saved value.
Payment notifications (ITN)
Notification URL: PayFast confirms every payment with a server-to-server notification to the URL shown here. With friendly URLs it looks like https://your-shop/module/wcp_payfast_pay/itn, possibly with the language code of the default language. The address is sent with each payment, so nothing has to be configured in PayFast, but it must be reachable from the internet. Orders are created only by these verified notifications; the customer returning to the shop does not create or pay an order.
Source check: accept live notifications only from PayFast servers. The addresses come from PayFast's DNS records (cached for 6 hours) and PayFast's documented address ranges. Disable it only if your shop is behind a proxy or CDN that hides the visitor address. Signature and server confirmation are always checked. Sandbox notifications are not checked by address. Default: on.
Advanced
Debug log: logs payment steps to logs/payfast_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when the switch is off. No passphrases or customer details are written. Default: off.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Uninstall: Delete the gateway settings when the module is uninstalled (settings, cached PayFast addresses and the log). PayFast payment records, orders and order statuses are always kept. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default PayFast) and confirms. A page with Thank you for your order. You are being redirected to PayFast to complete the payment. sends the signed payment form to PayFast automatically. If the browser does not continue by itself, the customer clicks Pay with PayFast; Cancel goes back to the checkout. The form carries the cart total in ZAR, Cart # with the cart number, the customer's name and e-mail, the payment reference (cart number and attempt) and a random token of the attempt. No order exists yet at this point. Each new attempt gets a new reference and token.
On the PayFast page the customer pays by card, Instant EFT or another method of your PayFast account. PayFast then sends the payment notification (ITN) to your shop. The order is marked paid only after PayFast confirms it with a notification that passes all checks:
Notifications for one cart are processed one at a time. If another notification of the same cart is being processed, PayFast gets an error answer and sends the notification again. The notification URL works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.
When the customer comes back and the order exists, the standard order confirmation page is shown. If PayFast reported the payment as pending, it says PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. If the order is on hold, it says Your payment is being reviewed. We will contact you if anything else is needed. If a pending payment later failed, it says Your PayFast payment was not completed. Please contact us about this order. If the notification has not arrived yet, a Payment confirmation page says that PayFast is confirming the payment and the order will be created as soon as PayFast confirms it, with the buttons Check again and Back to checkout.
If the customer cancels on the PayFast page, the customer is back at checkout with The PayFast payment was cancelled. You can try again or choose another payment method. If PayFast reported the payment as failed, the message is The payment was not completed. You can try again or choose another payment method. The cart is kept and can be paid again.
The payment method is hidden when the credentials of the current mode are missing, when the cart currency is not ZAR or not allowed for the module, or when the total is below R5.00. If the customer reaches the payment anyway, a short message explains it, for example PayFast accepts payments from R5.00. Please choose another payment method.
The module takes one-time payments in ZAR only. It has no refunds from the order page, no subscriptions, no saved (tokenised) cards and no split payments.
Orders
Order statuses
No order yet: the customer was sent to PayFast and the payment notification has not arrived yet, or PayFast reported the payment as failed. Only the cart exists.
Payment accepted: PayFast confirmed the payment. The payment is recorded with the PayFast payment ID as the transaction ID, and a note shows the payment ID. A sandbox payment gets the note that no real money was charged.
Awaiting PayFast payment: PayFast reported the payment as pending. The order moves to Payment accepted when PayFast completes it.
Payment error: a pending payment failed. If PayFast completes it later, the order becomes Payment accepted.
PayFast payment on hold: the paid amount differs from the cart total, or the cart is not in ZAR; a payment arrived for an order that had been cancelled or whose payment method is no longer PayFast; or a sandbox payment arrived while the gateway is in live mode. The amount PayFast received is recorded on the order (not for a sandbox payment), and the note explains it. Check the order and your PayFast dashboard, then set the order to Payment accepted or cancel it and refund the payment in PayFast.
A repeated notification for the same payment changes nothing. Late failed or pending notifications never change a paid order. If another completed payment arrives for an order that is already paid, a note asks you to refund the duplicate in PayFast. A payment for a refunded order only adds a note.
PayFast payment block
The order page shows a PayFast payment block with the payment reference (m_payment_id), the PayFast payment ID, the environment (live or sandbox), the status, the amounts gross, fee and net in ZAR and the notes of the module. For an order on hold it shows a reminder to review the payment.
Refunds
Refunds from the order page are not supported. Refund the payment in your PayFast dashboard, then update the order in PrestaShop manually.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayFast Pay Gateway is the first block on Modules > Module Manager > VibeFox PayFast Pay 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-payfast 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, PayFast 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. 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: payments already started are still confirmed.
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
PayFast does not appear at checkout: check that the license is active, Enable/Disable is on, the Merchant ID and Merchant Key of the current mode are filled in, the cart is in ZAR and the order total is at least R5.00. The settings page shows a warning when something is missing. In Payment > Preferences check that the module is allowed for the rand, the customer's country and the customer's group.
The payment went through, but no order was created: PayFast could not deliver the payment notification, or it was rejected. Look at the Log field on the module page; errors and rejected notifications are always logged, and Debug log adds every step. Typical reasons: the shop is not reachable from the internet (basic auth, firewall), a different passphrase in PayFast and in the module, or, in live mode behind a proxy or CDN, the source check. In that case switch off Source check.
The notification answers Invalid signature: the passphrase in the module is not the one set in PayFast for the mode the payment was made in.
The notification answers Invalid source: the notification did not come from a PayFast address, or a proxy or CDN hides the real address. Switch off Source check if your shop is behind a proxy or CDN.
The notification answers Merchant mismatch or Order mismatch: the payment was made to another PayFast account or does not belong to this payment attempt. Nothing is changed.
The notification answers Order not found: the payment reference is unknown to this shop. Nothing is changed.
The notification answers Confirmation unavailable, Busy or Temporary error: PayFast could not be reached for the server confirmation, another notification for the same cart was being processed at the same moment, or the order could not be created (for example, the module is disabled). PayFast retries the notification. The log shows the reason.
The notification answers Not configured: the credentials of the mode the payment was started in are missing. Enter them again, for example the sandbox credentials for a test payment.
The customer sees PayFast accepts payments in South African rand (ZAR) only: the cart is in another currency. Let the customer pay in rand or choose another payment method.
Order is PayFast payment on hold: read the notes in the PayFast payment block (see Order statuses) and your PayFast dashboard, then accept the order or refund the payment.
A sandbox payment did not pay the order: the gateway is in live mode. Sandbox payments never pay an order in live mode; a note on the order says so.
For developers: the hook actionPayfastPPaymentData can change the payment form fields before they are signed. The merchant credentials, URLs, payment reference, amount and token cannot be changed by it.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox PayFast Pay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete the gateway settings when the module is uninstalled is on, the gateway settings, the cached PayFast addresses and the log are removed. If it is off, all settings are kept for a later re-install. The PayFast payment records, the orders and the order statuses Awaiting PayFast payment and PayFast payment on hold are always kept. Existing orders keep their payment notes and transaction IDs.
PayFast is a trademark of its respective owner. This module is not affiliated with or endorsed by PayFast.