Quick Start

Last updated: Mars 03th, 2019

System Overview


Bitaqaty Business system offers online shopping malls an option to add Bitaqaty Business products to their malls. Based on the agreement made with Bitaqaty Business merchant relationship department, a specific list of Bitaqaty Business local products will be allowed to be purchased on POS site by their customers

Upon signing the contract with Bitaqaty Business, POS site is handed the following keys for the staging environment:

Upon signing the contract with Bitaqaty Business

Upon signing the contract with Bitaqaty Business, POS site is handed the following keys for the staging environment:

  • POS username which has two roles:
    • Acts as the username for the POS site while viewing POS dashboard in Bitaqaty Business system.
    • Used as POS site identifier in all communication between Bitaqaty Business and the POS site
  • Password: it should be used to view POS dashboard on Bitaqaty Business system.
  • Secret Key a key shared between Bitaqaty Business and the POS site; it will be used by the POS site in generating the POS site signature (hash code) and must not be communicated over http.

Product Type


Name Description
credential
  • item serial
  • username
  • secret
Serial
  • item serial
  • secret
Voucher
  • secret

Serial

  • item serial
  • secret

Credential

  • item serial
  • username
  • secret

VAT Type


Name Description
SG VAT Calculated on total product amount
SM VAT Calculated on different between EndUser Price and FaceValue
OS VAT in this case will be 0

API URLs


Point Of Sale URLs :

Point Of Sale Dashboard URLs :

Notes & Recommendations


  • Data synchronization or “retrieve product list” methods can be considered a high traffic operation – depending on the amount of products retrieved on response, hence it is recommended to cache response results and to call this method over long intervals such as daily or weekly basis.
  • “Purchase product” operation will be executed based on Bitaqaty Business system prices, hence if a product price was updated on Bitaqaty Business system after last time POS site performed data synchronization process, transaction will be executed on new prices, it is the POS site responsibility to take care of updated prices.
  • To avoid any inconvenience based on the above fact, “retrieve detailed product info” method should be called prior to “purchasing product” method to validate prices integrity and items availability.
  • Reconciliation process should take place on daily basis and for each POS machine.

API Methods

Retrieve Products List:


Method Name:

POSGetProductList


Description
Retrieve products list that assigned to your account by Bitaqaty Business


Request Flow
  • POS let you get full list of products that assigned to your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return list of products that assigned to yor account
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
signature MD5 Hash

MD5 (posUsername + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
productList list of product List of products objects, refer to below table 0..* List of Codes


Parameter Name Data Type Description Cardinality Mandatory Length
productCode long Bitaqaty Business product code 1 8
nameAr String Product name in Arabic 1 255
nameEn String Product name in English 1 255
productPrice double Product original price 1 8
productCurrency string Product currency 1 255
posPrice double POS site price 1 8
posCurrency string POS currency 1 255
available boolean
  • True :product is available at Bitaqaty Business system
  • False :product is not available at Bitaqaty Business system
1 1
merchantid Long Bitaqaty Business product code 1 8
merchantNameAr String Merchant name in Arabic 1 255
merchantNameEn String Merchant name in English 1 255
Code Examples :


     

function soap() {
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSGetProductListRequest>
<web:posUsername>Test6@hotmail.com</web:posUsername>
<web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
</web:POSGetProductListRequest>
</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/OneCardPOSSystem.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:POSGetProductListRequest>
<web:posUsername>Test@hotmail.com</web:posUsername>
<web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
</web:POSGetProductListRequest>
</soapenv:Body>
</soapenv:Envelope>"""

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

<?php

$posUsername =Test@gmail.com;
$signature ='5s1a65sa1casc1as5c11sc';


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

$params = array(
	'posUsername'=>$username,
	 'signature'=>$password
	);

$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/OneCardPOSSystem.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:POSGetProductListRequest>
<web:posUsername>Test@gmail.com</web:posUsername>
<web:signature>5s1a65sa1casc1as5c11sc</web:signature>
</web:POSGetProductListRequest>
</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);
}
}
} 


Retrieve Products ID :


Method Name:

POSGetProductID


Description
Retrieve products IDs of that assigned to your account by Bitaqaty Business


Request Flow
  • POS let you get full list of products ID's that assigned to your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return list of products ID's that assigned to yor account
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
signature MD5 Hash

MD5 (posUsername + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
productID list of product List of products ID's , refer to below table 0..* List of Products


Parameter Name Data Type Description Cardinality Mandatory Length
productCode long Bitaqaty Business product code 1 8
available boolean
  • True :product is available at Bitaqaty Business system
  • False :product is not available at Bitaqaty Business system
1 1
Code Examples :


     
  
  function soap() {
  var xmlhttp = new XMLHttpRequest();
  xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSGetProductIDRequest>
  <web:posUsername>Test6@hotmail.com</web:posUsername>
  <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
  </web:POSGetProductIDRequest>
  </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/OneCardPOSSystem.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:POSGetProductIDRequest>
  <web:posUsername>Test@hotmail.com</web:posUsername>
  <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
  </web:POSGetProductIDRequest>
  </soapenv:Body>
  </soapenv:Envelope>"""
  
  response = requests.GET(url,data=body,headers=headers)
  print response.content

  <?php
  
  $posUsername =Test@gmail.com;
  $signature ='5s1a65sa1casc1as5c11sc';
  
  
  $client = new SoapClient('https://www.ocstaging.net/webservice/OneCardPOSSystem.wsdl');
  
  $params = array(
  	'posUsername'=>$username,
  	 'signature'=>$signature
  	);
  
  $myXMLData = $client->__soapCall('POSGetProductIDRequest', 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/OneCardPOSSystem.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:POSGetProductIDRequest>
  <web:posUsername>Test@gmail.com</web:posUsername>
  <web:signature>5s1a65sa1casc1as5c11sc</web:signature>
  </web:POSGetProductIDRequest>
  </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);
  }
  }
  }
               



Retrieve Detailed Product Info:


Method Name:

POSGetProductInfo


Description
Retrieving a product information and status


Request Flow:
  • POS let you get a detailed info about product that assigned to your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about product
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
productCode Long Bitaqaty Business product code 1 Yes 8
signature MD5 Hash

MD5 (posUsername +productCode + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
productCode long Bitaqaty Business product code 0..1 8
nameAr string Product name in Arabic 0..1 255
nameEr string Product name in English 0..1 255
productPrice double Product original price 0..1 8
productCurrency String Product currency 0..1 255
posPrice double POS site price 0..1 8
posCurrency string POS currency 0..1 255
Available boolean
  • True : product is available at Bitaqaty Business System
  • false : product is not available
0..1 1
merchantNameAr string Merchant name in Arabic 0..1 255
merchantNameEn string Merchant name in English 0..1 255
Code Examples :


     
                
                function soap() {
                var xmlhttp = new XMLHttpRequest();
                xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSGetProductInfoRequest>
                <web:posUsername>Test6@hotmail.com</web:posUsername>
                <web:productCode>565446445546</web:productCode>
                <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
                </web:POSGetProductInfoRequest>
                </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/OneCardPOSSystem.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:POSGetProductInfoRequest>
                <web:posUsername>Test@hotmail.com</web:posUsername>
                <web:productCode>565446445546</web:productCode>
                <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
                </web:POSGetProductInfoRequest>
                </soapenv:Body>
                </soapenv:Envelope>"""
                
                response = requests.GET(url,data=body,headers=headers)
                print response.content

        <?php
        
        $posUsername =Test@gmail.com;
        $signature ='5s1a65sa1casc1as5c11sc';
        $productCode ='4564565465';
        
        
        $client = new SoapClient('https://www.ocstaging.net/webservice/OneCardPOSSystem.wsdl');
        
        $params = array(
        	'posUsername'=>$username,
        	 'signature'=>$signature,
        	 'productCode'=>$productCode
        	);
        
        $myXMLData = $client->__soapCall('POSGetProductInfo', 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/OneCardPOSSystem.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:POSGetProductInfoRequest>
                <web:posUsername>Test@gmail.com</web:posUsername>
                <web:productCode>565446445546</web:productCode>
                <web:signature>5s1a65sa1casc1as5c11sc</web:signature>
                </web:POSGetProductInfoRequest>
                </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);
                }
                }
                } 

POS Check Balance:


Method Name:

POSCheckBalance


Description
checking your POS site account balance

Request Flow:
  • POS let you Check Balance of your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about your Balance
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
signature MD5 Hash

MD5 (posUsername + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
balance double POS balance 0..1 8
Currency String POS currency 0..1 255
Code Examples :


     
                
                function soap() {
                var xmlhttp = new XMLHttpRequest();
                xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSCheckBalanceRequest>
                <web:posUsername>Test6@hotmail.com</web:posUsername>
                <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
                </web:POSCheckBalanceRequest>
                </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/OneCardPOSSystem.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:POSCheckBalanceRequest>
                <web:posUsername>Test@hotmail.com</web:posUsername>
                <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
                </web:POSCheckBalanceRequest>
                </soapenv:Body>
                </soapenv:Envelope>"""
                
                response = requests.GET(url,data=body,headers=headers)
                print response.content

                <?php
                
                $posUsername =Test@gmail.com;
                $signature ='5s1a65sa1casc1as5c11sc';
                
                
                $client = new SoapClient('https://www.ocstaging.net/webservice/OneCardPOSSystem.wsdl');
                
                $params = array(
                	'posUsername'=>$username,
                	 'signature'=>$signature
                	);
                
                $myXMLData = $client->__soapCall('POSCheckBalance', 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/OneCardPOSSystem.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:POSCheckBalance>
                <web:posUsername>Test@gmail.com</web:posUsername>
                <web:signature>5s1a65sa1casc1as5c11sc</web:signature>
                </web:POSCheckBalance>
                </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);
                }
                }
                } 



Query by Transaction :


Method Name:

POSQueryByTransaction


Description
checking your tranaction status

Request Flow:
  • POS let you get a detailed info specific request
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about request
    • 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 Cardinality Mandatory Length
trxRefNumber String Transaction number generated and given by POS merchant 1 Yes 255
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
signature MD5 Hash

MD5 (posUsername + trxRefNumber + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
amount double Paid amount in POS Currency 0..1 8
currency String POS currency 0..1 255
secret String Item secret 0..1 255
serial String Item serial 0..1 255
username String Item username 0..1 255
productType int Purchased product type, refer to enum illustration in below table 0..1 32
trxDate Date Date of transaction 0..1 255
Code Examples :


     

function soap() {
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSQueryByTransactionRequest>
<web:posUsername>test@gmail.com</web:posUsername>
<web:trxRefNumber>HG5561651</web:trxRefNumber>
<web:signature>414sa5c156csc1sa5651sc56sa</web:signature>
</web:POSQueryByTransactionRequest>
</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/OneCardPOSSystem.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:POSQueryByTransactionRequest>
<web:posUsername>test@gmail.com</web:posUsername>
<web:trxRefNumber>HG5561651</web:trxRefNumber>
<web:signature>414sa5c156csc1sa5651sc56sa</web:signature>
</web:POSQueryByTransactionRequest>
</soapenv:Body>
</soapenv:Envelope>"""

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

<?php

$posUsername =Test@gmail.com;
$signature ='5s1a65sa1casc1as5c11sc';
$trxRefNumber ='FG156165615';


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

$params = array(
	'posUsername'=>$username,
	'trxRefNumber'=>$trxRefNumber,
	 'signature'=>$signature
	);

$myXMLData = $client->__soapCall('POSQueryByTransaction', 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 = "
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="https://www.netader.com/webservice">
<soapenv:Header/>
<soapenv:Body>
<web:POSQueryByTransactionRequest>
<web:posUsername>test@gmail.com</web:posUsername>
<web:trxRefNumber>HG5561651</web:trxRefNumber>
<web:signature>414sa5c156csc1sa5651sc56sa</web:signature>
</web:POSQueryByTransactionRequest>
</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);
}
}
} 



Purchase a Product :


Method Name:

POSPurchaseProduct

Description
performing a purchase product operation.


Request Flow
  • POS Main method is to purchase product from that whom assigned to your account upon contract
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about product that you purchase
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
productCode long he selected product code in Bitaqaty Business system 1 Yes 8
signature MD5 Hash

MD5 (posUsername + product Code + secretKey)

1 Yes 255
terminalId string POS terminal ID 1 No 255
trxRefNumber string by your side (could be terminal ID + timestamp) 1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
errorCode String in case of error Response Code, refer to Response Codes 0..1 -
balance double POS site balance after performing purchase operation 0..1 8
currency String POS currency 0..1 255
secret String Item secret 0..1 255
serial string Item serial 0..1 255
username string Item username 0..1 255
productType int Purchased product type, refer to enum illustration in below table 0..1 32
amount double Paid amount in POS site currency 0..1 8
trxRefNumber String trxRefNumber sent in the request 0..1 255
ocTrxRefNumber String Bitaqaty Business Transaction Number 0..1 255
requestDate Date Date of Request Sending 0..1 255

Note: In case of purchased product doesn’t include a username or serial the response of these fields will be “null”.

Code Examples :


     
            function soap() {
            var xmlhttp = new XMLHttpRequest();
            xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSPurchaseProductRequest>
            <web:posUsername>test@gmail.com</web:posUsername>
            <web:productCode>2626</web:productCode>
            <web:signature>65scssacc651c1cregrwsa6c5sa1c6sa5</web:signature>
            <!--Optional:-->
            <web:terminalId>300</web:terminalId>
            <!--Optional:-->
            <web:trxRefNumber>TRF5161515</web:trxRefNumber>
            </web:POSPurchaseProductRequest>
            </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/OneCardPOSSystem.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:POSPurchaseProductRequest>
            <web:posUsername>test@gmail.com</web:posUsername>
            <web:productCode>2626</web:productCode>
            <web:signature>65scssacc651c1cregrwsa6c5sa1c6sa5</web:signature>
            <!--Optional:-->
            <web:terminalId>300</web:terminalId>
            <!--Optional:-->
            <web:trxRefNumber>TRF5161515</web:trxRefNumber>
            </web:POSPurchaseProductRequest>
            </soapenv:Body>
            </soapenv:Envelope>"""
            
            response = requests.GET(url,data=body,headers=headers)
            print response.content

        <?php
        
        $posUsername =Test@gmail.com;
        $signature ='5s1a65sa1casc1as5c11sc';
        $productCode ='451615';
        $terminalId ='200';
        $trxRefNumber ='651565';
        
        
        $client = new SoapClient('https://www.ocstaging.net/webservice/OneCardPOSSystem.wsdl');
        
        $params = array(
        	'posUsername'=>$username,
        	'productCode'=>$productCode,
        	 'signature'=>$signature,
        	 'terminalId'=>$terminalId,
        	 'trxRefNumber'=>$trxRefNumber
        	);
        
        $myXMLData = $client->__soapCall('POSPurchaseProduct', 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 = "
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:web="https://www.netader.com/webservice">
            <soapenv:Header/>
            <soapenv:Body>
            <web:POSPurchaseProductRequest>
            <web:posUsername>test@gmail.com</web:posUsername>
            <web:productCode>2626</web:productCode>
            <web:signature>65scssacc651c1cregrwsa6c5sa1c6sa5</web:signature>
            <!--Optional:-->
            <web:terminalId>300</web:terminalId>
            <!--Optional:-->
            <web:trxRefNumber>TRF5161515</web:trxRefNumber>
            </web:POSPurchaseProductRequest>
            </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);
            }
            }
            } 



Retrieve Detailed Product With VAT :


Method Name:

POSGetProductWithVATInfoPosPrice

Description
Retrieving a product information with vat details and status.


Request Flow
  • POS let you get a detailed product information with vat details and status whitch assigned to your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about product with vat info
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
productCode long Bitaqaty Business product code 1 Yes 8
signature MD5 Hash

MD5 (posUsername + productCode + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1 1
productCode Long Bitaqaty Business product code 0..1 8
nameAr String Product name in Arabic 0..1 255
nameEn String Product name in English 0..1 255
vatValue double Value of VAT on product 0..1 8
vatType string Type of VAT on product 0..1 255
faceValue double Exact value of voucher 0..1 8
productPrice double Product original price 0..1 8
posCurrency String POS currency 0..1 255
Available boolean
  • True : product is available at Bitaqaty Business system
  • false : product is not available
0..1 1
merchantID String ID of Merchant 0..1 255
merchantNameAr String Merchant name in Arabic 0..1 255
merchantNameEn String Merchant name in English 0..1 255
Code Examples :


     
                
                function soap() {
                var xmlhttp = new XMLHttpRequest();
                xmlhttp.open('GET', 'https://www.ocstaging.net/webservice/OneCardPOSSystem.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:POSGetProductWithVATInfoPosPriceRequest>
                <web:posUsername>test@gmail.com</web:posUsername>
                <web:productCode>1221</web:productCode>
                <web:signature>ds15651s15s6511sadfsdsa5f6as1f</web:signature>
                </web:POSGetProductWithVATInfoPosPriceRequest>
                </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/OneCardPOSSystem.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:POSGetProductWithVATInfoPosPriceRequest>
                        <web:posUsername>test@gmail.com</web:posUsername>
                        <web:productCode>1221</web:productCode>
                        <web:signature>ds15651s15s6511sadfsdsa5f6as1f</web:signature>
                        </web:POSGetProductWithVATInfoPosPriceRequest>
                        </soapenv:Body>
                        </soapenv:Envelope>"""
                        
                        response = requests.GET(url,data=body,headers=headers)
                        print response.content

            <?php
            
            $posUsername =Test@gmail.com;
            $signature ='5s1a65sa1casc1as5c11sc';
            $productCode ='451615';
            
            $client = new SoapClient('https://www.ocstaging.net/webservice/OneCardPOSSystem.wsdl');
            
            $params = array(
            	'posUsername'=>$username,
            	'productCode'=>$productCode,
            	'signature'=>$signature
            
            	);
            
            $myXMLData = $client->__soapCall('POSGetProductWithVATInfoPosPrice', 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/OneCardPOSSystem.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:POSGetProductWithVATInfoPosPriceRequest>
            <web:posUsername>test@gmail.com</web:posUsername>
            <web:productCode>1221</web:productCode>
            <web:signature>ds15651s15s6511sadfsdsa5f6as1f</web:signature>
            </web:POSGetProductWithVATInfoPosPriceRequest>
            </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);
            }
            }
            } 

Retrieve List Of Detailed product With VAT :


Method Name:

POSGetProductWithVATList

Description
Retrieving a List of product information with vat details and status


Request Flow
  • POS let you get Retrieving a List of product information with vat details and status about product that assigned to your account
  • Bitaqaty Business validates the received parameters and sends back the response, upon:
    • Success: Bitaqaty Business return info about product
    • 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 Cardinality Mandatory Length
posUsername String The POS username defined in Bitaqaty Business System 1 Yes 255
signature MD5 Hash

MD5 (posUsername + secretKey)

1 Yes 255
Note: All parameters are required.

Response Parameters

Parameter Name Data Type Description Cardinality Mandatory Length
status boolean
  • True : method returned successfully
  • false : error
1
productCode Long Bitaqaty Business product code 0..1 8
nameAr String Product name in Arabic 0..1 255
nameEn String Product name in English 0..1 255
vatValue double Value of VAT on product 0..1 8
vatType string Type of VAT on product 0..1 255
faceValue double Exact value of voucher 0..1 8
productPrice double Product original price 0..1 8
posCurrency String POS currency 0..1 255
Available boolean
  • True : product is available at Bitaqaty Business system
  • false : product is not available
0..1 1
merchantID String ID of Merchant 0..1 255
merchantNameAr String Merchant name in Arabic 0..1 255
merchantNameEn String Merchant name in English 0..1 255
Code Examples :


     
    
    function soap() {
    var xmlhttp = new XMLHttpRequest();
    xmlhttp.open('GET', 'http://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:POSGetProductWithVATListRequest>
    <web:posUsername>test@gmail.com</web:posUsername>
    <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
    </web:POSGetProductWithVATListRequest>
    </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="http://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:POSGetProductWithVATListRequest>
    <web:posUsername>test@gmail.com</web:posUsername>
    <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
    </web:POSGetProductWithVATListRequest>
    </soapenv:Body>
    </soapenv:Envelope>"""
    
    response = requests.GET(url,data=body,headers=headers)
    print response.content

    <?php
    
    $username = 'test@gmail.com';
    $signature = 'a516s5dd5d4df1dfef4e5f42';
    
    
    $client = new SoapClient('http://Bitaqaty Business.n2vsb.com/webservice/refillAccount.wsdl');
    
    
    $params = array(
    
    	 'username'=>$username
    	 'signature'=>$signature,
    	);
    
    $myXMLData = $client->__soapCall('RetrieveListofdetailedproductwithVAT', 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 = "http://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:POSGetProductWithVATListRequest>
    <web:posUsername>test@gmail.com</web:posUsername>
    <web:signature>be24bb1a511d16ac45813366cadbf413</web:signature>
    </web:POSGetProductWithVATListRequest>
    </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
200 Success


Missing Parameters:


Response Description
101 MISSING_USERNAME
103 MISSING_SIGNATURE
107 MISSING_PRODUCT_CODE
112 MISSED_TERMINAL_ID
113 MISSED_REQUEST_ID
114 MISSED_DATE
115 MISSED_TRX_REF_SUCCESS_NUMS
116 MISSED_TRX_REF_NUMS_LIST
117 MISSED_TRX_REF_NUMS
118 MISSED_TRX_TOT_NUM
119 MISSED_TRX_TOT_AMT
120 MISSED_LAST_TRX_DATE


Invalid Parameters:


Response Description
201 INVALID_SIGNATURE
203 INVALID_POS_USERNAME
204 INVALID_POS_INTERNAL_ACCOUNT
208 INVALID_PRODUCT_CODE
209 INVALID_SELLABLE_PRODUCT
210 INVALID_TRX_REF_NUM
211 MISMATCHED_TRX_REF_NUMS
213 TRX_REF_NUMS_EXCEED_MAX
214 INVALID_TERMINAL_ID
215 INVALID_TRX_TOT_NUM
216 INVALID_TRX_TOT_AMT
217 MISMATCH_TRX_TOT_NUM
218 MISMATCH_TRX_TOT_AMT

Bitaqaty Business Errors:


Response Description
301 NO_SELLABLE_ITEMS
302 INSUFFICIENT_BALANCE
303 POS_REACHED_PURCHASING_LIMIT
304 SERVICE_NOT_AVAILABLE
305 INTERNAL_SYSTEM_ERROR
306 INVALID_PURCHASING_CHANNEL
307 DUPLICATE_REQUEST
309 NO_REQUESTS_FOUND
310 NO_INITIAL_REQUEST_FOUND