PayFast

Collect payments with PayFast

PAYFAST posts a signed payment request to PayFast’s hosted page. The payer completes the payment there, and PayFast confirms it with an ITN (Instant Transaction Notification) that is signature-checked before anything is credited.

Available to ISPs in South Africa (ZA), alongside Paystack, PayPal, and DPO.

Before you start

1. Complete PayFast merchant onboarding in an account owned by the ISP.
2. In the PayFast dashboard open Settings → Integration and collect the merchant ID and merchant key.
3. Set a passphrase in the same place, and be ready to enter the identical value here — see the warning below.
4. Plan the walled garden: the payer’s browser must reach www.payfast.co.za, so a Hotspot subscriber who is not yet online cannot pay unless PayFast is reachable pre-authentication.

Configure the gateway

1. Open Settings → Payments → PayFast

   Select PayFast from the payment marketplace.

2. Enter the merchant ID and merchant key

   Both are required, and both come from PayFast dashboard → Settings → Integration.

3. Enter the passphrase

   Passphrase is optional in the form — PayFast allows unsigned merchants — but it is strongly recommended. It must be character-for-character identical to the passphrase saved in your PayFast dashboard.

4. Register the ITN, return, and cancel URLs

   See Callback URLs below.

5. Run a controlled test payment

   Pay a small amount from the captive portal on an unauthenticated device and confirm the payment reaches the ledger.

Caution

A passphrase that differs from PayFast’s — including a stray space — makes every signature mismatch. Payments are then rejected, or notifications are discarded, in a way that looks like an intermittent gateway fault rather than a configuration error. Set it on both sides at the same time, or leave it blank on both.

Credentials

Field	Required	Notes
Merchant ID	Yes	PayFast dashboard → Settings → Integration.
Merchant key	Yes	Same place.
Passphrase	No	Secret. Signs payment data and validates notifications. Must match PayFast exactly.

The merchant ID and key gate the switch; the passphrase does not, which is exactly why a mismatch is easy to ship.

Callback URLs

Name	Path
Notify URL (ITN)	https://<your-host>/api/payments/payfast/notify
Return URL	https://<your-host>/tenant/payfast/return
Cancel URL	https://<your-host>/tenant/payfast/cancel

Set all three in the PayFast dashboard, and confirm the notify URL is publicly reachable — it is what completes a payment.

What the payer must provide

Whatever PayFast’s page asks for — card, instant EFT, or another method enabled on your account. The amount, reference, and signature are fixed before the payer arrives.

Note

PayFast is always live here. There is no sandbox switch on this form, so test with a small real amount rather than with sandbox credentials.

How a payment completes

1. Signed redirect

   Centipid Billing builds the payment fields in PayFast’s canonical order, signs them with your passphrase, and redirects the payer to PayFast with the signature attached.

2. Payment

   The payer completes the payment on PayFast’s page.

3. Confirmation

   PayFast posts the ITN. Its signature is recomputed with your passphrase and compared; only a matching notification records a payment and applies the package.

Troubleshooting

Symptom	What it means	What to do
“Payment failed: PayFast is not fully configured. Please add your merchant ID and key.”	One of the two required fields is missing.	Complete both in Settings → Payments.
PayFast’s page rejects the request as an invalid signature	The passphrase here does not match the one in the PayFast dashboard.	Re-enter it on both sides, watching for trailing spaces.
Payments complete at PayFast, ledger stays empty	ITNs are being discarded — a passphrase mismatch, or a notify URL that is not publicly reachable.	Check both, then re-test with a small payment.
The payment page never loads on a Hotspot device	The walled garden does not allow PayFast.	Allow www.payfast.co.za pre-authentication — see Captive device cannot reach checkout.

For every gateway’s fields in one place, see the credential reference.