Custom Integration Guidelines

PayFast integration is based on very standard integration principles as used by a number of payment processing services on the internet viz. HTML form posting with callback verification/validation.

Our recommended integration for custom integration is the use of Website Payments in conjunction with Instant Transaction Notification (ITN).

For this, you will need the following pages on your site:

Sample code for these pages is available on this help site.

This page will have a hidden HTML form with a number of fields containing all the necessary information needed for PayFast to process the payment

The buyer will click on a “Confirm Order” or “Pay Now” button which will trigger the form being posted to PayFast.

The form must use variables as given here and a sample HTML form is given here.

This is a page on your site where the buyer is redirected from PayFast after successful payment.

This should just be a plain HTML page thanking the buyer for their purchase.

This page is specified by the return_url variable in the Confirm Page.

This is a page on your site where the buyer is redirected from PayFast after cancelling their payment.

This should be set to a page which will allow the buyer to purchase again and we recommend that you return the buyer to the Confirm Page.

This page is specified by the cancel_url variable in the Confirm Page.

This is the page which does all the “work” which is required (eg. updating the order in your database).

This page is “called” by our server directly after successful payment and before the user is redirected to the Success Page.

Note: This page is never viewed by the buyer and any HTML output from it is inconsequential.

On this page, the following should be done:

1. Receive the data posted by PayFast
2. Perform security checks
   • Verify the source IP address belongs to PayFast
   • Verify the data received is valid
3. Verify that the order hasn't been processed already
4. Process the order
   • Update the status to paid
   • Email the buyer confirming payment

This page is specified by the notify_url variable in the Confirm Page.

Data will be POSTed to the notify page by PayFast.

The variables which are posted are as specified here.

You need to verify the the page was called by our server and not from somewhere else.

This is done by ensuring that the source IP is one of the following hostnames:

• www.payfast.co.za
• w1w.payfast.co.za
• w2w.payfast.co.za
• sandbox.payfast.co.za

The data is verified by using PayFast's validation service as detailed below:

• Post the data as received from PayFast to https://www.payfast.co.za/eng/query/validate
• If the data is valid, VALID will be returned
• If the data is not valud, INVALID will be returned

The PayFast engine regards an ITN callback as successful if it receives an “HTTP 200 OK” response from the notify page.

If it doesn't receive this, it will keep trying until it is successful or it reaches the “maximum tries” limit.

For whatever reason, the Notify page may be called by PayFast, but be deemed as having been unsuccessful, even though it wasn't and will be retried.

For this reason, you need to ensure that an order on your side hasn't been processed already before you process it.

This can be done by:

• Using the m_payment_id variable to verify status of your internal order
• Using the pf_payment_id variable to ensure that this notification hasn't been eceived already

Once you have ensured that the call is genuine and that the order has yet to be processed, you can process your order as needed.

This would probably include:

• updating the status of the order to “paid”, and
• emailing the buyer to confirm payment, or
• delivering the digital download