Quick Start

Last updated: Mars 03th, 2019

System Overview


Funding channel service allows different funding channels to integrate with Bitaqaty Business to re-charge Bitaqaty Business customers’ balance and to check the status of any submitted funding requests.

The Funding Channel API document describes the API requirements for funding channels to integrate with Bitaqaty Business to re-charge Bitaqaty Business customers’ balance
Funding Channel is Provide WSDL that have two main methods
1-Recharge Account : that let you recharge customer Bitaqaty Business account
2-Get Request Status: that let you check status of request that you perform depending on request number that created aopn request

Before starting integration

Upon signing the contract with Bitaqaty Business

Funding channel is handed the following keys for the staging environment:

  • Username; which has two roles:
    • Allow funding channel to login to their dashboard on Bitaqaty Business system.
    • Used as identifier in all communication between Bitaqaty Business and funding channel
  • Password: it should be used to view merchant dashboard on Bitaqaty Business system.
  • OneCard_Key: it is a secret key shared between Bitaqaty Business and funding channel; it will be used by funding channel in generating its 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: used to login as a customer on Bitaqaty Business system

API URLs


Recharge Account URLs :

Funding Channel Dashboard URLs :

API Methods

Method Name:

Recharge Account (Refilling Method)


Request Flow :
  • Funding channel enters the request details and the customer account number to be re-charged.
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business re-charges the customer’s account after exchanging the amount to his/her account currency on Bitaqaty Business system.
    • Error: Bitaqaty Business return correspondent error code; please refer to the Response Codes for more details.

Technical Considerations

Request Parameters:

Parameter Name Data Type Description Validation
username String Web service dashboard username
password String Web service dashboard password
requestNo String A request reference number generated by funding
channel to be used to check on the request status
Unique
amount Double Amount to be added to the customer’s account Greater than zero, max 6 characters
currency String Currency (Please check Bitaqaty Business website for the supported currencies)
http://www.netader.com/customer/currencyList.html
3 letter ISO currency code
customerAccountNo String Bitaqaty Business customer’s account number (customer can get this from his control panel in Bitaqaty Business website) 10 digits
requestHash String MD5 digest for a string, composed as follows in order: MD5 (username + requestNo + amount + currency + customerAccountNo + OneCard_Key)
Note: All parameters are required.

Response Parameters:

Parameter Name Data Type Description Validation
responseCode String Response Code, refer to Response Codes
responseMessage String Response message for requested transaction
Code Examples :


     

     function soap() {
            var xmlhttp = new XMLHttpRequest();
            xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/refillAccount.wsdl', true);
            // build SOAP request
            var sr =
                '<soapenv:Envelope xmlns:soapenv="
                http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
                   <soapenv:Header/>
                   <soapenv:Body>
                      <web:refillAccountRequest>
                         <web:username>test@netader.com</web:username>
                         <web:password>#$JHJ5456</web:password>
                         <web:requestNo>25165156</web:requestNo>
                         <web:amount>200</web:amount>
                         <web:currency>EGP</web:currency>
                         <web:customerAccountNo>555565</web:customerAccountNo>
                         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
                         <!--Optional:-->
                         <web:terminalId>200</web:terminalId>
                      </web:refillAccountRequest>
                   </soapenv:Body>
                </soapenv:Envelope>';

            xmlhttp.onreadystatechange = function () {
                if (xmlhttp.readyState == 4) {
                    if (xmlhttp.status == 200) {
                        alert('done. use firebug/console to see network response');
                    }
                }
            }
            // Send the POST request
            xmlhttp.setRequestHeader('Content-Type', 'text/xml');
            xmlhttp.send(sr);
            // send request
            // ...
        }

import requests
url="https://www.ocstaging.net/webservice/refillAccount.wsdl"
#headers = {'content-type': 'application/soap+xml'}
headers = {'content-type': 'text/xml'}
body = """<soapenv:Envelope xmlns:soapenv="
                http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
                   <soapenv:Header/>
                   <soapenv:Body>
                      <web:refillAccountRequest>
                         <web:username>test@netader.com</web:username>
                         <web:password>#$JHJ5456</web:password>
                         <web:requestNo>25165156</web:requestNo>
                         <web:amount>200</web:amount>
                         <web:currency>EGP</web:currency>
                         <web:customerAccountNo>555565</web:customerAccountNo>
                         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
                         <!--Optional:-->
                         <web:terminalId>200</web:terminalId>
                      </web:refillAccountRequest>
                   </soapenv:Body>
                </soapenv:Envelope>"""

response = requests.GET(url,data=body,headers=headers)
print response.content   

<?php

$username =Test@gmail.com;
$password ='#Tests!123456Test!';
$requestNo =4083 ;
$amount =1;
$currency ='EGP';
$customerAccountNo =20266554438;
$requestHash ='e33732d47e3bd687bc6e1025043b1a37';
$terminalId =200;

$client = new SoapClient('https://www.ocstaging.net/webservice/refillAccount.wsdl');

$params = array(
	'username'=>$username,
	 'password'=>$password, 
	 'requestNo'=>$requestNo, 
	 'amount'=>$amount,
	 'currency'=>$currency,
	 'customerAccountNo'=>$customerAccountNo,
	 'requestHash'=>$requestHash,
	  'terminalId'=>$terminalId
	);

 $myXMLData = $client->__soapCall('refillAccount', array($params));

echo "<pre>";
  echo var_dump($myXMLData);
echo "<pre>";

?>

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class Send_XML_Post_Request_1 {
 public static void main(String[] args) {
 try {
 String url = "https://www.ocstaging.net/webservice/refillAccount.wsdl";
 URL obj = new URL(url);
 HttpURLConnection con = (HttpURLConnection) obj.openConnection();
 con.setRequestMethod("GET");
 con.setRequestProperty("Content-Type","application/soap+xml; charset=utf-8");
 String countryCode="Canada";
 String xml = "<soapenv:Envelope xmlns:soapenv=
 http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
   <soapenv:Header/>
   <soapenv:Body>
      <web:refillAccountRequest>
         <web:username>test@netader.com</web:username>
         <web:password>#$JHJ5456</web:password>
         <web:requestNo>25165156</web:requestNo>
         <web:amount>200</web:amount>
         <web:currency>EGP</web:currency>
         <web:customerAccountNo>555565</web:customerAccountNo>
         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
         <!--Optional:-->
         <web:terminalId>200</web:terminalId>
      </web:refillAccountRequest>
   </soapenv:Body>
</soapenv:Envelope>";
 con.setDoOutput(true);
 DataOutputStream wr = new DataOutputStream(con.getOutputStream());
 wr.writeBytes(xml);
 wr.flush();
 wr.close();
 String responseStatus = con.getResponseMessage();
 System.out.println(responseStatus);
 BufferedReader in = new BufferedReader(new InputStreamReader(
 con.getInputStream()));
 String inputLine;
 StringBuffer response = new StringBuffer();
 while ((inputLine = in.readLine()) != null) {
 response.append(inputLine);
 }
 in.close();
 System.out.println("response:" + response.toString());
 } catch (Exception e) {
 System.out.println(e);
 }
 }
} 



Method Name:

Get Request Status (Query Refill Request)


Request Flow
  • Funding channel enters the request reference number
  • Bitaqaty Business takes the request number entered and returns back the latest response of thisrequest.

Technical Considerations


Request Parameters

Parameter Name Data Type Description Validation
username String Web service dashboard username
password String Web service dashboard password
requestNo String A request reference number Unique
requestHash String MD5 digest for a string, composed as follows:
MD5(username + requestNo +OneCard_Key)
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Validation
responseCode String Response Code, refer to Response Codes
responseMessage String Response message for requested transaction
Code Examples :


     

 function soap() {
            var xmlhttp = new XMLHttpRequest();
            xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/refillAccount.wsdl', true);
            // build SOAP request
            var sr =
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
   <soapenv:Header/>
   <soapenv:Body>
      <web:queryRefillAccountRequest>
         <web:username>test@gmail.com</web:username>
         <web:password>$SS5151612</web:password>
         <web:requestNo>5898781</web:requestNo>
         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
      </web:queryRefillAccountRequest>
   </soapenv:Body>
</soapenv:Envelope>';

            xmlhttp.onreadystatechange = function () {
                if (xmlhttp.readyState == 4) {
                    if (xmlhttp.status == 200) {
                        alert('done. use firebug/console to see network response');
                    }
                }
            }
            // Send the POST request
            xmlhttp.setRequestHeader('Content-Type', 'text/xml');
            xmlhttp.send(sr);
            // send request
            // ...
        }

import requests
url="https://www.ocstaging.net/webservice/refillAccount.wsdl"
#headers = {'content-type': 'application/soap+xml'}
headers = {'content-type': 'text/xml'}
body = """<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
   <soapenv:Header/>
   <soapenv:Body>
      <web:queryRefillAccountRequest>
         <web:username>test@gmail.com</web:username>
         <web:password>$SS5151612</web:password>
         <web:requestNo>5898781</web:requestNo>
         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
      </web:queryRefillAccountRequest>
   </soapenv:Body>
</soapenv:Envelope>"""

response = requests.GET(url,data=body,headers=headers)
print response.content   

<?php

echo $username = 'test@gmail.com'; 
echo $password = '$DRT266Y8545';
echo $requestNo = '15651561651';
echo $requestHash = 'a516s5dd5d4df1dfef4e5f42'; 


$client = new SoapClient('http://Bitaqaty Business.n2vsb.com/webservice/refillAccount.wsdl');


$params = array(

	 'username'=>$username,
	 'password'=>$password,
	 'requestNo'=>$requestNo,
	 'requestHash'=>$requestHash,
	);

 $myXMLData = $client->__soapCall('queryRefillAccount', array($params));

echo "<pre>";
echo $myXMLData; echo "<br>";
echo "<pre>";

?>

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class Send_XML_Post_Request_1 {
 public static void main(String[] args) {
 try {
 String url = "https://www.ocstaging.net/webservice/refillAccount.wsdl";
 URL obj = new URL(url);
 HttpURLConnection con = (HttpURLConnection) obj.openConnection();
 con.setRequestMethod("GET");
 con.setRequestProperty("Content-Type","application/soap+xml; charset=utf-8");
 String countryCode="Canada";
 String xml = "<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="https://www.netader.com/webservice">
   <soapenv:Header/>
   <soapenv:Body>
      <web:queryRefillAccountRequest>
         <web:username>test@gmail.com</web:username>
         <web:password>$SS5151612</web:password>
         <web:requestNo>5898781</web:requestNo>
         <web:requestHash>sdsd454sd4s564s54s54ds54dwdwd45</web:requestHash>
      </web:queryRefillAccountRequest>
   </soapenv:Body>
</soapenv:Envelope>";
 con.setDoOutput(true);
 DataOutputStream wr = new DataOutputStream(con.getOutputStream());
 wr.writeBytes(xml);
 wr.flush();
 wr.close();
 String responseStatus = con.getResponseMessage();
 System.out.println(responseStatus);
 BufferedReader in = new BufferedReader(new InputStreamReader(
 con.getInputStream()));
 String inputLine;
 StringBuffer response = new StringBuffer();
 while ((inputLine = in.readLine()) != null) {
 response.append(inputLine);
 }
 in.close();
 System.out.println("response:" + response.toString());
 } catch (Exception e) {
 System.out.println(e);
 }
 }
} 

Response Codes


Valid Requests:

Response Description
00 VALID_REQUEST


Missing Parameters:

Response Description
101 MISSED_PAYMENT_REQUEST_USERNAME
102 MISSED_PAYMENT_REQUEST_PASSWORD
103 MISSED_PAYMENT_REQUEST_REQUEST_NUMBER
104 MISSED_PAYMENT_REQUEST_AMOUNT
105 MISSED_PAYMENT_REQUEST_CURRENCY
106 MISSED_PAYMENT_REQUEST_CUSTOMER_ACCOUNT_NUMBER
107 MISSED_PAYMENT_REQUEST_REQUEST_HASH


Invalid Parameters:

Response Description
201 INVALID_PAYMENT_REQUEST_AMOUNT
202 INVALID_PAYMENT_AGENT
203 INVALID_CUSTOMER
204 INVALID_CURRENCY
205 INVALID_HASHCODE
206 INVALID_REQUEST_NUMBER
300 AMOUNT_EXCEEDS_CURRENT_BALANCE
301 REQUEST_NOT_FOUND

Server Errors:

Response Description
302 SERVICE_NOT_AVAILABLE
303 INTERNAL_SERVER_ERROR