VibeFox PayFast for Adobe Commerce — Guida

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension (used for the server confirmation of each payment with PayFast).

Currency: South African rand (ZAR). PayFast settles in rand only, so the customer must check out in ZAR. Add the rand in Stores > Configuration > General > Currency Setup if your store does not have it yet, and set a currency rate in Stores > Currency Rates if your base currency is not ZAR. 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 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-payfast-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PayfastPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PayfastPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox PayFast Pay Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the Merchant ID, Merchant Key and passphrase. For testing, keep Test mode at Yes and enter your sandbox credentials. Set Enable to Yes and click Save Config. Make a test payment, then set Test mode to No to take real payments.

The module adds the PayFast payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates one table for the PayFast payment attempts.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayFast Pay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete Data on Uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title of 1 to 128 characters.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be zero or greater.).

Below the fields the group shows the notification URL (see Payment notifications). While Enable is Yes, it also warns you when something needs attention, because the Payment Methods page is shared by all payment methods:

General

Enable: shows or hides PayFast at checkout. It is shown only when the Merchant ID and Merchant Key of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name of the order. Default: PayFast. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it 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. Spaces at the start and end of the values are removed.

Merchant ID: your live PayFast Merchant ID.

Merchant Key: your live PayFast Merchant Key. The comment says: Sent in every payment form; this is a public integration key. It is a normal text field.

Passphrase: the passphrase from PayFast, Settings > Developer Settings. Strongly recommended: it signs payments and notifications. Set the same passphrase in PayFast Developer Settings.

Sandbox (test mode)

Test mode: Use the sandbox credentials. Existing notifications always use the attempt environment. In test mode payments go to the PayFast sandbox and no real money is charged. 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: Yes.

Sandbox Merchant ID: the Merchant ID of your PayFast sandbox account.

Sandbox Merchant Key: the Merchant Key of your PayFast sandbox account.

Sandbox Passphrase: Optional sandbox passphrase. Only if a passphrase is set in your sandbox account.

Magento stores both passphrases encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved passphrase, clear the field and click Save Config.

A payment is always checked with the credentials of the mode and merchant account it was started with. Do not replace the old credentials while payments started with them are still open.

Payment notifications (ITN)

Notification URL (ITN): PayFast confirms every payment with a server-to-server notification to this URL. It is the storefront address of the default store view and looks like https://your-store/wcppayfastpay/checkout/itn/. The address is sent to PayFast with each payment form, so nothing has to be configured in PayFast, but it must be reachable from the internet. Payments are confirmed only by verified notifications; the customer returning to the store does not pay an order. Refunds are made in the PayFast dashboard (see Refunds).

Source check: Live ITNs use REMOTE_ADDR only, DNS addresses cached for 6 hours and documented ranges. Disable only behind a trusted proxy. Sandbox is exempt. When Yes, live notifications are accepted only from PayFast servers: the addresses come from PayFast's DNS records and PayFast's documented address ranges. Forwarded address headers of a proxy are not used. Signature, merchant, attempt token and server confirmation are always checked. Default: Yes.

Conditions

Payment from Applicable Countries: All Allowed Countries offers PayFast for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer PayFast only for billing addresses in these countries.

Minimum Order Total: offer PayFast only from this order total, in the base currency of your store. Empty means no minimum. The PayFast minimum of R5.00 always applies.

Maximum Order Total: offer PayFast only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Advanced

Debug log: logs payment steps to var/log/payfast_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings, for example rejected notifications, are always logged, even when it is No. No passphrases, keys, tokens or customer details are written. Default: No.

Log: the row below shows the size and the latest entries of the log. Click Clear log to empty it.

Delete Data on Uninstall: Own settings, source-address cache and log only. Financial history is always preserved. When Yes, uninstalling the module with its data deletes the gateway settings, the cached PayFast addresses and the log (see Uninstall). The license key is always removed. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default PayFast) and sees the description. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. A page Continue to PayFast then sends the signed payment form to PayFast automatically. If the browser does not continue by itself, the customer clicks Pay with PayFast; Cancel cancels the order and goes back to the cart. The form carries the order total in ZAR (with tax, discount and shipping), Order # with the order number, a description "Order # … at" and the store name of the store view (as set in Stores > Configuration > General > General > Store Information > Store Name, otherwise the name of the store), the customer's name and e-mail, the payment reference (order ID and attempt) and a random token of the attempt. Opening the payment again for the same order, mode, amount and merchant account reuses the same 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:

Magento then creates the invoice with the PayFast payment ID, the order moves to Processing and the order e-mail is sent. 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 Enable is No and without an active license, so payments already started are still confirmed.

When the customer comes back after paying, the standard order success page is shown with PayFast payment confirmed. If PayFast reported the payment as pending, the message is PayFast is confirming your payment. Do not pay again., and for a payment that needs your review Your PayFast payment requires manual review. Do not pay again. A customer who comes back in another browser lands on the home page with the same message. If the notification has not arrived yet, a short page says PayFast is confirming your payment. Do not pay again. with a Check again link. The return itself never pays an order.

If the customer cancels on the PayFast page, or PayFast reported the payment as failed, the order is cancelled (the stock goes back), the cart is restored and the customer sees The PayFast payment was not completed. You can try again. in the cart. While a payment of the cart is pending, on review or paid, a new payment form for that cart is not offered.

If the payment cannot be started, for example because the credentials of the current mode are missing, the order is not in ZAR or the total is below R5.00, the order is cancelled, the cart is restored and the customer sees PayFast could not start payment. Please check your order before retrying.

The payment method is hidden when the credentials of the current mode are missing, when the cart currency is not ZAR or when the total is below R5.00. An order in Pending Payment can be cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If money arrives for it later, the order is not reopened and a note asks you to review it.

The module works with the standard Magento checkout. It takes one-time payments in ZAR only. It has no online refunds, no subscriptions, no saved (tokenised) cards and no split payments. PayFast is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to PayFast, but the payment notification has not arrived yet. There is no invoice. If PayFast reports the payment as pending, a note says PayFast is confirming your payment. The order remains unpaid until a verified COMPLETE notification. and the order is paid when PayFast completes it. If PayFast reports it as failed, a note says PayFast payment failed. No money was recorded.; the order is cancelled when the customer comes back, and a later completed payment can still pay it until then.

Processing: PayFast confirmed the payment. The invoice is created with the PayFast payment ID in the transaction ID, and the note Verified PayFast ITN confirmed payment shows the payment ID. A sandbox payment also gets the note TEST MODE: no real money was charged; do not ship this order.

On Hold: no invoice is created and the note explains why: PayFast amount or currency does not match. No paid invoice was created., A sandbox PayFast payment arrived while the store is live. NOT marked as paid; do not ship. or, for an order that was already on hold or under review, PayFast payment requires manual review. Hold was not released automatically. Check the order and your PayFast dashboard, then release the hold and invoice the order manually, or cancel it and refund the payment in PayFast.

Canceled: the customer cancelled or did not complete the payment, the payment could not be started, or the order was cancelled in Magento. Money that arrives later for a cancelled or closed order, or for an order whose payment method is no longer PayFast, does not reopen it; a note says PayFast received money after cancellation, refund or a payment-method change. Review stock and native accounting; the order was not reopened.

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 a cart that is already paid, a note on the paid order asks you to refund the duplicate in the PayFast dashboard. The notes are order comments that the customer does not see.

PayFast payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the payment, PayFast payment ID, Payment reference and Environment (test or live). The customer sees only the payment method title. Below it the PayFast payment history block lists every payment attempt of the order with Payment reference, PayFast payment ID, Environment / status and ZAR gross / fee / net. The PayFast fee does not reduce the paid amount of the order. For a payment under review the block shows This payment requires manual review. Do not ship or pay again until reconciled. The block is shown also when the module is disabled.

Refunds

Refunds from Magento are not sent to PayFast. Refund the payment in your PayFast dashboard, then record it in Magento with a credit memo and Refund Offline, which does not send money back. The order page reminds you: Refunds are performed in the PayFast dashboard. Record native offline accounting 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 row of the VibeFox PayFast Pay Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-payfast and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees PayFast could not start payment. Please check your order before retrying. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

PayFast does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the Merchant ID and Merchant Key of the current mode are filled in (Sandbox Merchant ID and Sandbox Merchant Key in test mode), that the customer checks out in ZAR and that the order total is at least R5.00. The settings page shows a warning when something is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: PayFast could not deliver the payment notification, or it was rejected. Look at the Log row in the settings; 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 module, or, in live mode behind a proxy or CDN, the source check. In that case set Source check to No.

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. Set Source check to No if your store is behind a trusted proxy or CDN.

The notification answers Merchant mismatch or Order mismatch: the payment was made to another PayFast account, the Merchant ID was changed after the payment was started, or the notification 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 Not configured: the Merchant ID of the mode the payment was started in is missing. Enter it again, for example the sandbox credentials for a test payment.

The notification answers Validation failed: PayFast did not confirm the notification in the server-to-server check. 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 updated. PayFast sends the notification again. The log shows the reason.

The notification URL shows POST required in the browser: this is normal. The URL accepts only notifications from PayFast.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order stays in Pending Payment until a notification gets through.

The customer is back in the cart with PayFast could not start payment: the credentials of the current mode are missing, the order is not in ZAR, the total is below R5.00 or the license is not active. The order of that attempt is cancelled.

Order is On Hold after payment: read the order notes and the PayFast payment history block (see Order statuses) and your PayFast dashboard, then invoice the order or refund the payment.

A sandbox payment did not pay the order: the module is in live mode. Sandbox payments never pay an order in live mode; the order is put on hold with a note.

There is no Refund button on the credit memo: online refunds are not supported. Refund in the PayFast dashboard and use Refund Offline.

For developers: the event payfast_p_payment_data can change the payment form fields before they are signed. The merchant credentials, URLs, payment reference, amount and token cannot be changed by it.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PayfastPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PayfastPayment to remove the data, then bin/magento module:disable Vibefox_PayfastPayment, delete the folder app/code/Vibefox/PayfastPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete Data on Uninstall is Yes, the gateway settings, the cached PayFast addresses and the log are removed too. If it is No, the settings are kept for a re-install. The PayFast payment history is always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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