WooCommerce payment gateways in South Africa: setup and troubleshooting

Start from your customers, not from the plugin directory. How payments work in South Africa explains the card, EFT and PayShap rails underneath WooCommerce; this page is about choosing and running the gateway on top. If most of your customers pay from a bank account, the cheapest published rate for that is Ozow's 1.5% with a minimum of R1^{[Ozow pricing page, checked 2026-11-04]}. If most pay by card, Paystack (2.9% + R1^{[Paystack pricing, checked 2026-11-04]}) and Peach Payments (2.95% + R1.50^{[Peach Payments fees page, checked 2026-11-04]}) are close, and Payfast (3.2% + R2^{[payfast.io fees page, checked 2026-11-05]}) costs more. Payfast earns its place when you want instalment, scan-to-pay and store-card options through one gateway: it lists 18 or more payment methods^{[Payfast home page, checked 2026-11-05]}, including Payflex, MoreTyme, Mobicred, SnapScan, Zapper and store cards^{[payfast.io fees page, checked 2026-11-05]}.

South African gateways for a WooCommerce store: published rates and official docs

Gateway	Local cards	Bank payments	Official developer docs
Payfast	3.2% + R2	Instant EFT 2% + R2	developers.payfast.co.za
Paystack	2.9% + R1	EFT 2%, no flat fee	paystack.com/docs
Ozow	2.85% (minimum R1)	Pay by Bank 1.5%, minimum R1	hub.ozow.com
Peach Payments	2.95% + R1.50 excluding VAT (Growth plan)	Pay by Bank 1.50% + R1.50 (all banks except Capitec)	developer.peachpayments.com
iKhokha	From 2.85%	Not verified	developer.ikhokha.com
Yoco	Not verified	Not verified	developer.yoco.com (APIs, SDKs and plugins)

Last verified: 2026-11-04. Sources, checked 2026-11-04 to 2026-11-05: payfast.io fees page, PayFast Developer Documentation, Paystack pricing, Paystack docs, Ozow pricing page, Ozow developer hub, Peach Payments fees page, Peach Payments documentation hub, ikhokha.com, Yoco Developer Hub. Rates as each provider publishes them; we re-check every fee against the provider's pricing page regularly. Payfast, Paystack, Peach Payments and iKhokha publish their rates excluding VAT; Ozow's pricing page does not say. Not verified means we have not confirmed a published rate. Install plugins only from the source the provider's own docs point to.

Two points the table does not show. First, Ozow says its payments involve no credit card chargebacks and no reverse transactions^{[Ozow FAQ, checked 2026-11-05]}, which matters for stores selling digital downloads or event tickets. Second, Payfast joined forces with Paygate and SiD under Network International^{[Payfast press release, checked 2026-11-04]}, so a store still running an old Paygate plugin should ask Network International about its migration route.

The full fee and developer comparison is in Payfast vs Paystack vs Ozow vs Peach Payments. If you use Paystack, our Paystack hub has a dedicated guide to Paystack for WooCommerce, so this page does not repeat it.

WooCommerce gateway plugins follow the same basic loop, and knowing it makes most problems easy to place:

1. Checkout creates the order with the status Pending payment.
2. The customer pays on the gateway's hosted page or in a payment form the plugin embeds.
3. The gateway sends a server-to-server notification to a callback URL on your site. This is the message that matters.
4. The plugin verifies the notification (a signature, a hash or a call back to the gateway's API) and moves the order to Processing, or to Completed for virtual and downloadable products.
5. The customer's browser returns to your thank-you page. This return is a courtesy, not proof of payment.

Steps three and four are where stores break. The browser can come back with a success message while the notification fails, or the customer can close the tab before the redirect while the notification succeeds. A well-built store trusts only the verified notification, then reconciles what is left against the gateway's settlement report.

The steps are the same whichever provider you choose; the field names differ by plugin.

1. Get the merchant account approved first. The gateway will ask for company and bank documents, because the FIC Amendment Act of 2017 provides for a risk-based approach to client identification and verification^{[FIC Amendment Act, checked 2026-11-05]}. Start this before the build, since approval can take longer than the plugin setup.
2. Install the plugin from the source the provider's documentation names, either its own download or the WordPress directory listing it links to. A copy from a third-party site is a security risk on a page that handles payments.
3. Set the store currency to South African rand under WooCommerce, Settings, General, unless the provider's docs say the plugin accepts another currency.
4. Enter test credentials and switch on test mode. Store test and live credentials as separate, clearly labelled entries so they never get mixed.
5. Find the callback URL the plugin uses and confirm it loads from outside your network over HTTPS, with no login prompt and no redirect.
6. Run four test orders: a successful payment, a declined one, a cancelled one, and a refund of the successful one.
7. Switch to live credentials, make one small real payment, and refund it.
8. Review Hold stock under WooCommerce, Settings, Products, Inventory (more on that below).

Turn on WooCommerce logging for the gateway while you test, and remember that POPIA requires the responsible party to ensure its conditions for processing personal information are complied with^{[POPIA, checked 2026-11-05]}: payment logs hold customer names and email addresses, so clear old logs on a schedule.

Because the notification in step three never reached WooCommerce, or arrived and failed verification. Work through the causes in this order:

• The site is not public. Maintenance mode, a coming-soon plugin or password protection on a staging site blocks the gateway along with everyone else.
• A security layer blocks the request. Security plugins, web application firewalls and bot protection at the CDN can reject a POST from a server they do not recognise. Allow the callback path through.
• A redirect eats the request. If the plugin registered http:// and your site forces https://, or registered the bare domain and you redirect to www, many HTTP clients either refuse to follow a redirect on a POST or follow it as a GET and drop the body. Register the exact final URL.
• The callback is cached. Page caches must never cache the callback URL or the checkout.
• Test and live are mixed. Live credentials on a site still in test mode, or the other way round, make every signature check fail.
• The plugin crashed. A PHP error during the callback leaves the order untouched. WooCommerce, Status, Logs will show it.

To diagnose, compare three records for the same order: the gateway dashboard's record of the transaction, your web server's access log for POST requests to the callback path, and the WooCommerce log. The first one that does not show the event tells you where it stopped.

Usually one of four things:

• Block checkout support. Recent WooCommerce versions build new checkout pages with the Checkout block. A plugin that has not added block support will not appear there. Update the plugin, or switch the checkout page back to the classic checkout shortcode to confirm the cause.
• Currency. A plugin may hide itself when the store currency is one it does not support.
• Enabled, but not for everyone. Some plugins offer a test mode visible only to administrators. Check in a private browser window.
• Your own rules. Minimum or maximum order amounts, shipping-method restrictions and country limits in the plugin settings all hide a gateway quietly.

WooCommerce holds stock for unpaid orders for a set time, then cancels them. That works for card payments, which confirm in seconds. It fails when a customer leaves a bank-payment page open, gets distracted, and pays later: the notification arrives for an order WooCommerce has already cancelled.

Two fixes, and you want both. Set a longer Hold stock time, or none, if bank payments are a large share of your orders. And check how your plugin treats a payment for a cancelled order: it should reinstate the order or flag it, never swallow the payment. If it does neither, add a daily job that compares the gateway's paid transactions with cancelled orders.

Signature and hash checks fail when the two sides compute the message differently. The common causes are a passphrase or secret that differs between the plugin settings and the gateway dashboard, an amount formatted differently (decimals, thousands separators), and a plugin or theme that changes the order total after the payment request was built, such as a late shipping fee or discount. Fix the order of operations so the amount is final before the payment request is created.

Duplicates come from customers clicking twice, pressing back and paying again, or a gateway retrying a notification your site already processed. Two habits prevent most of them: disable the place-order button after the first click, and make the callback handler idempotent, so it checks whether the order is already paid before it changes anything. The pattern is the same as for a custom build, covered in payment webhooks and reconciliation, and the provider-specific detail is in our guides to Payfast notifications, Ozow notifications and Peach Payments webhooks.

If you would rather someone set the store up and own these fixes, Mctaba Labs payment integration does WooCommerce gateway work as well as custom builds.

A plugin is the right call for a standard store. Move to custom code when the store needs something a plugin was not designed for:

• Two or more gateways with routing, for example cards on one and Instant EFT on another with failover between them.
• Marketplace payouts, where each order splits between sellers. See payment gateways for marketplaces.
• Recurring collections by debit order or DebiCheck, which a checkout plugin is not built to handle end to end.
• Reconciliation into your accounting system, matched payout by payout.

At that point a custom integration can be simpler to run than a stack of plugins. Shopify Payments in South Africa covers the other platform question merchants ask, and payments in Southern Africa has the regional view. When the custom route makes sense, Mctaba Labs payment integration builds it.