Merchant Integration Guide

Date: 26-September-2020

Version: 1.1

0 |Page PayFast
 Authors:

 Syed Yousuf Aziz (Service Delivery Manager)

Reviewed by:

 Faisal Alam (Chief Technology Officer)

Revision History:
Date Revised By Revision Incorporated Changes
Section
26 September S Yousuf Aziz API End Points 3.5 and 3.9 added
2020

7th Feb 2020 S Yousuf Aziz Error Codes Error codes update
26th Jan 2021 Syed Danyal Adding Store id 5.2 Initiate Transaction via Form Post
Hassan in Initiate
Transaction via Adding For Redirection implementation with store
Form POST id

18th Feb 2021 Syed Danyal 5.2 Initiate Adding Table 1.2
Hassan Transaction via
Form Post
24th Feb 2021 Syed Danyal 5.1 Get An Updating Table 1.0 with Basket id and txnamt as
Hassan Access Token optional parameters for getting access token

24th Feb 2021 Syed Danyal 5.2 Initiate Updating working code example
Hassan Transaction via
Form POST
request

16th Apr 2021 Syed Danyal 5.2 Initiate Correction in Tran type field name in text field
Hassan Transaction via input type and adding respective tran type details
Form POST
request

22nd Apr 2021 Syed Danyal Redirection Adding Redirection implementation with
Hassan implementation transaction type paragraph
with transaction
type

1 |Page PayFast
6th May 2021 Syed Danyal 6. Error Codes Updating Error codes
Hassan and Description
2nd September Safdar Abbas 3.2 Transaction Addition of information for checkout URL
2021 Via Post
15th June 2022 Safdar Abbas 3.2 Transaction Addition of new parameters
Via Post

Table of Contents
1 Preface............................................................................................. 3
1.1 About ......................................................................................... 3
1.2 Intended Audience ........................................................................ 3
1.3 Integration scope ......................................................................... 3
2 Introduction ...................................................................................... 3
2.1 Payment Flow: ............................................................................. 4
2.2 PayFast Checkout Flow .................................................................. 4
2.2.1 For redirection implementation .................................................. 4
2.3 Merchant Logo/Name setup on PAYFAST gateway page....................... 5
2.4 Getting started with PAYFAST ......................................................... 6
2.4.1 Merchant Settlement .................... Error! Bookmark not defined.
3 Merchant online Payment Integration ................................................. …7
4 Response from Payment Gateway ................... Error! Bookmark not defined.
4.1.1 For Redirect implementation ............... Error! Bookmark not defined.
5 Technical integration requirements ....................................................... 7
5.1 Getting an ACCESS TOKEN ............................................................. 7
5.2 Initiate Transaction via Form POST .................................................. 7
For Redirection implementation ............................................................ 7
5.3 Description of mandatory field ...................................................... 14
6 Error Codes & Description ................................................................. 15
7 PAYFAST checkout Page .................................................................... 17
7.1 For redirection implementation ..................................................... 17

2 |Page PayFast
1 Preface
1.1 About
This document contains detail explanation about how to integrate with
PAYFAST Using Our Hosted Checkout and I-frame based transactions
functionality. This document contains the details for online transactions.

1.2 Intended Audience

This document is for merchants, acquirers and developers who want to
integrate with PAYFAST to perform Our Hosted Checkout and I-frame based
transactions.

1.3 Integration scope

All the ecommerce functionality will be implemented by the merchant.
PAYFAST service (PayFast) will be used only for payment processing.

2 Introduction
PAYFAST payment gateway is a payment service developed for merchants to
accept payments from the customers using banks’ instruments.

3 |Page PayFast
Transaction starts from the merchant’s web based ecommerce portal, after this
the customer checks out and is redirected to PAYFAST payment gateway web
checkout page where customer will enter their credit, debit, wallet and, account
number Buyer Send the correct OTP (one-time password), and completes the
payment process, and customer will have redirected towards the same
merchant’s ecommerce portal where the customer order is confirmed by
merchant if payment is successful.

2.1 Payment Flow:

A generic payment flow
In a typical PAYFAST payment flow, a buyer:

1. Buyer (customer) adds items in the shopping cart on merchant’s

ecommerce portal.
2. Buyer reaches checkout page and select the PAYFAST as the payment
option.
3. Buyer is redirected to PAYFAST payment gateway web checkout page (For
Details see section “3” PAYFAST Checkout Flow).
4. Buyer Send the correct OTP (one-time password), and completes the
payment process. And customer will have redirected towards the same
merchant’s ecommerce portal where the customer order is confirmed by
merchant if payment is successful.

2.2 PayFast Checkout Flow

In the PAYFAST checkout flow, the buyer:
a. Logged IN user and clicks, “Submit my order” button on the merchant’s
ecommerce portal.

2.2.1 For redirection implementation

1. Order request forward to the PAYFAST checkout page.
2. Buyer select banks and enter their credit, debit, wallet and, account
number, and proceed payment.
3. After clicking validate button, transaction request to the selected bank for
authentication via OTP from customer.
4. After receiving OTP, customer can enter the OTP which is provided by bank
on SMS/USSD channel.
5. Returns to Merchant site and confirms the order then receives confirmation.

4 |Page PayFast
2.3 Merchant Logo/Name setup on PAYFAST gateway page

Before the transaction is processed the buyer is taken to a Merchant Logo/Name

on PAYFAST payment gateway page, where the buyer’s information is taken, and
after submission the order information is displayed. Upon continuation, this page
is used to process the transaction with the PAYFAST platform.

The buyer is subsequently taken to the merchant website order confirmation

page.

5 |Page PayFast
2.4 Getting started with PayFast

In order to proceed with PayFast- integration , merchant would be required to

sign up on https://getstarted.PayFast.net.pk/ , and would be proceeding with
sign up flow

Once the merchant is signed up, he would be required to fill up the info
required. For further details please refer DMS documentation document
shared separately.

C:\Users\muhammad.arfeen\Downloads\DMSDocumentation.pdf

6 |Page PayFast
3 Technical integration requirements
3.1 Getting an ACCESS TOKEN
A web hook has to be called to get the access token. Merchant ID, Secure Key,
Basket ID and Transaction ount are the values will be sent to fetch the access
token. Moreover, Empty user agent not allowed. Please see below table 1.1.

Table 1.0
URL https://ipguat.apps.net.pk/Ecommerce/api/Transaction/GetAccessToken
Method POST
Parameters MERCHANT_ID (Mandatory)
SECURED_KEY (Mandatory)
BASKET_ID (Mandatory)
TXNAMT (Mandatory)
Response Type JSON
Response {
“MERCHANT_ID”:”<<MERCHANT_ID>>”
“ACCESS_TOKEN”:”<<ACCESS_TOKEN>>”
“NAME”:”sha”
“GENERATED_DATE_TIME”:”<<GENERATED_DATE_TIME>>”
}

3.2 Initiate Transaction via Form POST

For Redirection implementation, after getting an access token, ecommerce
will send a FORM POST along with following parameters to PAYFAST payment
gate.

Table 1.1
URL for redirection option https://ipguat.apps.net.pk/Ecommerce/api/Transaction/PostTransaction
Method POST
Form Parameters Description
MERCHANT_ID A unique ID provided by PAYFAST
MERCHANT_NAME Brand name
TOKEN Access token fetched by web hook as mentioned in Table 1.0
PROCCODE 00
TXNAMT The amount which needs to be paid by the customer (this should
match with the amount sent in the token API)
CUSTOMER_MOBILE_NO Customer’s mobile number
CUSTOMER_EMAIL_ADDRESS Customer’s email address
SIGNATURE A random string value
VERSION A random string value
TXNDESC Short description of the goods purchased by customer
SUCCESS_URL URL where customer will be redirected to in the browser if payment is
successful.
FAILURE_URL URL where customer will be redirected to in the browser if payment is
unsuccessful.
BASKET_ID A unique order id from the merchant, which will represent customer’s
order. (this should match with the Basket ID sent in the token API)

7 |Page PayFast
 ORDER_DATE Date of the order.
(Format: YYYY-MM-DD e.g. 2018-01-01)
CHECKOUT_URL URL payment information or notification is pushed to the merchant at
the backend. There are two types of checkout URL
immediate(Transaction notification will be pushed immediately) or
delayed(Transaction notification will be pushed after a minute)
STORE_ID Alphanumeric string which would come from merchant portal’s outlet
section after outlet creation <optional>
CURRENCY_CODE PKR <optional>
TRAN_TYPE Transaction type for settlement <optional>

CUSTOMER_NAME Customer name from merchant’s web site

MERCHANT_CUSTOMER_ID Customer ID in merchant’s web site
CUSTOMER_IPADDRESS Customer IP address at merchant’s web site
COUNTRY Customer country
SHIPPING_CUSTOMER_NAME Customer name for Shipping address
SHIPPING_ADDRESS_1 Customer shipping address
SHIPPING_ADDRESS_2 Customer shipping additional address
SHIPPING_STATE_PROVINCE Shipping state/province
SHIPPING_ADDRESS_CITU Shipping city
SHIPPING_POSTALCODE Shipping postal code
SHIPPING_METHOD Shipping method (Courier, Local Delivery etc)
BILLING_CUSTOMER_NAME Billing customer name from merchant’s web site
BILLING_ADDRESS_CITY Billing city of customer
BILLING_ADDRESS_1 Billing address
BILLING_ADDRESS_2 Billing additional address
BILLING_STATE_PROVINCE Billing state/province
BILLING_POSTALCODE Billing postal code
MERCHANT_USERAGENT Browser user agent from merchant’s web site
ITEMS An array (stating from zero) of purchased products from merchant’s
web site. S
ITEMS[x][SKU]
ITEMS[x][NAME]
ITEMS[x][PRICE]
ITEMS[x][QTY]
TRAVEL_FIRSTNAME Travelling customer first name
TRAVEL_LASTNAME Travelling customer last name
TRAVEL_NOOFPASSENGERS Travelling no of customers
TRAVEL_CARRIERCODE Travelling customer carrier code
TRAVEL_DESTINATION Travelling destination
TRAVEL_DEPARTUREDATE Travelling departure date
TRAVEL_DEPARTURETIME Travelling departure time
TRAVEL_ORIGINATION Travelling origination
TRAVEL_JOURNEYTYPE Travelling journey type
TRAVEL_ACTUALFINALDESTINATION Travelling actual destination

Working Code Example

An example PHP code snippet is as follows:

<html>
<body>

8 |Page PayFast
 <h1>PayFast Example Code For Redirection Payment Request</h1>
<?php
$merchant_id = 102;

$secured_key = 'zWHjBp2AlttNu1sK';
$basket_id = 'ITEM-001';
$trans_amount = 100;
if (count($_GET) > 0) {
processResponse($merchant_id, $basket_id, $trans_amount, $_GET);
}
$token = getAccessToken($merchant_id, $secured_key, $basket_id,
$trans_amount);

/**

* get access token with merchant id, secured key, basket id,
transaction amount
*
*/

function getAccessToken($merchant_id, $secured_key, $basket_id,

$trans_amount)
{
$tokenApiUrl =
'https://ipguat.apps.net.pk/Ecommerce/api/Transaction/GetAccessToken';

$urlPostParams = sprintf(
'MERCHANT_ID=%s&SECURED_KEY=%s&TXNAMT=%s&BASKET_ID=%s',
$merchant_id,
$secured_key,
$trans_amount,

$basket_id
);

9 |Page PayFast
 $ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $tokenApiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, $urlPostParams);
curl_setopt($ch, CURLOPT_USERAGENT, 'CURL/PHP PayFast Example');
$response = curl_exec($ch);
curl_close($ch);
$payload = json_decode($response);
$token = isset($payload->ACCESS_TOKEN) ? $payload->ACCESS_TOKEN
: '';
return $token;
}

/**
* process response coming from PayFast
*
*/
function processResponse($merchant_id, $original_basket_id, $txnamt,
$response)
{
/**
* following parameters sent from PayFast after success/failed
transaction
*
*/

$trans_id = $response['transaction_id'];

$err_code = $response['err_code'];
$err_msg = $response['err_msg'];
$basket_id = $response['basket_id'];
$order_date = $response['order_date'];
$response_key = $response['Response_Key'];

10 | P a g e PayFast
 $payment_name = $response['PaymentName'];
$secretword = ''; // No secret code defined for merchant id 102,
secret code can be entered in merchant portal.
$response_string = sprintf("%s%s%s%s%s", $merchant_id,
$original_basket_id, $secretword, $txnamt, $err_code);
$response_hash = hash('MD5', $response_string);

if (strtolower($response_hash) != strtolower($response_key)) {
echo "<br/>Transaction could not be varified<br/>";
return;
}

if ($err_code == '000' || $err_code == '00') {

echo "<strong>Transaction Successfully Completed.
Transaction ID: " . $trans_id . "</strong><br/>";
echo "<br/>Date: " . $order_date;
return;

}
echo "<br/>Transaction Failed. Message: " . $err_msg;
}

?>
<!-- For data integrity purpose, transaction amount and basket_id
should be the same as the ones sent in token request -->
<!--
Actual Payment Request
-->
<form id='PayFast_payment_form' name='PayFast-payment-form'
method='post'
action="https://ipguat.apps.net.pk/Ecommerce/api/Transaction/PostTransac
tion">

Currency Code: <input type="TEXT" name="CURRENCY_CODE"

value="PKR" /><br />
Merchant ID: <input type="TEXT" name="MERCHANT_ID" value="<?php
echo $merchant_id; ?>" /><br />

11 | P a g e PayFast
 Merchant Name: <input type="TEXT" name="MERCHANT_NAME"
value="UAT Demo Merchant" /><br />
Token: <input type="TEXT" name="TOKEN" value="<?php echo $token;
?>" /><br />
Success URL: <input type="TEXT" name="SUCCESS_URL"
value="http://merchant-site-example.com" /><br/>
Failure URL: <input type="TEXT" name="FAILURE_URL"
value="http://merchant-site-example.com" /><br/>
Checkout URL: <input type="TEXT" name="CHECKOUT_URL"
value="http://merchant-site-example.com" /><br/>

Customer Email: <input type="TEXT" name="CUSTOMER_EMAIL_ADDRESS"

value="[email protected]" /><br />
Customer Mobile: <input type="TEXT" name="CUSTOMER_MOBILE_NO"
value="00000000000" /><br />
Transaction Amount: <input type="TEXT" name="TXNAMT"
value="<?php echo $trans_amount; ?>" /><br />
Basket ID: <input type="TEXT" name="BASKET_ID" value="<?php echo
$basket_id; ?>" /><br />
Transaction Date: <input type="TEXT" name="ORDER_DATE"
value="<?php echo date('Y-m-d H:i:s', time()); ?>" /><br />
Signature: <input type="TEXT" name="SIGNATURE" value="SOME-
RANDOM-STRING" /><br />

Version: <input type="TEXT" name="VERSION" value="MERCHANT-CART-

0.1" /><br />
Item Description: <input type="TEXT" name="TXNDESC" value="Item
Purchased from Cart" /><br />
Proccode: <input type="TEXT" name="PROCCODE" value="00" /><br />
Transaction Type: <input type="TEXT" name="TRAN_TYPE"
value='ECOMM_PURCHASE' /><br />
Store ID/Terminal ID (optional): <input type="TEXT"
name="STORE_ID" value='102-ZEOJDZS3V' /><br />

<INPUT TYPE="HIDDEN" NAME="MERCHANT_USERAGENT" value="Mozilla/5.0

(Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0">

<INPUT TYPE="HIDDEN" NAME="ITEMS[0][SKU]" value="SAMPLE-SKU-01">

<INPUT TYPE="HIDDEN" NAME="ITEMS[0][NAME]" value="An Awesome Dress">
<INPUT TYPE="HIDDEN" NAME="ITEMS[0][PRICE]" value="150">
<INPUT TYPE="HIDDEN" NAME="ITEMS[0][QTY]" value="2">

12 | P a g e PayFast
 <INPUT TYPE="HIDDEN" NAME="ITEMS[1][SKU]" value="SAMPLE-SKU-02">
<INPUT TYPE="HIDDEN" NAME="ITEMS[1][NAME]" value="Ice Cream">
<INPUT TYPE="HIDDEN" NAME="ITEMS[1][PRICE]" value="45">
<INPUT TYPE="HIDDEN" NAME="ITEMS[1][QTY]" value="5">

<input type="SUBMIT" value="SUBMIT">

</form>

</body>
</html>

For Redirection implementation with store id

Please note that store id is optional but if added as a parameter then it will be validated in
our system of which following example is slated below:

Store id of sample merchant: 102-ZEOJDZS3V

For Redirection implementation with transaction type

If merchant wants customer to pay with slab based banks then tran type would be passed as
bill payment:

Transaction Type: <input type="TEXT" name="TRAN_TYPE" value='BILL_PAYMENT' />

For bill_payment tran_type, merchant may pass additional information in the respective form
as follows:

Bill Number: <input type="TEXT" name="BILL_NUMBER" value='12345' />

Please note that we are passing transaction type (tran_type) for the sole purpose of
transaction settlement.

In either case, payment gateway will send additional parameters (along with those sent
already by merchant) containing transaction information. These parameters are as follows:
Table 1.2
Method GET
URL Merchant’s supplied URL
transaction_id Transaction ID processed at payment gateway

13 | P a g e PayFast
err_code Status code of the transaction.

(‘000’ is for successful transaction)

err_msg Descriptive message in case of failed transaction
basket_id Order ID sent by merchant.
order_date Date of order sent by merchant.
Rdv_Message_Key Payment gateway middleware transaction id.
responseKey (it An MD5 hash of combination of multiple fields,
will be depreciated to verify authenticated response:
soon)
merchant_id + basket_id + <secret word>+
txnamt + err_code
validation_hash A SHA256 hash of combination of following
fields in particular order:

Basket ID

Merchant Secured Key

Merchant ID

Error Code (received from PayFast)

String Sequence:

“your_basket_id|your_merchant_secret_key|yo
ur_merchant_id|payasft_err_code”

e.g. BAS-01|jdnkaabcks|102|000

SHA256 of above example will make following

hash:
e8192a7554dd699975adf39619c703a492392edf
5e416a61e183866ecdf6a2a2
(please note “|” (pipe) sign is included in the string)

Value received from PayFast should match with your calculated

hash for data integrity.

3.3 Description of mandatory field

Mandatory Field Description

MERCHANT_ID A unique ID provided by PAYFAST
Merchant_Name Your brand name

14 | P a g e PayFast
 TOKEN Access token fetched by web hook as mentioned in Table 1.0
PROCCODE 00
TXNAMT The amount which needs to be paid by the customer
CUSTOMER_MOBILE_NO Customer’s mobile number
CUSTOMER_EMAIL_ADDRESS Customer’s email address
SIGNATURE A random string value
VERSION A random string value
TXNDESC Short description of the goods purchased by customer
SUCCESS_URL URL where customer will be redirected to in the browser if
payment is successful.
FAILURE_URL URL where customer will be redirected to in the browser if
payment is unsuccessful.
BASKET_ID A unique order id from the merchant that will represent
customer’s order.
ORDER_DATE Date of the order.
(Format: YYYY-MM-DD e.g. 2018-01-01)
CHECKOUT_URL URL payment information or notification is pushed to the
merchant at the backend. There are two types of checkout
URL immediate(Transaction notification will be pushed
immediately) or delayed (Transaction notification will be
pushed after a minute)

The code being flexible is easily embedded on the merchant payment

page. The buyer payment information will need to be parsed to the
PAYFAST gateway page via this relay form.

4 Error Codes & Description

ERROR CODES ERROR DESCRIPTIONS
00 Processed OK
002 Time Out
97 Dear Customer, You have an Insufficient
Balance to proceed
106 Dear Customer, Your transaction Limit has
been exceeded please contact your bank
03 You have entered an Inactive Account
104 Entered details are Incorrect
55 You have entered an Invalid OTP/PIN
54 Card Expired
13 You have entered an Invalid Amount
126 Dear Customer your provided Account
details are Invalid
75 Maximum PIN Retries has been Exceeded
14 Dear Customer, You have entered an In-
Active Card number
15 Dear Customer, You have entered an In-
Active Card number

15 | P a g e PayFast
 42 Dear Customer, You have entered an Invalid
CNIC
423 Dear Customer, We are unable to process
your request at the moment please try
again later
41 Dear Customer, entered details are
Mismatched
801 {0} is your PayFast OTP (One Time
Password). Please do not share with
anyone.
802 OTP could not be sent. Please try again
later.
803 OTP has been sent to your email address.
804 OTP has been sent to your mobile number.
805 OTP Verified
806 OTP could not be verified.
807 Too many attempts. Please try again later in
few minutes.
808 Passwords do not match
809 Invalid Password
810 Password could not be changed
811 Password changed successfully
812 Request could not be validated. Please try
again.
813 Email address already registered
9000 FRMS Rejected
9010 FRMS Error
308 Dear Customer your provided Account
details are Invalid
600 OTP Already Expired
309 You have entered Invalid OTP Length
853 Dear Customer, Your provided Account
details are Invalid
04 You have entered a Closed Account
537 You have entered a Dormant Account
359 Blocked Account
8811 Password changed successfully
880 Transaction declined due to non-activation
of local ecommerce session. Please call
your bank.
881 Your transaction is declined due to
insufficient funds. Please call your bank for
assistance
882 Your transaction is declined due to
consumption of daily local epayment
transaction limit/count.

16 | P a g e PayFast
 883 Your transaction is declined. Please call
your bank to activate local epayment
service

PayFast checkout Page

4.1 For redirection implementation
On posting the form data, customer will be redirected to the following page of
the PAYFAST web ecommerce portal.

17 | P a g e PayFast
18 | P a g e PayFast