Quick answer
To set up PayFast in WooCommerce, create and verify a PayFast merchant account, set your store currency to ZAR and your store country to South Africa (WooCommerce > Settings > General), install the free official PayFast Payment Gateway plugin, and enter your Merchant ID, Merchant Key and Security Passphrase (WooCommerce > Settings > Payments > PayFast).
This is part of the Build a WooCommerce Store hub, which walks through setting up your shop, adding products and taking payments. Payments only work once the store exists, so start with how to set up WooCommerce for the first time if you have not done that yet; the other half of checkout is how to set up WooCommerce shipping zones, and the orders that follow are covered in how to manage orders in WooCommerce. Tick PayFast Sandbox and place a test order — on the test install the sandbox payment failed with a signature error, so the order stayed at “Pending payment” and no payment was completed (see “What I tested / What failed”). Then untick Sandbox, swap in your live credentials, and place one small real order yourself before telling customers the store is open. Most setups fail at the notification step, not the install. After a customer pays, PayFast sends your store a server-to-server message called an Instant Transaction Notification (ITN). That message — not the customer returning to your site — changes the order to “Processing”. If it never arrives, your customer has paid and your order stays stuck on pending.
Tested on
- WordPress: 7.1.4
- WooCommerce: 11.3.0
- PayFast Payment Gateway plugin: 1.7.9
- PHP: 8.4.27
- Theme: GeneratePress 3.6.1
- Test date: 15 November 2026
- Test install: a WordPress test install with one simple product (Sourdough Loaf, R85,00) and one variable product, set to ZAR and South Africa as the store country.
Tested 15 November 2026 on a WordPress test install. Screenshots are from that test install.
What is PayFast?
PayFast — now branded “Payfast by Network” — is a South African payment gateway shoppers already recognise. It is a payment aggregator, so you do not need your own merchant bank account to take card payments. One account lets your store accept credit and debit cards, Instant EFT, and local options such as Capitec Pay, SnapScan and buy-now-pay-later methods. (The payment-method list was not re-checked against payfast.io in this run.)
One hard rule shapes this guide: PayFast only processes payments in South African Rand (ZAR). Payments from any country may be accepted, but ZAR must be the store currency. If your store currency is USD, EUR or anything else, PayFast will hide itself at checkout. Set ZAR first.
Yoco, Peach Payments and Ozow are real alternatives; the short comparison near the end will help you decide if PayFast is the right first gateway for you. It is the usual starting point for small South African stores because it supports a wide range of local payment methods from one integration, and its WooCommerce plugin is free. What it charges must be checked on PayFast’s own pricing page — see the fees section.
What you need before you start
- WordPress with WooCommerce installed and activated, running over HTTPS. PayFast’s Notify URL must use
https://. - Store currency ZAR and store country South Africa (WooCommerce > Settings > General). The PayFast plugin’s September 2026 update restricted it to South African stores. (The restriction was not re-checked in this run; the test install is South African, so the gateway worked there.)
- A verified PayFast merchant account. Register at payfast.io and complete verification in the PayFast dashboard, uploading the documents PayFast asks for. Verification time varies. (Verification time and document list were not confirmed in this run — no live PayFast account was created; only the published sandbox credentials were used.) You cannot get live Merchant ID and Merchant Key values until the account is verified, so start this first.
- A bank account for payouts, entered in your PayFast dashboard.
- At least one test product. PayFast requires a minimum initial charge of R5.00. (The R5.00 minimum was not re-checked in this run; the test product cost R85,00, well above it.) A R1.00 test product will fail at checkout for a reason that looks like a gateway error but is actually a minimum-amount rule.
Keep your Merchant Key and Security Passphrase private — never paste them into a forum post or screenshot. The sandbox credentials in this article are PayFast’s published shared test credentials from its developer docs, not live credentials; your own live credentials are placeholders here, such as YOUR_MERCHANT_ID.
Step 1: Create and verify your PayFast account
Go to payfast.io and click Sign Up. Choose the account type that matches your business. (Account types were not re-checked in this run — no live account was created.) Enter your business, contact and bank details, upload the documents PayFast asks for, and wait for the approval email. A live checkout needs a verified account; the sandbox test below can be done with PayFast’s published sandbox credentials.
Step 2: Find your Merchant ID, Merchant Key and Security Passphrase
Once verified, log in to your PayFast dashboard. According to PayFast’s support documentation, your Merchant ID and Merchant Key are shown in the top right of your dashboard. (The dashboard layout was not re-checked in this run — no live PayFast account was created.)
The Security Passphrase is different from the Merchant Key, and confusing the two is one of the most common setup mistakes. It is a value you set yourself in your PayFast dashboard, under Settings > Integration. If the passphrase in WooCommerce does not match the one in your PayFast dashboard exactly — including case, spaces and special characters — payments will fail with a “security signature mismatch” error. If you have never set one, set it now and write it down somewhere safe.
Step 3: Enable Instant Transaction Notifications (ITN)
When a customer pays, two things happen. First, the customer is sent back to your store — the return URL. Second, PayFast’s server sends a message directly to your store’s server saying the payment succeeded. That second message is the Instant Transaction Notification (ITN). It is the ITN — not the customer’s return — that changes the order from “Pending payment” to “Processing”. If it never arrives, the customer has paid and your order still says pending.
In your PayFast dashboard, enable Instant Transaction Notifications and set the Notify URL to your store’s domain followed by /?wc-api=WC_Gateway_PayFast, using https://. Do not use a localhost URL for your live account. (The exact location of the ITN settings in the current dashboard was not confirmed in this run — no live PayFast account was created.)
PayFast’s support pages say the ITN URL is set automatically when you use an official module. Even so, check that ITN is enabled and the Notify URL is correct.
Step 4: Install the official PayFast Payment Gateway plugin
Use the official plugin first. It is free, developed by WooCommerce, and covered by WooCommerce’s own documentation. In WordPress, go to Plugins > Add New, search for WooCommerce Payfast Gateway, click Install Now, then Activate.
Check the plugin’s requirements first — WooCommerce’s documentation and a newer third-party guide disagree on the minimum WordPress and WooCommerce versions. (The exact minimum versions were not confirmed in this run; the version installed on the test install was 1.7.9 — see the Tested on box.) If yours is older than the minimum, update it first, on a backup.
Step 5: Enter your credentials in WooCommerce
Go to WooCommerce > Settings > Payments, find PayFast, and click Set up (or Manage).
- Enable/Disable — tick this to offer PayFast at checkout.
- Title — what customers see, for example “PayFast (Card, Instant EFT, SnapScan)”.
- Description — a one-line description shown under the title at checkout.
- PayFast Sandbox — tick this while testing. Untick it when you go live. Forgetting it in either direction is the most common live-store mistake.
- Merchant ID, Merchant Key and Passphrase — paste the values from your PayFast dashboard. The passphrase must match exactly.
- Send Debug Emails — Sandbox mode only; enter your email address to receive an email for each test transaction. Turn it off for live.
- Enable Logging — tick this. It writes transaction events to WooCommerce > Status > Logs, the first place you look when anything goes wrong. Leave it on for the first week after going live.
Click Save changes. Two warnings: your Merchant ID and Merchant Key must be correct even in Sandbox mode, and sandbox and live Merchant IDs are different. When you go live, swap the credentials as well as unticking Sandbox. The test run proved the first warning: the sandbox payment failed with a signature error even with PayFast’s published sandbox credentials (see “What I tested / What failed”).
Step 6: Test in PayFast sandbox test mode WooCommerce
PayFast’s sandbox, at sandbox.payfast.co.za, runs the whole payment flow without moving real money, using a virtual wallet in place of the real payment methods. It does not send email confirmations.
Find your sandbox Merchant ID, Merchant Key and Passphrase in your PayFast dashboard — these differ from your live credentials. PayFast also publishes shared sandbox credentials in its developer docs (https://developers.payfast.co.za/docs, “Test transaction setup”): Merchant ID 10000100, Merchant Key 46f0cd694581a, Passphrase jt7NOE43FZPn. These are PayFast’s published shared sandbox test credentials, not live credentials. Use your own sandbox account where possible. Note: on the test install, a payment attempt with these published credentials failed with a signature error — see “What I tested / What failed”.
In WooCommerce, go to WooCommerce > Settings > Payments > PayFast, tick PayFast Sandbox, replace the credentials with your sandbox equivalents, and click Save changes. Then place a test order as a customer would, and check it in WooCommerce > Orders. It should move from “Pending payment” to “Processing” once the sandbox ITN arrives. On the test install it did not — the sandbox payment failed with a signature error, so the order stayed at “Pending payment” and no ITN arrived (see “What I tested / What failed”). If it stays on pending, do not go live — fix it in sandbox first. Also check WooCommerce > Status > Logs to see whether the ITN arrived.
Use a different email address for the test order from the one linked to your PayFast account. Also test the failure paths: cancel a payment and confirm the order stays pending, try a test order below R5.00, and test a variable product with a variation selected. (None of these failure paths was tested on the test install in this run — the sandbox payment failed with a signature error before any payment could be completed, so there was no cancelled, below-minimum or variable-product payment to check.)
Step 7: Go live — and place one small real order first
When sandbox testing passes cleanly, go to WooCommerce > Settings > Payments > PayFast, untick the PayFast Sandbox checkbox, replace the Merchant ID, Merchant Key and Passphrase with your live credentials, check the Notify URL and ITN settings one more time, and click Save changes.
Then place one small real order yourself — buy your cheapest product with your own card — and confirm the payment lands in your PayFast dashboard, the order moves to “Processing”, and the money is visible in your balance. Refund yourself afterwards if you like; the point is to prove the live flow end to end before a customer tries it. Then tell customers the store accepts online payments. Keep logging enabled for the first week.
What does PayFast cost? Check the fees on the day
PayFast’s fees change, and a fee table copied from an article — including this one — is the wrong place to make a pricing decision. No fee figures are stated here as fact, because none were verified against PayFast’s own fees page.
Before you publish, and before you choose a gateway, open payfast.io/fees and record, with the date: the per-transaction rate and flat fee for each payment method you offer; any setup or monthly fee; the payout fee; the refund fee, if any; and whether the figures are excluding or including VAT.
Two cost details catch new store owners by surprise. First, the flat per-transaction fee matters most on small orders. Second, the payout fee is per withdrawal, not per transaction, so withdrawing weekly costs far more over a year than withdrawing monthly. Re-check Yoco, Peach Payments and Ozow on their own pricing pages on the same day, and run your own numbers on your own average order value before choosing.
Troubleshooting
Most PayFast problems trace back to credentials or blocked notifications. Match the symptom to the fix, and check the log before changing anything.
PayFast order stuck on pending WooCommerce — fix the ITN
The customer has paid and your store does not know it — the ITN is not arriving or is not passing validation. Check in order:
- PayFast dashboard first. Is the payment actually there? If not, the customer may not have completed it.
- Notify URL. It must be
https://yourdomain.com/?wc-api=WC_Gateway_PayFast. - WooCommerce > Status > Logs, with logging enabled. The log names the exact reason the ITN was rejected.
- Caching and security plugins. They are the usual cause of missing ITNs — they can cache the Notify URL or block the request from PayFast’s server. Exclude the Notify URL from page caching. Cloudflare showing a challenge page to PayFast’s server will also break the ITN, because a server cannot solve a CAPTCHA. This is a known, still-open issue on the official plugin’s GitHub tracker. (The current status of GitHub issue #11 was not confirmed in this run.)
- Your host’s firewall. PayFast’s support documentation advises whitelisting the IP addresses and ports on its developer documentation, and notes cPGuard’s firewall on cPanel hosts treating ITNs as brute-force attacks. Discuss any change with your host first. (The current IP whitelist was not confirmed in this run.)
If the order is stuck but the payment is confirmed in PayFast, do not mark the order as paid by hand and forget about it — find out why the ITN failed first, or the next order will stick too.
PayFast security signature mismatch — the passphrase fix
This almost always means the Security Passphrase in WooCommerce does not match the one in your PayFast dashboard, or it is set in one place and not the other. Fix it by resetting the passphrase in PayFast and copying the new value into the WooCommerce PayFast settings — do not guess which side is wrong. Check for an extra space at the start or end of the pasted value, and confirm you have not confused the passphrase with the Merchant Key. Then place another test order in sandbox mode. This is exactly what happened on the test install: a sandbox test order with PayFast’s published sandbox credentials failed with “Error: 400 Bad Request — Unfortunately we could not process your transaction. The following information provided by the seller is invalid: signature: Generated signature does not match submitted signature.” — see “What I tested / What failed”.
“Bad source IP address” in the logs (live mode only)
This check applies when Sandbox mode is disabled. WooCommerce checks that the notification came from a trusted IP address, but the address can appear different if your host redirects traffic — WooCommerce’s documentation calls this a known limitation of its own source-IP check. Verify the Merchant ID, Merchant Key, Passphrase, Notify URL and ITN settings first.
PayFast not showing at checkout — ZAR currency / country check
The gateway hides itself when it cannot complete a payment. Check, in order: the store currency is ZAR, the store country is South Africa, the gateway is enabled under WooCommerce > Settings > Payments, and a Merchant ID and Merchant Key are filled in for the mode you are in — sandbox credentials in sandbox mode, live credentials in live mode. If any of those is wrong, PayFast simply does not show up, with no error message. Also check that no currency-switcher plugin is sending a non-ZAR amount to PayFast: a “currency format invalid” error usually means a plugin or multi-currency setting is at fault.
Test mode left on, and checkout errors in sandbox mode
If the PayFast Sandbox checkbox is still ticked after you go live, customers will be sent to the sandbox, their payments will not be real, and you will not receive any money. There is no error message. Before you announce the store is open, check the sandbox checkbox one final time, and confirm the live Merchant ID is in place.
Use the sandbox Merchant ID and Key in sandbox mode, not your live ones. Mixing the two sets produces checkout errors that look like a broken plugin. Also confirm the test order meets the minimum amount, and that you are testing with a different email address from the one linked to your PayFast account.
PayFast and WooCommerce Subscriptions
PayFast works with WooCommerce Subscriptions, a separate paid extension. If you sell subscriptions, use PayFast’s Recurring Billing instead of WooCommerce’s built-in renewals, and enable Ad hoc Payments in the Recurring Billing section of your PayFast dashboard. (Subscriptions behaviour was not tested in this run — the test install has no subscriptions.)
PayFast vs Yoco South Africa
This is a PayFast setup guide, not a comparison — but a short note helps you decide whether it is the right first gateway. PayFast is the default for most small South African stores: a wide range of local payment methods from one integration. Yoco is strong for businesses that also sell in person, because the same account covers card machines and online payments. Peach Payments and Ozow are also worth a look — Ozow, for example, is often cheaper on EFT. (Competitor rates were not re-checked in this run; check each provider’s own pricing page.)
The right gateway depends on how your customers actually pay — if most pay by Instant EFT, the EFT rate matters more than the card rate; if your average order is small, the flat fee matters more than the percentage. Run your own numbers, and re-check the live fee pages — do not choose a gateway on a fee table from an article, including this one.
Next steps
- Create and verify your PayFast account — the step with the longest wait, so start it first.
- Set ZAR as your store currency and South Africa as your store country.
- Install the official PayFast Payment Gateway plugin and enter your credentials, with the Sandbox box ticked.
- Place a sandbox test order and confirm the order moves to “Processing” and the ITN appears in the logs. (On the test install, the sandbox payment failed with a signature error, so the order stayed at “Pending payment” — see “What I tested / What failed”.)
- Go live: untick Sandbox, swap in live credentials, and place one small real order yourself.
- Keep logging on for the first week and check your orders daily.
- If you sell subscriptions, enable Ad hoc Payments first.
If you get stuck on an order that stays pending, start at WooCommerce > Status > Logs before you change any setting. The log tells you what actually happened.
What I tested / What failed
Tested 15 November 2026 on the WordPress test install (WordPress 7.1.4, WooCommerce 11.3.0, WooCommerce Payfast Gateway 1.7.9, PHP 8.4.27, GeneratePress 3.6.1). The gateway was installed from WooCommerce → Payments → “More payment options” → Payfast (Official). WordPress showed: “WooCommerce Payfast Gateway (1.7.9) was successfully installed and activated.”, then “Action needed” / “Complete setup”. Note: the plugin header says “WC tested up to: 11.1”, while the test install runs WooCommerce 11.3.0. Settings used: “Payfast works by sending the user to Payfast to enter their payment information.”; Enable Payfast ticked on; Payfast Sandbox checked by default (“Place the payment gateway in development mode.”); Merchant ID 10000100, Merchant Key 46f0cd694581a, Passphrase jt7NOE43FZPn — PayFast’s published shared sandbox test credentials from its developer docs (https://developers.payfast.co.za/docs, “Test transaction setup”), not live credentials; Sandbox URL https://sandbox.payfast.co.za; Send Debug Emails checked, recipient the test install’s email address; Enable Logging later ticked on. “Your settings have been saved.” — the settings page confirms “Sandbox Merchant ID currently in use ( 10000100)” / “Sandbox Merchant Key currently in use ( 46f0cd694581a)”. Test order: Sourdough Loaf, SKU BREAD-SOU-01, R85,00; checkout as Test Baker, 1 Test Street, Cape Town, Western Cape 8001, South Africa; Free shipping; Payfast the only payment method. Order #41, 15 November 2026 11:34, Pending payment, R85,00.
What failed — the payment. Place Order redirected to the PayFast sandbox, which returned verbatim “Error: 400 Bad Request — Unfortunately we could not process your transaction. The following information provided by the seller is invalid: signature: Generated signature does not match submitted signature.” A second checkout reached the identical error. Diagnosis: the shared sandbox account 10000100’s real passphrase (and/or merchant key) does not match PayFast’s published test credentials; two code experiments on the test install (including/excluding “source” from the signature; computing the signature with no passphrase) both still failed; the plugin was reinstalled pristine afterwards and its settings are intact (Enable checked, Sandbox checked, Merchant ID 10000100, Merchant Key 46f0cd694581a, passphrase saved); the reinstalled gateway shows a “Test account” badge. No test card was ever entered (the payment screen was never reached); no real money; no account created.
What this means for your site
The payment itself was not completed in the test run for this guide — the PayFast sandbox payment failed with a signature error — so this guide does not claim a completed test payment. There is no declined-card result, no order email and no double-charge result from this run, and the failure paths (cancelling a payment, a test order below R5.00, a variable product) were not tested. Before you go live, run your own sandbox test with a real PayFast sandbox account (email signup) and place one small real order yourself — see Step 7.
Mohd Shah Ahmad is a WordPress & WooCommerce specialist based in Pretoria, South Africa. He builds and runs live WooCommerce stores, and manages the live stores Stanley’s Bakery (stanleysbakery.co.za) and Aaliyah Perfumes (aaliyahperfumes.co.za).