Accepting Payments with Payfast

The Payfast add-on lets your customers pay through Payfast, a payment service for South African businesses. Customers are sent to Payfast's own payment page, where they can pay by card, instant EFT and the other ways Payfast offers, then come back to your site.

Payfast only takes payments in South African Rand, so set your store currency in Sunshine > Settings to South African Rand (ZAR).

Installing the Add-on

If you have a Pro, Plus or Basic license, go to Sunshine > Add-ons and turn on Payfast. Sunshine downloads it, adds its license key and activates it for you. The steps are in Install add-ons for Pro/Plus/Basic licenses.

If you bought the add-on on its own, follow Install individually purchased add-on, then enter its key in Sunshine > Settings > Licenses. See License Keys if the key won't activate.

Getting Your Merchant ID, Merchant Key and Passphrase

Sunshine needs three things from your Payfast account.

1. Log in to your Payfast account
2. Go to Settings > Developer Settings
3. Copy your Merchant ID and Merchant Key
4. Find Salt Passphrase. If it's empty, click Edit and make one up. Use letters and numbers, like a strong password
5. Copy the passphrase exactly as it's saved in Payfast

The passphrase in Sunshine has to match the one in Payfast letter for letter. If they don't match, Payfast turns the payment away before the customer can pay.

Setting Up Payfast in Sunshine

1. Go to Sunshine > Settings > Payments
2. Turn on Payfast with the toggle, then click Configure
3. Set Mode to Live
4. Paste your Merchant ID, Merchant Key and passphrase into Live Merchant ID, Live Merchant Key and Live Passphrase
5. Click Save Changes

Here is every setting on the Payfast screen:

• Name: What customers see as the payment option at checkout. Leave it blank to show "Payfast".
• Description: The short line under the name at checkout. Leave it blank to show "Pay with credit card".
• Fees: Add an extra charge when customers pay this way, as a percentage or a fixed amount, with a Fee Name and Fee Amount. See Payment Gateway Fees.
• Mode: Live takes real payments. Test uses the Payfast sandbox, where no real money moves.
• Live Merchant ID, Live Merchant Key and Live Passphrase: From your real Payfast account. Shown when Mode is Live.
• Test Merchant ID, Test Merchant Key and Test Passphrase: From your Payfast sandbox account. Shown when Mode is Test.

There's nothing to set up in Payfast for payment notices. Sunshine tells Payfast where to send them with every payment.

Why the passphrase matters

Payfast lets an account work without a passphrase, but set one anyway. Two things depend on it.

After a customer pays, Payfast sends a payment notice to your site, and that notice is what marks the order paid. Sometimes the notice never arrives, usually because a firewall or security plugin blocked it. With a passphrase set, Sunshine looks the payment up in your Payfast transaction history when the customer comes back to your site, and finishes the order once it finds the full payment there. Without a passphrase, Sunshine can't look it up, so an order whose notice was blocked stays Pending Payment until you mark it paid yourself.

Refunds from the order screen also need the passphrase. Payfast doesn't allow them without one.

Testing with the Payfast Sandbox

The sandbox is a practice version of Payfast with its own Merchant ID, Merchant Key and passphrase. Your live details won't work in Test mode.

1. Go to sandbox.payfast.co.za and sign in to your sandbox account
2. Copy the sandbox Merchant ID and Merchant Key, and set a passphrase for the sandbox
3. In Sunshine, set Mode to Test and paste them into Test Merchant ID, Test Merchant Key and Test Passphrase
4. Place an order and pay on the sandbox payment page

Set Mode back to Live when you're done testing.

What Customers See at Checkout

When a customer chooses Payfast on the payment step, there is no card form on your site. The button reads Continue to payment details. Clicking it shows a short "Redirecting to Payfast..." page, then sends them to Payfast to pay.

Payfast can't take a payment under R5.00. If the order total is smaller than that, the customer sees "Payfast can't take payments under R5.00. Add more to your order or choose another way to pay." at checkout, before they are sent anywhere.

What Happens After Payment

When the customer finishes paying, Payfast sends them back to their receipt page on your site. Payfast also sends your site a payment notice. Sunshine checks that notice with Payfast and only marks the order paid if:

• Payfast confirms it really sent the notice
• The payment went to your Payfast account
• The payment is complete
• The amount matches the order total

Then the order is marked New and the receipt email is sent. The Payfast payment ID is saved in the Payfast tab on the order screen, with a link to the payment in your Payfast dashboard.

If the customer gets back before the notice arrives, their receipt page shows: "Thank you! Your payment is being confirmed by Payfast. Your order will show as paid once Payfast confirms it." The order finishes on its own as soon as Payfast confirms the payment, and the customer gets the receipt email then.

When the customer cancels

If the customer clicks to cancel on the Payfast page, they come back to your checkout page with the message "Payment has been cancelled." They can try again with Payfast or choose another payment method. The order they left behind stays Pending Payment with a note that they cancelled. If they did pay on Payfast after all, that payment still finishes it.

When a payment is declined or doesn't match

If Payfast says the payment was declined or cancelled, the order stays Pending Payment and a note is added with the status Payfast sent. If the payment doesn't match the order, for example the amount is different or it went to another Payfast account, the order also stays unpaid and the note says why. Check the payment in your Payfast dashboard before marking an order like this paid.

Refunds

You can refund a Payfast payment from your WordPress admin, in full or in part.

1. Open the order in Sunshine > Orders
2. In the Order Actions panel, choose Refund payment in Payfast
3. Leave Full refund ticked to refund everything that's left, or untick it and enter the amount
4. Optionally type a Reason for refund. Payfast keeps it with the refund, and Sunshine saves it on the order
5. Leave Notify customer via email ticked if you want Payfast to email the customer about the refund
6. Click Apply

A full refund marks the order Refunded. A partial refund is recorded on the order and comes off its total, but the order keeps its status. You can make more partial refunds later, up to what's left.

The refund option only shows on orders that have a Payfast payment ID, which is saved when Payfast confirms the payment.

Refunds that have to be done in Payfast

Payfast decides how each payment can be refunded. For some payments, such as instant EFT, Payfast can only pay the refund into the customer's bank account, which needs their bank details. Sunshine can't do these. You'll see "Payfast can only pay this refund into the customer's bank account, which needs their bank details. You can do this refund in your Payfast dashboard." Do the refund in your Payfast dashboard, then mark the order Refunded in Sunshine.

If any other refund doesn't go through, Sunshine shows Payfast's reason at the top of the order screen and adds it to the order notes.

Admin Payment Problem Email

Sunshine can email you when a Payfast payment can't be accepted for an order, so you hear about it without checking each order. This email is off until you turn it on.

1. Go to Sunshine > Settings > Email and open Admin Payment Problem
2. Tick Enabled
3. Add one or more addresses in Recipient(s), or leave it empty to send to your site's admin email
4. Under Send when, choose what to hear about:
5. A payment didn't match the order: the amount was wrong, the payment went to another account, or Payfast lists the payment but it can't finish the order. Ticked by default
6. A payment was declined or cancelled at the payment service: Payfast said the payment was declined or cancelled. Not ticked by default

See Emails for all the options.

Troubleshooting

Payfast shows a signature error instead of the payment page

The passphrase in Sunshine doesn't match the one in Payfast. Copy it again from Settings > Developer Settings in Payfast and paste it into the passphrase field for the mode you're using. If you don't use a passphrase in Payfast, leave the field in Sunshine empty.

Also check that live details are in the Live fields, sandbox details are in the Test fields, and Mode matches.

Orders stay on Pending Payment after customers pay

Payfast's payment notice isn't reaching your site, or your site can't reach Payfast to check it. Common causes:

• A security plugin, firewall or Cloudflare setting is blocking requests from Payfast
• The site is in maintenance mode, password protected, or on a local computer that Payfast can't reach
• Your web host blocks your site from connecting to other servers

Set a passphrase in the Payfast settings so Sunshine can find these payments in your Payfast transaction history. For an order that is already stuck, check your Payfast dashboard. If the full payment is there, open the order and change its status to New. This finishes the order and sends the customer their receipt.

"Payfast can't take payments under R5.00"

The order total is below Payfast's minimum. The customer needs to add more to their order or use another payment method.

The refund option says the Payfast API needs the merchant ID and passphrase

Add your passphrase to the Payfast settings in Sunshine. Payfast doesn't allow refunds from outside its dashboard without one.

If you need more detail about what happened with a payment, turn on logging and try another test order.