PayFast Integration Guide for South African Developers
A practical, no-nonsense guide to integrating PayFast into your Next.js application. Covers ITN webhooks, signature verification, IP whitelisting, and the gotchas.
Before You Start
PayFast is the dominant payment gateway in South Africa. You will need a merchant account, your Merchant ID, Merchant Key, Passphrase, and a publicly accessible webhook endpoint.
The Payment Flow
PayFast uses a redirect-based flow. Your server generates a signed form, redirects the customer to PayFast, and PayFast sends an ITN POST to your webhook.
The critical point: the ITN is the source of truth, not the redirect.
Building the Checkout Endpoint
Your checkout API route creates a pending order, builds the PayFast parameter string, generates an MD5 signature, and returns parameters for the frontend.
The ITN Webhook Handler
You must verify the signature, verify the source IP, verify the payment amount, check the payment status, and handle idempotency.
Common Gotchas
- URL encoding: PayFast uses + for spaces, not %20
- Sandbox behaves differently from production
- Next.js body parsing can interfere with signature verification
- Decimal precision matters (99.90 not 99.9)
- Passphrase is required for live accounts but optional for sandbox
Production Checklist
- Signature verification working with passphrase
- IP whitelist enforced
- Amount verification
- Idempotency check
- HTTPS configured
- Error notifications set up
- All credentials in environment variables