Payfast Payment Gateway

Payfast Payment Gateway allows you to process payments via the South African payment processor, Payfast. Payment from any country may be accepted, but it is required to use ZAR as the store currency.

Requirements

↑ Back to top

• A Payfast account to obtain a Merchant ID and Merchant Key. Note that Merchant IDs for developers and live sites are different, so you may need to update those on your live site.
• Instant Transaction Notification (ITN) should be enabled. Replace the following with your domain name for the Notify URL: https://yourdomain.com/?wc-api=WC_Gateway_PayFast
• WooCommerce 10.7 or higher
• WordPress 6.8 or higher
• PHP 7.4 or higher

Sign up for a Payfast account

↑ Back to top

1. Create or verify your Payfast merchant account.
2. Obtain your Merchant ID, Merchant Key, and Security Passphrase from Payfast.
3. Enable Instant Transaction Notifications (ITNs) and configure the Notify URL using your store domain: https://yourdomain.com/?wc-api=WC_Gateway_PayFast. See Payfast’s ITN documentation for Payfast account instructions.

If you’re using the WooCommerce Subscriptions and/or WooCommerce Pre-Orders, extensions, confirm that Ad hoc Payments are enabled in the Recurring Billing section. 

Setup and configuration

↑ Back to top

To connect your store to Payfast:

1. From your store’s WP Admin dashboard, navigate to WooCommerce > Settings > Payments > Payfast.
2. Use the toggle under Enabled to enable Payfast.
3. Click the Set up button to be taken to the settings screen. From here, you’ll see the following options displayed:
   1. Enable/Disable: Check this box to enable Payfast as an option on the checkout page.
   2. Title, Description: Shown to customers at checkout (optional).
   3. Payfast Sandbox: Check this box if you are developing your website and are not ready to accept payments and/or wish to test this integration.
   4. Merchant ID, Merchant Key, Passphrase: Obtained from your Payfast account as outlined in Sign up for a Payfast account above.
   5. Send Debug Emails, Who Receives Debug Emails?: In Sandbox mode only, check this box and enter an email address to receive email notifications for each transaction (optional).
   6. Enable Logging: When checked, this option creates a log in WooCommerce > Status > Logs to record transaction event information. This is useful for troubleshooting.
4. Save changes.

After saving, Payfast is available as a payment method at checkout. For a complete check, place a Sandbox test order and review WooCommerce > Status > Logs for the payment notification.

This extension uses the Merchant ID and Merchant Key fields to send cart information to your Payfast account.

Troubleshooting payment notifications

↑ Back to top

When logging is enabled, payment and notification errors are recorded under WooCommerce > Status > Logs. Check the log before changing credentials or contacting support.

• Security signature mismatch: Verify that the Passphrase in your store matches the Payfast account. If it appears to match, reset the passphrase in Payfast, save it, and copy the new value into the store settings.
• Bad source IP address: This check applies when Sandbox mode is disabled. It is a known limitation of the extension’s own source-IP check, not a host or firewall allowlisting problem. Verify the Merchant ID, Merchant Key, Passphrase, Notify URL, and Instant Transaction Notification settings for the environment you are using. If the error persists after those checks, see Payfast source IP validation filter for Developer-level guidance.

Compatibility with other extensions

↑ Back to top

Payfast works well with several extensions. Please bear in mind that the initial charge must not be less than R5.00 ZAR.

WooCommerce Subscriptions

↑ Back to top

Payfast works with WooCommerce Subscriptions (separate purchase). Configure a simple or variable subscription product as described in the extension’s documentation.

Using Payfast with WooCommerce Subscriptions:

• Basic features: Subscription suspension and subscription cancellation
• Advanced features: Recurring total modification, payment date modification, customer payment method changes

Payfast supports purchasing multiple subscriptions in a single order.

Cancellation works from both the WooCommerce store and the Payfast side. If you cancel via the store, the token is canceled at Payfast. If you cancel via Payfast, the order is canceled locally.

WooCommerce Pre-Orders

↑ Back to top

Payfast works with WooCommerce Pre-Orders (separate purchase). Configure the products as described in the extension’s documentation.

WooCommerce Pre-Orders will not work if no initial fee is charged. To address this, there are two options:

• If you want to charge Upon Release, you first need to set a Pre-Order Fee.
• If you charge the full amount Upfront, setting a Pre-Order Fee is optional. 

Testing Payfast

↑ Back to top

You can test this Payfast Payment Gateway before going live using Payfast Sandbox credentials.

To do this:

1. In your WP Admin dashboard, go to WooCommerce > Settings > Payments > Payfast.
2. Tick the Payfast Sandbox checkbox to put the gateway in test mode.
3. Replace your Merchant ID, Merchant Key, and Passphrase with the equivalents in your Payfast Sandbox.
4. Click Save changes.

Note: Once you’re ready to go live, be sure to untick the Payfast Sandbox checkbox and review your live credentials again. Your Merchant ID and Merchant Key must be entered correctly in the appropriate fields, even when using Sandbox mode — otherwise, there will be a checkout error. Merchant IDs for developers and live sites are different, so you may need to update those on your live site after testing.

Questions and feedback

↑ Back to top

Need some assistance? Get in touch with a Happiness Engineer via the Help Desk.