Documentation ( V 1.0 ) Back

Last updated: Jun 27th, 2017

Overview

FastPay is Kurdistan's quickest, most convenient, and safest mobile wallet for Shopping, Mobile recharge, Internet recharge, Money transfers and Bill payments. Use FastPay for a cashless, hassle-free experience while shopping, dining, travelling and a lot more!

FastPay Process Flow

FastPay  Process

The above steps can be categorized in three sections based on the development process described below.

Transaction Initiate:

The Steps 1, 2 and 3 are used to make the request for a new transaction. After getting confirmation of checkout from customer, merchant server sends a request to FastPay server to get a Session ID. If all the credentials and mandatory fields are valid, then FastPay provides a Session ID to Merchant System. After receiving the Session ID, Merchant System redirects the customer to payment page with Session ID.

Handling Payment Notification:

The Step 4 and 5 are processed at this stage. For any notification, FastPay will send HTTP message in POST method called IPN Message to the Listener which is to be configured by the Merchant attheir FastPay Administrator Panel. After receiving the message, you must validate the message with Transaction Validation API of FastPay.

Service Confirmation:

At Step 5, FastPay will redirect the customer to merchant’s side. At this stage, Merchant will display the notification of Service Confirmation.

Integration Steps

Initiate Payment

Provide Information about your customer and order to FastPay along with your store id to initiate the payment. Rest of the payment process will be done by FastPay

Validate Payment

After successfully taking the payment FastPay will send the request back to you as SUCCESS, FAILED or CANCEL status. You must validate with our validation API using transaction ID, amount and currency

Update your transaction

After validation of the transaction that you have received, Depending on the status you have to update your transaction in your Database. The status will Success, Failed, Cancelled depending on payment status.

Enable most advanced IPN

This is an important and interesting part of integration. If somehow your consumer pays your payable amount to BANK Side and FastPay accept it as SUCCESS but your website/Connectivity/Customer Network got downtime and unable to update the payment at your side you can use IPN ( Instant Payment Notification ). It will send an notification to your set up URL in FastPay Merchant Dashboard to notify you and your database even if your user unable to return back to your website

Checkpoint Tips:

  • You must collect your STORE ID and Password from FastPay by contacting to our helpline
  • You must validate your transaction and amount by calling our API
  • You must set IPN url to receive notification for both returned and missed payments

Payment Process Environment

We have both Live environment and Test/Sandbox environment in FastPay . You just need to use proper URL and Store ID's to process payments. We provide separate store ID for live and test

Live Environment

All the transaction made using this environment are counted as real transaction, URL starts with https://secure.fast-pay.cash

Sandbox Environment

All the transaction made using this environment are counted as test transaction and has no effect with accounting, URL starts with https://dev.fast-pay.cash

Initiate Payment

For initiating payment processing, at first you need to enable HTTP IPN Listener to listen the payments. So that you can update your database accordingly even customer got connectivity issue to return back to your website.

Create and Get Session

Make an array by using those parameters fill with data, You need to create session at FastPay end. You have to call initiation API to generate session and get in response


/* PHP */
$post_data = array();
$post_data['merchant_mobile_no'] = "+9641234567890";
$post_data['store_password'] = "your-store-password";
$post_data['order_id'] = "asdf12345";
$post_data['bill_amount'] = "1000";
$post_data['success_url'] = "https://your-domain-url/success.php";
$post_data['fail_url'] = "https://your-domain-url/fail.php";
$post_data['cancel_url'] = "https://your-domain-url/cancel.php";
                                            
API URL: https://dev.fast-pay.cash/merchant/generate-payment-token
Parameters: Your ready array variable in previous step.
Method: POST ( CURL for PHP, httpwebrequest for .NET and etc)
# SENT REQUEST TO FASTPAY
$direct_api_url = "https://dev.fast-pay.cash/merchant/generate-payment-token";

$handle = curl_init();
curl_setopt($handle, CURLOPT_URL, $direct_api_url );
curl_setopt($handle, CURLOPT_TIMEOUT, 10);
curl_setopt($handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($handle, CURLOPT_POST, 1 );
curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);


$content = curl_exec($handle );

$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);

if($code == 200 && !( curl_errno($handle))) {
	curl_close( $handle);
	$response = $content;
} else {
	curl_close( $handle);
	echo "FAILED TO CONNECT WITH FastPay  API";
	exit;
}

# PARSE THE JSON RESPONSE
$decodedResponse = json_decode($response, true );
                                            
Response :
    {
        "messages":"",
        "token":"giu47z87fyr863adsfajfdenbof1846as4fd68a1v8e8a6e1fa8df48e88ef49a8sd7f458ve4s4dfgpkko,mqw3239sdv948hzvfh",
        "code":"200"
    }
                                            

You have to parse token field from this json response and redirect user to https://dev.fast-pay.cash/merchant/payment url with token field via post or get method. For example: https://dev.fast-pay.cash/merchant/payment?token=generatedToken

Validate Payment with IPN

Remember, We have set an IPN URL in first step so that your server can listen at the right moment when payment is done at FastPay End. So, It is important to validate the transaction notification to maintain security and standard.

Step 1) Grab the notification

As IPN URL already set in panel. All the payment notification will reach through IPN prior to user return back. So it needs validation for amount and transaction properly.

The IPN will send a POST REQUEST with below parameters. Grab the post notification with your desired platform ( PHP: $_POST)

transaction_id Transaction ID (Unique)
order_id Order ID (Unique)Send by you when make the token request
bill_amount The total amount sent by you and it needs validation for security
customer_account_no Customer fast pay account number who make the payment
status Transaction Status - as Success / Failed / Cancelled
received_at Transaction date - Payment completion date as 2016-05-08 15:53:49 ( PHP date('Y-m-d H:i:s') )

Step 2) Payment Validation API

After knowing that the post keys are valid and no moletion done with the request, now it is the time to validate your transaction for amount and transaction. It will only treated as valid if amount and transaction status are valid at FastPay End

So, Let's call the API and the example given below

API URL: https://dev.fast-pay.cash/merchant/payment/validation

Method: POST

$post_data = array();
$post_data['merchant_mobile_no']='merchant_mobile_no';
$post_data['store_password']="your store id";
$post_data['order_id']="your order id";

$requested_url = "https://dev.fast-pay.cash/merchant/payment/validation";

$handle = curl_init();
curl_setopt($handle, CURLOPT_URL, $requested_url );
curl_setopt($handle, CURLOPT_TIMEOUT, 10);
curl_setopt($handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($handle, CURLOPT_POST, 1 );
curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($handle);

$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);

if($code == 200 && !( curl_errno($handle)))
{

	# TO CONVERT AS ARRAY
	# $result = json_decode($result, true);

	# TO CONVERT AS OBJECT
	$result = json_decode($result);

	# TRANSACTION INFO
	$messages = $result->messages;
	$code = $result->code; #if $code is not 200 then something is wrong with your request.
        $data = $result->data;
	

} else {

	echo "Failed to connect with FastPay";
}
                                        

Response:

{
	"messages":"Please find your transaction details:",
        "data":
        {
            'transaction_id':'123456',
            'order_id':'asdf12345',
            'bill_amount':'10000',
            'customer_account_no':'+9649876543210',
            'status':'Success',
            'received_at': '2017-07-27 12:55:45'
        }
        "code":"200"

}
                                        

Security Check Points:

  • Track your order by transaction ID and check it in your database for existence
  • Must validate amount and incomming amount from your Database
  • Check for the status - Success, Failed, Cancelled to update your order status

Update your transaction

So, Your order and amount validated and it is ready for update in your database. If status is Valid and validation status Valid then update your database according to the status. and wait for your user to your website to show him/her the success, fail, and cancel page.

Common Issues

Network Issues:

  • The Listener must use the common port like 80, 443 or 8080
  • Your IPN Listener must be reachable from Internet
  • White-list the FastPay IPs at your network firewall