Skillmerc Payment Gateway for PayFast

By skillmerc

0+ active installationsVersion 0.1.6

PayFast for WooCommerce in South Africa: card, Instant EFT and SnapScan, orders that update reliably via ITN, refunds, HPOS and block checkout.

Description

Skillmerc Payment Gateway for PayFast lets South African stores take payments through PayFast’s hosted payment page (card, instant EFT, SnapScan and Mobicred) and keeps WooCommerce order statuses in step with what PayFast actually reports.

It was written to fix the things South African merchants complain about most: order statuses that never update because the ITN callback silently fails, no refund path from the order screen, no High-Performance Order Storage support, and settings scattered across several screens.

What it does

  • PayFast hosted checkout for card, instant EFT, SnapScan and Mobicred.
  • One toggle to switch between the PayFast sandbox and your live account. Each mode keeps its own credentials, so switching back and forth never means retyping keys.
  • Order status sync through Instant Transaction Notification (ITN), with signature verification, source host verification, amount matching, server confirmation and replay protection. Every rejection is logged with the reason, so a broken callback is diagnosable instead of silent.
  • Refunds sent to PayFast straight from the WooCommerce order screen (needs API access on your PayFast account).
  • Full High-Performance Order Storage (HPOS) compatibility, with no legacy post meta.
  • Optional South African number formatting for Rand amounts (R 1 234,56).
  • Works the moment you activate it: sandbox mode is on with PayFast’s published test credentials already filled in.
  • Every setting is on one screen, at WooCommerce → Settings → Payments → Skillmerc Payment Gateway for PayFast.

Pro version

The free plugin covers once-off payments. Skillmerc PayFast Pro adds PayFast subscriptions (sign-up, automatic renewal and cancel from WooCommerce), a notification log, and an automatic re-query every 15 minutes that marks orders paid when PayFast confirms a payment whose notification never arrived, plus Ozow instant EFT and Yoco card payments (both in beta). USD 49 a year for one site, with a 14-day money-back guarantee: https://checkout.freemius.com/plugin/40911/plan/70874/licenses/1/

The free plugin stays fully functional without Pro. Nothing is locked or time-limited. The gateway settings screen shows one short panel about Pro, which any admin can hide with one click, and the Plugins screen shows a “Get Pro” link. Neither appears once Pro is active, and there are no notices anywhere else in your dashboard.

Switching from another PayFast plugin

If your current PayFast plugin leaves paid orders stuck on pending, throws errors on your PHP version, or has no refund button, you can move over in a few minutes:

  1. Install and activate this plugin. It uses its own gateway ID, so it does not clash with other PayFast plugins.
  2. Enter the same merchant ID, merchant key and salt passphrase you already use. Your PayFast account does not change.
  3. Place a test order in sandbox mode, then switch to live.
  4. Disable the old PayFast gateway under WooCommerce, Settings, Payments, so shoppers only see one PayFast option. Keep the old plugin installed (just disabled) while you still have older orders that were paid through it.

The code is checked on PHP 7.4 through 8.5 and tested end to end against the PayFast sandbox on PHP 8.2.

External services

This plugin talks to PayFast, and only to PayFast. There is no tracking, no analytics and no phone-home of any kind.

  • Shoppers are redirected to https://www.payfast.co.za (or https://sandbox.payfast.co.za in sandbox mode) to complete payment. The order number, order total, item description and the billing name and email address are sent so PayFast can process and receipt the payment.
  • When PayFast notifies your store of a payment, the plugin posts the notification back to https://www.payfast.co.za/eng/query/validate (or the sandbox equivalent) to confirm PayFast really sent it. This is PayFast’s documented server confirmation step and is what makes a forged callback unusable.
  • If you switch refunds on, refund requests are sent to https://api.payfast.co.za. This only happens when you refund an order in WooCommerce, and the setting is off by default.
  • Source host verification does a DNS lookup of PayFast’s ITN hostnames. You can switch it off with the wc_payfast_pro_verify_itn_source filter if your host sits behind a proxy.

PayFast is a service of DPO South Africa (Pty) Ltd. Terms: https://payfast.io/legal/ and privacy policy: https://payfast.io/privacy-policy/

Installation

  1. Upload the plugin folder to /wp-content/plugins/, or install it from Plugins → Add New.
  2. Activate the plugin.
  3. Go to WooCommerce → Settings → Payments → Skillmerc Payment Gateway for PayFast.
  4. Set your store currency to ZAR under WooCommerce → Settings → General. PayFast only accepts South African Rand.
  5. Place a test order with sandbox mode on. When you are happy, untick sandbox mode and enter your live merchant ID, merchant key and salt passphrase from your PayFast dashboard.

You do not need to configure a notify URL in your PayFast dashboard. The plugin sends its own ITN callback URL with every payment.

FAQ

Do I need a PayFast account?

Yes. Register at payfast.co.za, then copy the merchant ID and merchant key from Settings in your PayFast dashboard.

Why is PayFast not showing at checkout?

The gateway hides itself when it cannot complete a payment. Check that your store currency is ZAR and that a merchant ID and merchant key are filled in for the mode you are in (sandbox or live).

PayFast shows the payment, but my WooCommerce order is still pending or on hold.

That means the ITN callback is not arriving or not passing validation. Switch the debug log on in the gateway settings, place a test order, and read WooCommerce → Status → Logs, source skillmerc-payment-gateway-for-payfast. The log names the exact reason: signature mismatch, amount mismatch, unknown source host or failed server confirmation. A signature mismatch is almost always a salt passphrase that is set in your PayFast dashboard but not in the plugin, or the other way round. Step-by-step fixes for pending orders, invalid signatures, passphrase mismatches, refunds and Cloudflare are at https://skillmerc.github.io/payfast-woocommerce/help/ and work with any PayFast plugin.

Can I refund from WooCommerce?

Yes, once you tick the refunds setting. PayFast has to enable API access on your account first, and you must have a salt passphrase set. Refunds are not available in sandbox mode, because PayFast’s sandbox does not implement the refunds API.

Is this HPOS compatible?

Yes. The plugin declares compatibility with High-Performance Order Storage and reads and writes order data through the WooCommerce CRUD API only.

Does it work with the checkout block?

Yes. The gateway registers a payment method with the checkout block as well as the classic shortcode checkout, so it appears in both.

Does this plugin send my data anywhere?

Only to PayFast, only to process your payments, and only as described in the Description section. There is no telemetry.

Can I run it next to the official PayFast plugin?

Yes. The two use different gateway IDs and different order fields. Disable the one you are not using at checkout so shoppers do not see PayFast twice.

Which PHP and WordPress versions does it support?

PHP 7.4 or newer and WordPress 6.4 or newer, with WooCommerce active. The code is checked on PHP 7.4 through 8.5.

Is this the official PayFast plugin?

No. It is an independent plugin and is not affiliated with or endorsed by PayFast or DPO.

Changelog

0.1.6

  • Fixed: the debug log setting and the FAQ now name the log source the plugin actually writes to (skillmerc-payment-gateway-for-payfast). No change to payments.
  • Docs: link to step-by-step troubleshooting guides.

0.1.5

  • Added: a short, dismissible panel about the optional Pro version on the gateway settings screen, and a “Get Pro” link on the Plugins screen. Both disappear when Pro is active. No change to payments.

0.1.4

  • Docs: describes the optional Pro version. No code changes.

0.1.3

  • Docs: setup notes for stores switching from another PayFast plugin, and clearer troubleshooting for orders that stay pending. No code changes.

0.1.2

  • Fixed: ITN signatures are now checked the way PayFast computes them (every posted field, including empty custom fields), and against the values exactly as posted. Before this fix genuine notifications were rejected with “Invalid signature” and orders stayed pending. Found against the live sandbox.
  • Fixed: the default sandbox credentials now use PayFast’s shared sandbox account with a passphrase (10004002), because the passphrase-free account rejects signed requests.
  • Added: a “Reverse proxy” setting that reads the notification source from X-Forwarded-For for sites behind a proxy or CDN.

0.1.1

  • Plugin and author links point to live pages.
  • The gateway uses the plugin’s own name in the WooCommerce settings.

0.1.0

  • First release.
  • PayFast hosted payment page checkout with sandbox and live modes.
  • ITN listener with signature, source host, amount, server confirmation and replay checks.
  • Refunds from the WooCommerce order screen.
  • HPOS support and a cart/checkout block payment method integration.
  • Optional ZAR display formatting.