Bitaqaty Business system offers online shopping to merchants in order to expand their current payment processing options by adding Bitaqaty Business as a payment method where Bitaqaty Business user will select Bitaqaty Business as the payment method on the shopping interface of the website, and will be redirected to Bitaqaty Business’s website in order to provide his Bitaqaty Business credentials. Once the credentials are verified, the user will be redirected to the merchant’s website back to get the service.

Before starting integration

Upon signing the contract with Bitaqaty Business

1. Merchant is handed the following keys for the staging environment:
   • Merchant ID; which has two roles:
     • Acts as the username for the merchant while viewing merchant dashboard in Bitaqaty Business system.
     • Used as merchant identifier in all communication between Bitaqaty Business and the merchant.
   • Password: it should be used to view merchant dashboard on Bitaqaty Business system.
   • Transkey: it is a secret key shared between Bitaqaty Business and the merchant; it will be used by the merchant in generating the merchant signature (hash code) and must not be communicated over http.
   • Keyword:it is a secret key shared between Bitaqaty Business and the merchant; it will be used by Bitaqaty Business in generating Bitaqaty Business signature (hash code) and must not be communicated over http.
   • User testing credentials to simulate payment over Bitaqaty Business system
     • Username:used to login as a customer on Bitaqaty Business system
     • Password
2. Merchant has to provide the following:
   • Error URL (optional):a page on merchant website that will be used for any non successful/failure transaction as Bitaqaty Business system will redirect user to this specific URL in a post request passing the error code related to such transaction; it is the merchant responsibility to display a user friendly error message according to the error code received from Bitaqaty Business system.
   • Notification email address (optional):a merchant email address that will receive a daily notification mail message that includes an attached spreadsheet file “.xls”, which will contain all successful transactions which took place during the previous business day (12:00 am to 11:59 pm) based on Egyptian time zone UTC/GMT +2 hrs (summer +3 hrs).
   • Handshake URL (optional): where Bitaqaty Business system will communicate with merchant system to validate incoming transactions. This page role will be as follows:
     • Receives validation request from Bitaqaty Business system (http POST request)
     • Validates request internally by merchant site
     • Responds with validation acknowledgment to Bitaqaty Business request (reply to Bitaqaty Business request)

Full Scenario of what happen :

1. Customer finishes their shopping on the merchant site and proceeds to merchant’s checkout page.
2. Merchant redirects customer to Bitaqaty Business staging or Production Integration URL as mention below via http post request with the appropriate request parameters that includesmerchant signature.
3. Bitaqaty Business validates the received merchant request; i.e. calculate the proper hash code value and compare it with the one passed by merchant.
4. Bitaqaty Business requests customer’s Bitaqaty Business credentials.
5. Customer provides his/her Bitaqaty Business’s credentials (username & password), and confirms purchase request.
6. Bitaqaty Business authenticates the user.
7. Optional Feature:
   • On a separate call Bitaqaty Business sends a different http request to merchant’s handshake URL (previously submitted upon signing the contract).
   • Merchant validates Bitaqaty Business request; i.e. calculate the proper hash code value and compare it with the one passed by Bitaqaty Business.
   • Merchant replies back with a confirmation response to Bitaqaty Business request via the response of Bitaqaty Business request. The response should include only a hash key value that calculates as follows:
     

     MD5 (OneCard_MerchID + OneCard_Code + OneCard_TransID + OneCard_Amount + OneCard_Currency + OneCard_RTime + OneCard_TransKey)

   • Bitaqaty Business validates merchant confirmation; i.e. calculate the proper hash code value and compares it with the one passed by the merchant.
8. Bitaqaty Business deduct the amount from user balance, then redirects the user back to merchant’s return URL which was previously sent by merchant at the beginning of the transaction

Transaction lifecycle:

Main Cycle:

Request Status Cycle:

Method Name:

Technical Considerations

This is consider main method of this service where Customer finishes their shopping on the merchant site and proceeds to merchant’s checkout page then Merchant redirects customer to Bitaqaty Business staging or Production Integration URL as mention below via http post request with the appropriate request parameters that includesmerchant signature.

Request URLs (Web Version) :

Request URLs (WAP Version) :

Request Parameters :

Response Parameters:

Code Examples :

• JavaScript

• Python

• PHP

• Java

     

const Url='https://www.ocstaging.net/mobile/integratedPayment.html';
const data ={
	  'OneCard_MerchID' : 'testingg',
    'OneCard_TransID' : '2143688488',
    'OneCard_Amount' : '10',
    'OneCard_Currency' : 'SAR',
    'OneCard_Timein' : 1533785391,
    'OneCard_MProd' : 'Dummy product',
    'OneCard_ReturnURL' : 'index.html',
    'OneCard_Field1' : 'Dummy data',
    'OneCard_Field2' : 'Dummy data',
    'OneCard_HashKey' : 'b21bee1d13107ae48623411762768fc9',
    'OneCard_CancelURL' : 'index.html',
    'siteLanguage' : 'EN'

}

$('.btn').click(function(){
	
	$.post(Url,data,function(data,status){

console.log('S{data} and status is ${status}')
	});
});

import urllib, urllib2

url = 'https://www.ocstaging.net/mobile/integratedPayment.html'
values = {
    'OneCard_MerchID' : 'testingg',
    'OneCard_TransID' : '2143688488',
    'OneCard_Amount' : '10',
    'OneCard_Currency' : 'SAR',
    'OneCard_Timein' : 1533785391,
    'OneCard_MProd' : 'Dummy product',
    'OneCard_ReturnURL' : 'index.html',
    'OneCard_Field1' : 'Dummy data',
    'OneCard_Field2' : 'Dummy data',
    'OneCard_HashKey' : 'b21bee1d13107ae48623411762768fc9',
    'OneCard_CancelURL' : 'index.html',
    'siteLanguage' : 'EN'
}

data = urllib.urlencode(values)
req = urllib2.Request(url, data)
rsp = urllib2.urlopen(req, timeout=60)
content = rsp.read()

print content

<?php

$url = 'https://www.ocstaging.net/mobile/integratedPayment.html';
$params = array(
    'OneCard_MerchID' => 'testingg',
    'OneCard_TransID' => '2143688488',
    'OneCard_Amount' => '10',
    'OneCard_Currency' => 'SAR',
    'OneCard_Timein' => 1533785391,
    'OneCard_MProd' => 'Dummy product',
    'OneCard_ReturnURL' => 'index.html',
    'OneCard_Field1' => 'Dummy data',
    'OneCard_Field2' => 'Dummy data',
    'OneCard_HashKey' => 'b21bee1d13107ae48623411762768fc9',
    'OneCard_CancelURL' => 'index.html',
    'siteLanguage' => 'EN'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);

// This should be the default Content-type for POST requests
//curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: application/x-www-form-urlencoded"));

$result = curl_exec($ch);
if(curl_errno($ch) !== 0) {
    error_log('cURL error when connecting to ' . $url . ': ' . curl_error($ch));
}

curl_close($ch);
print_r($result); 

?>

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.ProtocolException;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class JavaPostRequest {

    private static HttpURLConnection con;

    public static void main(String[] args) throws MalformedURLException,
            ProtocolException, IOException {

        String url = "https://www.ocstaging.net/mobile/integratedPayment.html";
        String urlParameters = "OneCard_MerchID=testingg+&OneCard_TransID=2143688488+&OneCard_Amount=10&OneCard_Currency=SAR+&OneCard_Timein=1533785391+&OneCard_MProd=Citroen&OneCard_ReturnURL=Sucess_page.php+&OneCard_Field1=Dummy+data+&OneCard_Field2=Dummy+data+&OneCard_HashKey=b21bee1d13107ae48623411762768fc9&OneCard_CancelURL=index.php+&siteLanguage=Ar+
";
        byte[] postData = urlParameters.getBytes(StandardCharsets.UTF_8);

        try {

            URL myurl = new URL(url);
            con = (HttpURLConnection) myurl.openConnection();

            con.setDoOutput(true);
            con.setRequestMethod("POST");
            con.setRequestProperty("User-Agent", "Java client");
            con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

            try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
                wr.write(postData);
            }

            StringBuilder content;

            try (BufferedReader in = new BufferedReader(
                    new InputStreamReader(con.getInputStream()))) {

                String line;
                content = new StringBuilder();

                while ((line = in.readLine()) != null) {
                    content.append(line);
                    content.append(System.lineSeparator());
                }
            }

            System.out.println(content.toString());

        } finally {
            
            con.disconnect();
        }
    }
}

Method Name:

Technical Considerations

On a separate call Bitaqaty Business sends a different http request to merchant’s handshake URL then Merchant validates Bitaqaty Business request; i.e. calculate the proper hash code value and compare it with the one passed by Bitaqaty Business and after This Merchant replies back with a confirmation response to Bitaqaty Business request via the response of Bitaqaty Business request. The response should include only a hash key value that calculates as follows:

MD5 (OneCard_MerchID + OneCard_Code + OneCard_TransID + OneCard_Amount + OneCard_Currency + OneCard_RTime + OneCard_TransKey)

Request URL:

Request Status

Technical Considerations

Merchant can request the status of certain transaction from Bitaqaty Business system via a separate http post request

Request URL:

Request Parameters:

Response Parameters: