Integration Guide
Overview
This integration guide details how a merchant should go about integrating with PayFast.
For the purposes of this guide, we'll make reference to the example of Widgets CC wanted to sell widgets via their site at www.widgets.co.za using PayFast. The owner of the company is John Doe and his email address is john@widgets.co.za. The main email address of the company is info@widgets.co.za and any support queries are sent to support@widgets.co.za.
Preparation
Register
In order to use PayFast to process transactions from your website, you will first need to register.
Note: At registration you can choose either a Basic, Personal, Premier or Business account. The differences between the account types are detailed here. For the purposes of this guide, we are assuming you want to register a Business account.
Register with your details as the primary person responsible for the account at your company (This could be in your capacity as business owner, financial manager etc.). In our example, this would mean that John Doe would register as John Doe using the main company email address of info@widgets.co.za.
Account Identifiers
When redirecting users to PayFast for payment fulfillment, you will need to send various pieces of information including identifiers for your Business account. These can be obtained by logging into your account and going to the Integration page under My Account.
At a minimum, you will need to know your Merchant ID and Merchant Key.
API Documentation
The PayFast engine is basically a "black box" which processes a purchaser's payment. The API Documentation provides the details of the inputs and outputs of this box.
These details are available on the Website Payments Variables and PDT & ITN Variables pages.
Development
Now that you have a Business account and have the necessary information and documentation, the proper integration can start.
Modify Payment Process
In order to redirect users to PayFast for payment you will need to modify your payment process to redirect to our site with the required data for fulfillment during your checkout/payment process.
All the information that is required to be posted to us from your system is available in the API Documentation.
Security
The address to where you post the information is secured by High Strength 256 bit Encryption. As an extra precaution, we have implemented a Security Signature which it is advisable that you implement on your system.
This signature is an MD5 Hash of all the variables submitted. This hash must be calculated by your system and submitted to PayFast along with the posted variables. The PayFast engine will calculate its own version of the security signature based on the submitted variables and compare this with your submitted signature. The two need to be the same in order for the transaction to proceed.
Auto Return
You will need to provide a landing page where we can return the user to, once payment has been successfully received from the user. The redirection to this page is known as "auto return" and is governed by the value of return_url.
Since this is a browser based redirection, no information will be posted to this page to give you feedback as to the success or failure of the transaction.
For feedback on the status of the transaction, you need to have enabled either Payment Data Transfer (PDT) or Instant Transaction Notification (ITN) on your account.
Payment Data Transfer (PDT)
PDT works in conjuntion with auto return, such that if you have enabled PDT on your account, a transaction token will be appended to the return_url.
This token is then used, along with your PDT key, to query PayFast for the status and details of the transaction.
Click here for more information on PDT as well as sample code.
Security
PDT is secured through the following means:
- The merchant must use both the transaction token returned to them as well as an authentication token (PDT key) to retrieve transaction information from PayFast. Provided that the merchant accesses the secure version of PDT, the authentication token is never communicated across an unsecured connection and basically acts as a "shared secret" key.
- The merchant must make a connection to the PayFast servers (rather than the other way around). This increases security as it ensures that you are obtaining the information from the correct source, rather than trusting information that was rather sent to you without being able to verify the source of that information.
Instant Transaction Notification (ITN)
Auto Return (and by extension PDT) is the standard redirection of the user's browser, and as such, is subject to unforeseen interruptions. The user could close their browser before being redirected to the return_url, the user's Internet connection could be dropped etc.
As such, Auto Return and PDT are not a reliable means of notification about the status of a transaction. Instant Transaction Notification is not subject to these sorts of interruptions and as such, is the preferred choice of notification to be used by merchants.
ITN is a completely independent callback (independant of the user, their connection and their browser) which is initiated directly by the PayFast engine to the merchant's site. This notification is a separate connection made by the PayFast server to the notify_url as specified by the merchant to provide feedback on the success of a user's payment.
This notification gives the merchant the same information as can be retrieved with PDT but is far more resilient to any interruption as it incorporates queuing, acknowledgement and repeated attempts failing non-acknowledgement.
ITN is also far more secure as it cannot be spoofed by a would be attacker as the IP address from which it will originate can be limited to the PayFast servers IP address (or range of addresses). A valid ITN cannot originate from any address other than those used by our servers.
Click here for more information on ITN as well as sample code.
Security
ITN is secured through the following means:
- Along with the other information, an ITN to the merchant site will also include a security signature as detailed previously. This signature should be independently generated by the merchant and compared with the submitted signature to ensure data integrity.
- Since this is an independent connection between PayFast and the merchant, the merchant can perform validation on the source IP address of the connection. It must be the IP Address (or belong to the range of IP addresses) specified in the Appendix as belonging to PayFast.
- The merchant can validate that the information is correct and has originated from PayFast by performing a secure post to PayFast requesting a validation of the received data. PayFast will validate the data for accuracy and provide the appropriate response.
Testing Strategy
Overview
Testing on the PayFast system follows a sandbox strategy (See Wikipedia entry), which is to say that there is an exact code duplicate of the production site available in a sandbox. Any transactions made or actions performed on this system are isolated from the main production environment and as such it provides a realistic, but inconsequential environment where merchants can test their system before going live.
System
Registration
Generic sandbox credentials are available with which you can test standard integration and PDT. These are detailed below:
Merchant account:
- Username: sbtm01@payfast.co.za
- Account Name: Sandbox Text
- Merchant ID: 10000100
- Merchant Key: 46f0cd694581a
- PDT: Enabled
- PDT Key: 0a1e2e10-03a7-4928-af8a-fbdfdfe31d43
- ITN: Disabled (Use notify_url to test ITN)
User account:
- Username: sbtu01@payfast.co.za
- Password: clientpass
To test ITN, simply set the notify_url variable when posting to the sandbox. On the live site, you can set notify_url globally on your account such that it doesn't have to be set with each call to PayFast if you would prefer.
Note: ITN in the sandbox will not be retried as on the production site.
Sandbox Limitations
The sandbox does not make any connections to external systems and any such functionality which would require it to has beed "stubbed" for the sandbox. Most significantly this means that all payments will result in successful transactions.
Registration has been disabled in the sandbox. Please use the generic sandbox credentials detailed above for testing.
Testing
Sandbox Test Transactions (Non-Fulfilled)
Your integration to the PayFast system can be tested by posting to the sandbox location with the necessary details for your test merchant account. You must then proceed with the payment using the credentials of one of your test user accounts.
Any transactions processed in the sandbox by PayFast:
- will be recorded against the test merchant account as normal, and
- will be successful.
Note: Fulfillment of these transactions will not actually be checked, so when testing the Instant EFT payment method, you must not transfer money as instructed by the system.
Live "Test" Transactions (Fulfilled)
The only real way to "test" whether the full end to end system is working correctly is to actually process some transactions on the live system.
The responsibility for such testing is actually internal to PayFast however, so there should be no need for you to test this functionality.
If you have ensured that your inputs to PayFast are correct in test transactions with the sandbox and have ensured that you can handle the appropriate responses, there should be no reason why the Live system should perform any differently.
If you wish to test this functionality however, note that any money transferred in testing this way will appear in your wallet and can simply be paid out once you are finished with the testing.
Note: Any "test" transactions processed this way will be subject to your agreed to transaction fees which cannot unfortunately be refunded!
Server Details
IP Addresses
| Server | IP Address |
| Live | 196.33.227.224, 196.33.227.225 |
| Sandbox | 196.33.227.224, 196.33.227.225 |
Website Payments
| Server | Address | Port |
| Live | https://www.payfast.co.za/eng/process | 443 |
| Sandbox | https://sandbox.payfast.co.za/eng/process | 443 |
