ReCurr Tutorial Series — Part 3: Configuring PayFast

Welcome back to the ReCurr tutorial series. In Part 2 we created a subscription product. Now we’ll configure the PayFast payment gateway so your customers can pay.

PayFast is a South African payment gateway that handles credit and debit card processing. ReCurr uses PayFast’s Ad Hoc tokenization to securely store customer card details for automatic recurring payments — no card numbers are stored on your site.

From ReCurr 2.8.8, ReCurr’s requests to PayFast’s API and its payment forms are signed by PayFast’s official PHP library (payfast-php-sdk), which is bundled inside ReCurr — there is nothing extra to install.

Before You Begin

Make sure you have:

Completed Tutorial 1: Getting Started and Tutorial 2: Creating Subscription Products
A PayFast merchant account (sign up at payfast.co.za if you don’t have one)
Your site is running on HTTPS (SSL certificate installed)

How PayFast Works with ReCurr

Here’s a quick overview of the payment flow:

Customer checks out and is redirected to PayFast’s secure payment page
Customer enters their card details on PayFast (not on your site)
PayFast processes the payment and tokenizes the card
PayFast sends a notification (ITN) back to your site confirming payment
ReCurr activates the subscription and stores the token for future renewals
For subsequent renewals, ReCurr uses the stored token to charge the card automatically — no customer action needed

Step 1: Get Your PayFast Credentials

1a. Find Your Merchant ID and Merchant Key

Go to Settings in your PayFast dashboard
Navigate to Developer Settings
Note down your Merchant ID and Merchant Key

Screenshot 1: PayFast dashboard showing where to find Merchant ID and Merchant Key.

1b. Set Up Your Passphrase

The passphrase adds an extra layer of security to payment signatures.

In your PayFast account settings, look for the Passphrase or Salt Passphrase field
Set a passphrase (or note the existing one)
You will need to enter this same passphrase in ReCurr’s gateway settings

Screenshot 2: PayFast account settings showing the Passphrase field.

Important: The passphrase in ReCurr must match the passphrase in your PayFast account exactly. If they don’t match, payments will fail with a signature error.

Step 2: Configure the Gateway in WooCommerce

In your WordPress dashboard, go to WooCommerce > Settings
Click the Payments tab
Find PayFast Subscriptions in the list of payment gateways
Click Manage (or the toggle/gateway name) to open the settings

Screenshot 3: WooCommerce > Settings > Payments tab with “PayFast Subscriptions” visible in the gateway list.

Step 3: Gateway Settings

You will see the following settings fields. Let’s go through each one:

Enable/Disable

Tick Enable Payfast Subscriptions to activate the gateway
If unticked, the gateway will not appear at checkout

Screenshot 4: The Enable/Disable checkbox at the top of the gateway settings.

Title

This is the payment method name your customers see at checkout
Default: Credit/Debit Card (Recurring)
You can change this to something like “Credit/Debit Card” or “Pay with Card”

Description

This text appears below the payment method at checkout
Default: Pay securely. Your card will be saved for automatic renewals.
You can customise this to suit your brand

Screenshot 5: Title and Description fields with their default values.

Merchant ID

Enter your Merchant ID from Step 1a
This is required — the gateway will not appear at checkout without it

Merchant Key

Enter your Merchant Key from Step 1a
This is required — the gateway will not appear at checkout without it

Screenshot 6: Merchant ID and Merchant Key fields (with values entered or placeholder text visible).

Passphrase

Enter the passphrase that matches your PayFast account
This field is displayed as a password field (dots instead of text)
If your PayFast account does not have a passphrase set, leave this blank

Screenshot 7: Passphrase field (password type).

Test Mode

Tick Enable Test Mode to use the PayFast sandbox for testing
When Test Mode is enabled: payments go to sandbox.payfast.co.za (no real money is charged)
When Test Mode is disabled: payments go to www.payfast.co.za (real transactions)

Screenshot 8: Test Mode checkbox.

Save Your Settings

Click Save changes at the bottom of the page.

Screenshot 9: Save changes button at the bottom of the gateway settings page.

Step 4: Understanding Sandbox vs Live

	Sandbox (Test Mode ON)	Live (Test Mode OFF)
Payment URL	sandbox.payfast.co.za	www.payfast.co.za
Renewal API	sandbox.payfast.co.za	api.payfast.co.za
Real money charged	No	Yes
Use for	Testing your setup	Production / real customers

Sandbox Testing

PayFast provides a separate sandbox environment for testing. To use it:

Register for a sandbox account at sandbox.payfast.co.za
Use your sandbox Merchant ID and Merchant Key in the gateway settings
Enable Test Mode
Process a test transaction to verify everything works

Once testing is complete:

Replace the sandbox credentials with your live Merchant ID and Merchant Key
Update the Passphrase to match your live PayFast account
Untick Test Mode
Save changes

Important: Never go live with sandbox credentials, and never use live credentials with Test Mode enabled. The credentials must match the environment.

Screenshot 10: A comparison showing Test Mode ticked (sandbox) vs unticked (live) — or just the checkbox in its final live state.

Step 5: Verify the ITN Callback URL

The ITN (Instant Transaction Notification) is how PayFast tells your site that a payment was successful. ReCurr generates this URL automatically — you don’t need to configure it manually.

Your ITN callback URL will be one of:

https://yoursite.com/wc-api/crb_payfast/

https://yoursite.com/?wc-api=crb_payfast

The exact format depends on your WordPress permalink settings.

Verify It Works

To confirm PayFast can reach your callback URL:

Make sure your site is publicly accessible (not behind a password or maintenance mode)
Check that no security plugins are blocking incoming POST requests to the callback URL
If you use a firewall (e.g., Cloudflare, Wordfence), make sure PayFast’s servers are not blocked

PayFast’s servers need to reach this URL to confirm payments. If the callback is blocked, payments will process on PayFast’s side but your site won’t know about it — orders will stay as “pending” and subscriptions won’t activate.

Step 6: Test a Transaction

With sandbox/test mode enabled, run through a full test:

Go to your store frontend and add a subscription product to the cart
Proceed to checkout
Select Credit/Debit Card (Recurring) as the payment method
Click Proceed to PayFast
You will be redirected to PayFast’s sandbox payment page
Enter test card details and complete the payment
You will be redirected back to your store’s thank you page

What to Check After the Test

Order status should be Processing or Completed (go to WooCommerce > Orders)
Subscription status should be Active (go to Subscriptions > All Subscriptions)
The subscription should have a stored payment token (visible in the subscription detail view)
In your PayFast sandbox dashboard, the payment in Transactions (and the new card in Tokenization, where your account shows that list) carries the WooCommerce order number as its Payment ID (v2.8.4)
PayFast’s payment confirmation for you (“You received R… from …”) arrives at the address set in your PayFast sandbox account under Settings → Integration → Email Confirmation, not at the customer’s address (v2.8.8). The customer receives PayFast’s own receipt.

Screenshot 11: A successful test order showing Processing/Completed status in WooCommerce Orders.

Screenshot 12: The subscription in All Subscriptions showing Active status after the test payment.

If the order stays as “Pending”, the ITN callback may not be reaching your site. Check ReCurr’s log lines under WooCommerce → Status → Logs (source “recurr”) for error messages (v2.8.6 — before 2.8.6 they went to the WordPress debug log). Most of them appear only while WP_DEBUG is switched on.

Changing a card on an existing subscription (v2.7.26): Update Card in My Account runs a R5.00 card registration, credited in full to the customer’s account (it comes off their next payment), and this works the same in sandbox and live. Once the new card is stored, ReCurr cancels the card it replaced at PayFast, so it can no longer be charged from your PayFast dashboard (v2.8.8). Update Card is offered on card subscriptions only — not on Manual EFT subscriptions (v2.8.8). PayFast’s free card-update page is an opt-in from 2.7.26 and is not provided for the sandbox at all. Both routes are described in Tutorial 6.

Step 7: Go Live

Once you’ve confirmed everything works in sandbox mode:

Go to WooCommerce > Settings > Payments > PayFast Subscriptions
Replace the sandbox Merchant ID with your live Merchant ID
Replace the sandbox Merchant Key with your live Merchant Key
Update the Passphrase to match your live PayFast account
Untick Test Mode
Click Save changes
In your PayFast dashboard, open Settings → Payment Methods and confirm Credit Card → Minimum amount reads R5.00 (v2.7.26). That is PayFast’s default. ReCurr registers a new card with a R5.00 charge, and PayFast refuses any payment below your own minimum. Visa and Mastercard debit and cheque cards are processed under the Credit Card method, so that is the figure that counts.
Still in your PayFast dashboard, open Settings → Integration → Email Confirmation and set it as you want it (v2.8.8). PayFast sends its payment confirmation for you (“You received R… from …”) and its refund notices as set there: ReCurr’s payment forms no longer name an address for it.

Your store is now ready to accept real payments.

Screenshot 13: Final gateway settings configured for live mode (with Test Mode unticked). Blur or redact the Merchant ID and Key for security.

Troubleshooting

Gateway Not Showing at Checkout

Confirm the gateway is enabled (checkbox ticked)
Confirm Merchant ID and Merchant Key are entered (both are required)
Confirm the cart contains a subscription product — the PayFast Subscriptions gateway only appears when a subscription product is in the cart

Payment Completes on PayFast but Order Stays Pending

The ITN callback is not reaching your site
Check that your site is accessible from the internet (not localhost or behind a password)
Check for security plugins or firewalls blocking POST requests
Review ReCurr’s log lines under WooCommerce → Status → Logs (source “recurr”) for ITN-related errors (v2.8.6)
On a ReCurr version before 2.8.6, a payment by a customer whose name or email address contains an apostrophe, a quotation mark or a backslash (for example O’Brien) was taken by PayFast but not recorded. Update ReCurr, then find and repeat those payments as the 2.8.6 release notes describe

Signature Mismatch Errors

The passphrase in ReCurr does not match your PayFast account
Double-check for trailing spaces or incorrect characters
Remember: sandbox and live accounts may have different passphrases
(v2.8.8) A log line “PayFast form: signed by ReCurr, not the PayFast SDK (…)” under WooCommerce → Status → Logs (source “recurr”) is not an error. PayFast’s library cannot sign a form the way PayFast’s documentation does when the passphrase holds a character other than letters, digits, “-“, “_” and “.”, or when no passphrase is set; ReCurr then signs it as before, and the payment goes ahead

“400 Bad Request — The subscription amount is outside the limits” (v2.7.26)

PayFast shows this, before the customer sees a card form, when the amount is below a minimum set in your PayFast account. It is most often met on Update Card, which charges R5.00.

In the PayFast dashboard go to Settings → Payment Methods → Credit Card and set Minimum amount to R5.00 (PayFast’s default)
If you want to keep a higher minimum, raise ReCurr’s card registration amount to match with the crb_card_registration_amount filter — see Tutorial 8. The whole amount is credited back to the customer
A subscription product priced below your minimum will be refused at checkout in the same way

Renewal Payments Failing

Verify the subscription has a valid payment token stored
If the token was created in sandbox mode, it will not work in live mode — the customer must re-subscribe through live checkout
Check ReCurr’s log lines under WooCommerce → Status → Logs (source “recurr”) for API response errors (v2.8.6)

What’s Next?

Your PayFast gateway is configured and tested. Customers can now subscribe and pay with their credit or debit cards.

Up next: Tutorial 4: Managing Subscriptions — Admin dashboard overview, viewing subscription details, and managing subscription statuses.

Quick Checklist

[ ] PayFast merchant account credentials obtained (Merchant ID, Merchant Key, Passphrase)
[ ] Gateway enabled in WooCommerce > Settings > Payments
[ ] Title and Description customised (optional)
[ ] Merchant ID entered
[ ] Merchant Key entered
[ ] Passphrase entered (matching PayFast account)
[ ] Test Mode set appropriately (sandbox for testing, off for live)
[ ] Test transaction completed successfully in sandbox
[ ] Order status verified after test payment
[ ] Subscription status verified after test payment
[ ] Live credentials entered and Test Mode disabled for production
[ ] PayFast Credit Card → Minimum amount confirmed at R5.00 (PayFast dashboard > Settings > Payment Methods)

Need Help?

Email: [email protected]
Support Hours: Monday to Thursday, 9:00 AM – 4:00 PM (SAST)
Friday, 09:00 AM – 12:00 PM (SAST)
Website: cyberdummies.co.za/recurr

This is Part 3 of the ReCurr Tutorial Series. All tutorials are available at cyberdummies.co.za/recurr.

Tutorial	Topic
1. Getting Started	Install, activate, and initial configuration
2. Creating Subscription Products	Billing periods, pricing, and discounts
3. Configuring PayFast	Gateway credentials, sandbox vs live, ITN setup (you are here)
4. Managing Subscriptions	Admin dashboard, status management, details
5. Manual EFT Subscriptions	Corporate clients paying via bank transfer
6. Customer Experience	Checkout flow and My Account subscription management
7. Invoicing	Invoice generation, PDF attachments, email delivery
8. Settings Reference	Complete reference of all available settings

We Are Here To Help!



Office

Queenswood
Pretoria
SA



Hours

M-T: 9am – 4pm
F: 9am – 12pm
S-S: Closed



Email Us

[email protected]
[email protected]



Legalities



Let's Chat

+27 66 3417545