+27 66 341 7545 (Whatsapp only) [email protected]

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:

How PayFast Works with ReCurr

Here’s a quick overview of the payment flow:

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

Step 1: Get Your PayFast Credentials

Log in to your PayFast merchant account at payfast.co.za.

1a. Find Your Merchant ID and Merchant Key

  1. Go to Settings in your PayFast dashboard
  2. Navigate to Developer Settings
  3. 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.

  1. In your PayFast account settings, look for the Passphrase or Salt Passphrase field
  2. Set a passphrase (or note the existing one)
  3. 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

  1. In your WordPress dashboard, go to WooCommerce > Settings
  2. Click the Payments tab
  3. Find PayFast Subscriptions in the list of payment gateways
  4. 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:

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

Once testing is complete:

  1. Replace the sandbox credentials with your live Merchant ID and Merchant Key
  2. Update the Passphrase to match your live PayFast account
  3. Untick Test Mode
  4. 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/

or

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:

  1. Make sure your site is publicly accessible (not behind a password or maintenance mode)
  2. Check that no security plugins are blocking incoming POST requests to the callback URL
  3. 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:

  1. Go to your store frontend and add a subscription product to the cart
  2. Proceed to checkout
  3. Select Credit/Debit Card (Recurring) as the payment method
  4. Click Proceed to PayFast
  5. You will be redirected to PayFast’s sandbox payment page
  6. Enter test card details and complete the payment
  7. 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:

  1. Go to WooCommerce > Settings > Payments > PayFast Subscriptions
  2. Replace the sandbox Merchant ID with your live Merchant ID
  3. Replace the sandbox Merchant Key with your live Merchant Key
  4. Update the Passphrase to match your live PayFast account
  5. Untick Test Mode
  6. Click Save changes
  7. 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.
  8. 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?

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

Terms of Use
Privacy Policy
Cookie Policy
SLAgreement
ReCurr License

Let's Chat

+27 66 3417545