VibeFox PayFast for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

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

PHP: 8.0 or later.

Currency: South African rand (ZAR), set in WooCommerce > Settings > General. PayFast settles in rand only. 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 plugin. For tests you need the credentials of the PayFast sandbox.

Reachable site: the payment notification URL must be reachable from the internet, without maintenance mode, basic auth or a firewall block.

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_payfast_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Set the store currency to South African rand in WooCommerce > Settings > General.

4. Open the settings: WooCommerce > Settings > Payments > PayFast > 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 Merchant ID, Merchant Key and passphrase. For testing, keep Test mode on and enter your sandbox credentials.

7. Turn on Enable/Disable and save. Make a test payment, then turn test mode off to take real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PayFast. Above the fields the page warns you when the credentials of the current mode are empty (PayFast is then hidden at checkout), when the store currency is not ZAR, when live mode uses the public sandbox Merchant ID 10000100, when no passphrase is set, and shows Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. while test mode is on. In the list of payment methods, PayFast is marked as needing setup until the Merchant ID and Merchant Key of the current mode are entered.

General

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

Title: the payment method name shown to the customer at checkout. Default: PayFast.

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.

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. At checkout the customer sees TEST MODE: payments go to the PayFast sandbox, no real money is charged. 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.

When you update from version 1.0 in test mode, your existing credentials are copied to the sandbox fields. Check the live credentials before you switch test mode off.

Payment notifications (ITN)

PayFast confirms every payment with a server-to-server notification to the URL shown in this section. It looks like https://your-site/wc-api/payfast_pay/. The address is sent with each payment, so nothing has to be configured in PayFast, but it must be reachable from the internet.

Source check: Accept live notifications only from PayFast servers. The addresses come from PayFast's DNS records. Disable it only if your site 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: Log payment steps writes the steps to WooCommerce > Status > Logs, source wcp_payfast_pay. Errors are always logged. No passphrases or customer details are written. Default: off.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default PayFast) and places the order. The customer goes to the Pay for order page of the order, which shows Thank you for your order. You are being redirected to PayFast to complete the payment. and sends the signed payment form to PayFast automatically. If the browser does not continue by itself, the customer clicks Pay with PayFast; Cancel order cancels the order. The form carries the order total in ZAR, Order # with the order number, the customer's name and e-mail, and the order key. It is built again each time the page is opened, so the customer can reopen it after coming back from PayFast.

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 store. The order is marked paid only when the notification passes all checks:

The customer's return to the order received page does not change the order. While the notification has not arrived, the page 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 the customer cancels on the PayFast page, the order is cancelled the standard WooCommerce way. If the customer leaves without paying, the order stays unpaid and can be paid again from the Pay for order page.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is hidden when the credentials of the current mode are missing, when the store or order currency is not ZAR, or when the total is below R5.00. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments in ZAR only. It has no refunds from WooCommerce, no subscriptions, no saved (tokenised) cards, no pre-orders and no split payments.

Orders

Order statuses

Pending payment: the customer was sent to PayFast and the payment notification has not arrived yet.

Processing: PayFast confirmed the payment. This is the standard WooCommerce status after payment; orders with only virtual downloadable products become Completed. The order note shows the PayFast payment ID, which is also the transaction ID of the order. A sandbox payment gets the note that no real money was charged. The PayFast fee and net amount are stored on the order.

On hold: PayFast reported the payment as pending; or the paid amount differs from the order total, or the order is not in ZAR; or a payment arrived for an order that had already been cancelled. The order note explains it. Check the order and your PayFast dashboard, then ship it or refund the payment in PayFast.

Failed: PayFast reported the payment as failed while the order was unpaid. The customer can pay again.

Cancelled: the customer cancelled on the PayFast page, or the order was cancelled by you or by the WooCommerce stock hold timeout.

A repeated notification for the same payment changes nothing. 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. A sandbox payment received while the gateway is in live mode adds a note and does not mark the order paid.

Refunds

Refunds from WooCommerce are not supported. Refund the payment in your PayFast dashboard, then create a manual refund in 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 > PayFast. 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, 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. 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: payments already started are still confirmed.

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

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 store currency is ZAR and the order total is at least R5.00. The settings page shows a warning when something is missing.

The payment went through, but the order stays Pending payment: PayFast could not deliver the payment notification, or it was rejected. Enable Debug log and check WooCommerce > Status > Logs, source wcp_payfast_pay. Typical reasons: the site is not reachable from the internet (maintenance mode, basic auth, firewall), a different passphrase in PayFast and in the plugin, 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 plugin is not the one set in PayFast for this mode.

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 site 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 order. Nothing is changed.

The notification answers Confirmation unavailable or Busy: PayFast could not be reached for the server confirmation, or another notification for the same order was being processed at the same moment. PayFast retries the notification.

The notification answers Not configured: the credentials of the mode the order was paid in are missing.

The customer sees PayFast accepts payments from R5.00: the order total is below the PayFast minimum.

Order is On hold: PayFast confirmed a payment that does not match the order (different amount, or a currency other than ZAR), or the payment arrived for an order that was already cancelled. Check the order notes and your PayFast dashboard.

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.

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, the other options of the plugin, the cached PayFast addresses and its logs are removed only if Delete the gateway settings and logs when the plugin is deleted was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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