Payfast integration: A developer's guide for SA e-commerce

Payfast is the payment rail most Cape Town e-commerce stores lean on — it's reliable, locally trusted, and supports card, Instant EFT, and Bob Pay out of the box. But the documentation is thinner than the international equivalents, and the first integration always takes longer than expected. Here's the playbook we use for every Payfast build.

Sandbox first, production last. Payfast's sandbox environment is a faithful replica of production, including webhook delivery. Wire the full ITN (Instant Transaction Notification) flow in sandbox before you ever touch production keys. The webhook signature is calculated as an MD5 of a specific param string; getting this wrong in production means a customer pays and your dashboard never updates. We use ngrok to expose a local dev endpoint to Payfast's sandbox for the entire integration phase.

ITN validation is non-negotiable. Every ITN Payfast sends must be validated by re-computing the signature server-side using your passphrase. Never update order status based on the webhook body alone — a spoofed webhook will create phantom orders. Our pattern: receive webhook → recompute signature → if mismatch, log + drop → if match, fetch the order, verify the amount matches the ITN m_amount field to the cent, then mark as paid. This single check has caught three fraud attempts this year.

Reconciliation is where the real bugs live. Payfast settles daily to your bank account, but the settlement file lumps refunds, fees, and successful charges into a single amount. If your dashboard doesn't reconcile, you'll only find out at month-end when the books don't close. We built a nightly job that pulls the Payfast settlement report via SFTP, matches each line to an internal transaction, and flags any unmatched amounts into a Slack channel. Mother City Logistics found R8,400 of unrecorded refunds in the first week of running it.

Keep the raw payload. When Payfast support asks "can you send the original ITN for order ORD-8842?", you want to be able to paste the JSON in five seconds, not go digging through archived logs. Every webhook we receive gets stored in full in a payment_webhooks table with a 5-year retention. It's saved us hours on dispute resolution and made SARS audits noticeably less painful.