Optimizing WooCommerce Checkout Flow for SA Payment Gateways (PayFast, Yoco)

This article is about configuring payment gateways on your own WordPress/WooCommerce store. It is not about the INNOVATECH GROUP billing portal or its payment methods. The INNOVATECH GROUP portal uses its own payment gateways for client invoice payments — those are entirely separate from the WooCommerce plugins described here.

If you run a WooCommerce-powered online store hosted on your INNOVATECH GROUP hosting account, this guide covers how to set up and optimise the two most commonly used South African payment gateways — PayFast and Yoco — for a smooth checkout experience.

Prerequisites

• A WordPress website with WooCommerce installed and activated
• Administrator access to your WordPress dashboard
• A merchant account with PayFast, Yoco, or both
• Your store is accessible over HTTPS (required by both payment gateways)

PayFast: Installation and Configuration

PayFast is one of South Africa's most established payment gateways, supporting credit cards, debit cards, EFT, SnapScan, and other local payment methods.

Step 1: Install the PayFast Plugin

1. Log in to your WordPress admin dashboard.
2. Navigate to Plugins → Add New.
3. Search for PayFast in the plugin directory.
4. Install and activate the official PayFast payment gateway plugin for WooCommerce.

If the plugin is not available in the directory for your WordPress version, check the PayFast developer portal for the latest compatible release or GitHub repository.

Step 2: Obtain Your PayFast Credentials

You will need the following from your PayFast merchant dashboard:

• Merchant ID — a unique numeric identifier for your PayFast account
• Merchant Key — an alphanumeric key paired with your Merchant ID
• Passphrase (Salt Passphrase) — a security string you set in your PayFast dashboard under Settings → Security. This passphrase is used to generate and verify transaction signatures and is required for subscriptions and strongly recommended for all integrations.

These credentials are found in your PayFast dashboard after logging in. Your live credentials are different from your sandbox credentials — do not mix them.

Step 3: Configure the Plugin

1. In your WordPress admin, navigate to WooCommerce → Settings → Payments.
2. Find PayFast in the payment methods list and click Manage (or Set up).
3. Enable the payment method.
4. Enter your credentials:
   • Merchant ID
   • Merchant Key
   • Passphrase
5. Set the mode:
   • Sandbox — for testing (uses sandbox.payfast.co.za)
   • Live — for real transactions (uses www.payfast.co.za)
6. Save your changes.

Step 4: Configure the ITN (Instant Transaction Notification) URL

PayFast uses ITN (Instant Transaction Notification) to notify your store when a payment is completed, failed, or cancelled. This is how WooCommerce knows to update an order from "Pending Payment" to "Processing" or "Completed."

• The ITN URL is typically set automatically by the WooCommerce plugin to your store's callback endpoint.
• In your PayFast merchant dashboard, you can also set a global ITN URL under Settings. The per-transaction URL sent by the WooCommerce plugin takes precedence over this global setting.
• Critical requirement: Your ITN URL must be publicly accessible over the internet. If your store is behind a firewall, maintenance mode, or basic authentication, PayFast cannot deliver notifications and your orders will remain stuck in "Pending Payment."

PayFast sends ITN notifications on ports 80, 8080, 8081, and 443. Ensure your server firewall allows incoming connections on at least one of these ports.

Step 5: Test with Sandbox Mode

Before accepting real payments, test the full checkout flow using PayFast's sandbox:

1. Create a sandbox account at sandbox.payfast.co.za if you have not already.
2. In the sandbox dashboard, note your sandbox Merchant ID, Merchant Key, and set a sandbox passphrase.
3. In your WooCommerce PayFast settings, switch to Sandbox mode and enter your sandbox credentials.
4. Place a test order on your store and complete the payment using the sandbox buyer credentials provided in your sandbox dashboard.
5. Verify that:
   • The order status changes from "Pending Payment" to "Processing" (or "Completed" for digital goods)
   • The customer receives an order confirmation email
   • The payment appears in your PayFast sandbox transaction history
6. Once testing is successful, switch back to Live mode and enter your live credentials.

Common sandbox pitfall: The sandbox only supports wallet payments (not real card transactions). The sandbox does not connect to external banking systems — all payments succeed automatically. This is normal test behaviour.

Yoco: Installation and Configuration

Yoco is a popular South African payment provider focused on card payments, offering a streamlined checkout experience.

Step 1: Install the Yoco Plugin

1. In your WordPress admin dashboard, navigate to Plugins → Add New.
2. Search for Yoco or Yoco Payments in the plugin directory.
3. Install and activate the official Yoco payment gateway plugin for WooCommerce.

If the plugin is not listed, check the Yoco developer portal or Yoco's official website for the latest installation instructions for your WordPress version.

Step 2: Obtain Your Yoco API Keys

1. Log in to your Yoco Business Portal.
2. Navigate to the Online Payments or API Keys section.
3. You will see two sets of keys:
   • Test keys (Public Key and Secret Key) — for testing without processing real payments
   • Live keys (Public Key and Secret Key) — for production transactions

Copy the appropriate keys for the mode you are configuring.

Step 3: Configure the Plugin

1. In your WordPress admin, navigate to WooCommerce → Settings → Payments.
2. Find Yoco in the payment methods list and click Manage (or Set up).
3. Enable the payment method.
4. Enter your API keys:
   • Public Key
   • Secret Key
5. Select the mode:
   • Test mode — uses your test API keys for testing
   • Live mode — uses your live API keys for real transactions
6. Save your changes.

Step 4: Test with Test Mode

1. Ensure the plugin is set to Test mode with your test API keys entered.
2. Place a test order on your store and complete the checkout.
3. Verify that:
   • The payment modal or redirect loads correctly
   • The order status updates appropriately after payment
   • A confirmation email is sent to the customer
4. Check your Yoco Business Portal for the test transaction.
5. Once satisfied, switch to Live mode and enter your live API keys.

WooCommerce Order Status Mapping

Understanding how payment gateway callbacks map to WooCommerce order statuses helps you diagnose problems:

If orders remain stuck in Pending Payment after the customer completes payment, the most likely cause is that the payment gateway's notification (ITN for PayFast, webhook for Yoco) is not reaching your store. See the troubleshooting section below.

Troubleshooting Common South African Checkout Issues

Orders Stuck in "Pending Payment"

This is the single most common issue with South African WooCommerce payment gateways.

Possible causes:

• Notification URL not reachable — your store's callback URL must be publicly accessible. Check that your site is not behind maintenance mode, password protection, or a firewall rule blocking the gateway's servers.
• Incorrect credentials — verify that your Merchant ID, Merchant Key, passphrase (PayFast) or API keys (Yoco) are entered correctly and match the mode you are using (sandbox vs. live).
• SSL issue — both gateways require your store to be served over HTTPS. Ensure your SSL certificate is valid and not expired.
• Plugin conflict — other WordPress plugins (security plugins, caching plugins, or firewall plugins) may block incoming webhook requests. Temporarily disable suspect plugins to test.

Diagnostic steps:

1. Check your WooCommerce order notes — each order has a notes section that logs payment gateway communication. Look for error messages.
2. For PayFast: Check the ITN log in your PayFast sandbox or live dashboard to see if notifications were sent and what response they received.
3. For Yoco: Check the webhook delivery status in your Yoco Business Portal.
4. Review your server's error logs (accessible in cPanel under Metrics → Errors) for any PHP errors occurring during the callback.

Sandbox Keys Left in Live Mode (or Vice Versa)

A surprisingly common mistake. Symptoms include:

• Payments do not appear in your live dashboard
• Customers see test environment branding during checkout
• All payments succeed without real money changing hands (sandbox behaviour in production)

Fix: Double-check that your plugin settings match your intended mode. Live credentials should only be used with live mode. Sandbox credentials should only be used with sandbox/test mode.

Payment Page Redirect Issues

If customers are redirected to the payment gateway but the page does not load or shows an error:

• Verify that your store URL and callback URLs are correct and use HTTPS.
• Check that the gateway's domain is not blocked by your browser extensions or network firewall.
• Ensure the payment amounts meet the gateway's minimum (PayFast requires a minimum of R5.00 per transaction).

Unsupported Card Types

Not all card types are accepted by all South African gateways. If customers report that their cards are declined:

• Confirm which card networks the gateway supports (Visa, Mastercard, American Express).
• Note that some international cards may not work with locally-focused gateways.
• Advise customers to try an alternative payment method if available.

When to Escalate

Different issues require different support channels:

• PayFast account, merchant settings, or transaction issues → Contact PayFast support directly through the PayFast website or your merchant dashboard.
• Yoco account, API keys, or transaction issues → Contact Yoco support through your Yoco Business Portal or the Yoco website.
• WooCommerce plugin bugs or compatibility issues → Check the plugin's support forum on wordpress.org or the plugin developer's issue tracker.
• Server-side errors, PHP issues, or hosting configuration → Open a support ticket with INNOVATECH GROUP. The hosting support team can help diagnose server-level issues affecting webhook delivery, SSL certificates, or PHP error logs.

Keep your payment gateway plugins updated to ensure compatibility with the latest WooCommerce and WordPress versions. Plugin updates often include security patches and bug fixes that can resolve checkout issues.