VibeFox PayFast for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: South African rand (ZAR). PayFast settles in rand only, so the order must be in ZAR. Add the currency in System > Localisation > Currencies if your store 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 extension. For tests you need the credentials of the PayFast sandbox.

Reachable store: 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_payfast_pay-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_payfast_pay.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_payfast_pay-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox PayFast Pay Gateway and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_payfast_pay.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox PayFast Pay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the PayFast credentials and test the payment as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Notification URL); it is sent to PayFast with every payment as well.

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the credentials of the current mode are empty (PayFast is then hidden at checkout), when the default store 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 it shows Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.

When you save, Title must not be empty (up to 128 characters), Sort Order must be a whole number (negative numbers are allowed), Total a number, 0 or greater, and the selected geo zone and order statuses must exist; otherwise nothing is saved and the page names the field. If you enable the payment method without the credentials of the current mode, the settings are saved with a warning.

PayFast

Enable/Disable: Enable PayFast 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: PayFast. Required.

Description: the text shown to the customer on the Confirm Order step, above the confirm button. Default: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Sort Order: the position of PayFast among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer PayFast only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones. On OpenCart 4, when the store asks for no payment address, the shipping address is used.

Total: the checkout total, in the default currency of the store, that an order must reach before PayFast is offered. Leave it empty to offer PayFast for any total. PayFast itself always needs at least R5.00.

PayFast account (live)

Find your Merchant ID and Merchant Key in the PayFast dashboard under Settings > Developer Settings (the section links there). 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. at the Confirm Order step. 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. To remove a saved passphrase, tick Clear the saved passphrase on save under the field and click Save.

Payment notifications (ITN)

Notification URL: PayFast confirms every payment with a server-to-server notification to the URL shown here. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn. It is built from the storefront address of your OpenCart installation. The address is sent with each payment, so nothing has to be configured in PayFast, but it must be reachable from the internet. Orders get their status only from these verified notifications; the customer returning to the store does not change the order.

Source check: accept live notifications only from PayFast servers. The addresses come from PayFast's DNS records (cached for 6 hours; the cache is reset when you save the settings) and PayFast's documented address ranges. Disable it only if your store 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.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only from a verified PayFast notification. A cancelled, failed or abandoned payment leaves it without a status, and the customer can pay again. Each field below lists your OpenCart order statuses.

Order Status (paid): the status after PayFast confirmed the payment and the amount and currency match. Default: Processing.

Awaiting PayFast payment: PayFast reported the payment as pending (for example Instant EFT). It changes to the paid status when PayFast completes it. Default: Pending.

PayFast payment on hold: a payment that needs your review (see Order statuses). Such an order is not marked as paid; a note explains why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Payment failed: a pending payment failed. If PayFast completes it later, the order changes to the paid status. Default: Failed.

Advanced

Debug log: logs payment steps to payfast_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to payfast_p_debug.old.log.php. Errors and warnings are always logged, even when the switch is off. No passphrases, keys 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 extension is uninstalled (settings, cached PayFast addresses and the log). PayFast payment records and orders are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Passphrases are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved passphrases are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default PayFast). At the Confirm Order step the customer sees your description and the note Thank you for your order. You will be redirected to PayFast to complete the payment. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension sends the signed payment form to PayFast. The form carries the order total in ZAR, Order # with the order number, the customer's name and e-mail, the payment reference (order number and attempt) and a random token of the attempt. 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 store. The order is marked paid only after PayFast confirms it with a notification that passes all checks:

The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. 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 also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the notification and the customer's return from PayFast through.

When the customer comes back and the order has a status, the OpenCart order success page is shown. If PayFast reported the payment as pending, it also 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. (on OpenCart 4 the customer is sent back to the checkout instead, see below). If the notification has not arrived yet, a Payment confirmation page says that PayFast is confirming the payment, 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. On OpenCart 4 these messages are shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, so after a cancelled or failed payment the customer pays the same order with a new attempt. If another order of the same cart has already been handled by PayFast (for example in a second browser tab), the customer is taken to the success page instead of paying again.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example its pending payment failed or you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled or its payment failed. Please confirm the order again., and the next Confirm Order pays a new order. If that order already has a status and the cart now has other products or quantities, the message is Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.

The payment method is hidden when the credentials of the current mode are missing, when the checkout currency is not ZAR, or when the total is below R5.00. If the customer reaches the payment anyway, a short message above the button explains it, for example PayFast accepts payments from R5.00. Please choose another payment method.

The extension 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 status (missing order): the customer was sent to PayFast and the payment notification has not arrived yet, or PayFast reported the payment as failed. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

On OpenCart 4 an unpaid order of the checkout can get the status Voided, which OpenCart 4 sets when the customer comes back to the Confirm Order step. The extension treats such an order as an order without status, and a later payment still confirms it.

Order Status (paid) (default Processing): PayFast confirmed the payment. A note shows the PayFast payment ID. A sandbox payment gets the note that no real money was charged.

Awaiting PayFast payment (default Pending): PayFast reported the payment as pending. The order moves to the paid status when PayFast completes it, or to Payment failed when the payment fails; the customer is notified of these changes by e-mail.

Payment failed (default Failed): a pending payment failed. If PayFast completes it later, the order changes to the paid status.

PayFast payment on hold (default Pending): the paid amount differs from the order total, or the order is not in ZAR; a payment arrived for an order whose status you had changed meanwhile (for example cancelled) or whose payment method is no longer PayFast; or a sandbox payment arrived while the gateway is in live mode. The note explains it. Check the order and your PayFast dashboard, then set the order to the paid status 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, or for a second order of an already paid cart, a note on the paid order asks you to refund the duplicate in PayFast.

Notes are entries in the order History that the customer does not see.

VibeFox PayFast Pay Gateway tab

In Sales > Orders open an order paid with PayFast. At the bottom of the order page, next to History and Additional, the VibeFox PayFast Pay Gateway tab shows the Payment reference (m_payment_id), the PayFast payment ID, the Environment (live or sandbox), the requested amount, the status, the amounts gross, fee and net in ZAR and the PayFast notes. For an order on hold it shows a reminder to review the payment. The tab is shown to users who have access to the extension.

Refunds

Refunds from the order page are not supported. Refund the payment in your PayFast dashboard, then update the order in OpenCart manually.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayFast Pay Gateway is the first block on Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-payfast and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 checkout currency is ZAR and the order total is at least R5.00. The settings page shows a warning when something is missing. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: PayFast could not deliver the payment notification, or it was rejected. Look at the Log field on the extension page; errors and rejected notifications are always logged, and Debug log adds every step. Typical reasons: the store is not reachable from the internet (basic auth, firewall), a different passphrase in PayFast and in the extension, 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 extension 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 store 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 store. 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 status could not be set. 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 order is in another currency. Let the customer pay in rand or choose another payment method.

The customer sees This payment method is not available. Please reload the checkout page. The checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Order is in the on-hold status: read the notes in the VibeFox PayFast Pay Gateway tab (see Order statuses) and your PayFast dashboard, then set the paid status 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: before the payment form is signed, the extension triggers the OpenCart event payfast_p_payment_data with the form fields and the order. The merchant credentials, URLs, payment reference, amount and token cannot be changed by it.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox PayFast Pay Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notification and the customer's return through in maintenance mode). If Delete the gateway settings when the extension is uninstalled is on, the other gateway settings (title, description, credentials, passphrases, test mode, source check, logging), the cached PayFast addresses and the log are removed. If it is off, they are kept for a later re-install. The PayFast payment records and the orders are always kept. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox PayFast Pay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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