Quomo.digital API Documentation For Deposit

This documents is Payment Gateway Interface Specification for Merchants and, its aimed to connect with the merchant system to Quomo.digital Payment Gateway System via multiple currencies at the moment.

Interested Reader of this document would be developers and testers of Merchant System. HTTP protocol and JSON format are adopted for data interaction between Merchant and Quomo.digital payment gateway. This API integration is not allow to test with POSTMAN Integrated Tools and other similar. Please use CURL POST to integrate with the system.

Integration diagram

1.0 API Credential

Merchant would need below credential to integrate with Quomo.digital System. 

• API_USER_NAME (Must request to Quomo.digital Administrator)
• API_PASSWORD (Must request to Quomo.digital Administrator)
• MD5_KEY (Must request to Quomo.digital Administrator)
• MERCHANT_ID (Must request to Quomo.digital Administrator)
• BUSINESS_EMAIL (Merchant must provide. This is the email address when you register with Quomo.digital )
• WEBSITE_URL (Merchant must provide. This is the website address when you register with Quomo.digital )
• Quomo.digital_API_POST_URL (Must request to Quomo.digital Administrator)

2.0 Digital Signature 

To ensure the integrity and authenticity of request parameters transmitted to Quomo.digital payment gateway, MD5 are adopted to sign the plaintext of the request message and the signed data will be set as a field of request message for verification purpose of Quomo.digital payment gateway. MD5 key to sign request message shall be agreed and set during merchant registration with Quomo.digital Payment Gateway.

Build the plaintext to sign as the order of MD5 key plus All Parameters within the request message except the sign_data field. Please make sure the parameters of request message follow a specific order and no space or any characters shall be inserted in between. Encrypt the above composed signature string by MD5 key to get sign_data and set the value to sign_data field of request message.

2.1 AES encryption for Visa/Master method

AES encryption uses ECB mode(128-bit keys) and encrypted values must be encoded and transmitted with Base64. 

To encrypt the data with APIkey that given by quomo for below 4 parameters:

AES encryption:
“card_number”: “nFrfBUFEVazHuyv9iyoSc22yTYAqAbXj258YO4wcCCs==”,

“card_month”: “o9dc1kX0/5ByMWQmc0HXhg==”,

“card_year”: “0wxonR/51dAhmEWlrCCzsA==”,

“card_cvv”: “UYKKU4ICWAi2C3nBNsR+lg==”,

2.2  Deposit’s sign_data Combination

Combination of md5_key + merchant_id + business_email + product_name + order_id + deposit_method_id + bank_id + deposit_amount + currency + card_number + card_month + card_year + card_cvv + customer_name + customer_ip + customer_email + customer_phone_no + customer_address + note + website_url + request_time + success_url + fail_url + callback_noti_url will become sign_data and put it into md5 and change it into Uppercase.

Original signature string : 
APIKEYMD5484631345B1745B0999FE484631345b209a01c5e631ACB1000004MRYSmarN/AN/AN/AN/Athttp://yourwebsite.com1528863233http://web.com/depositsuccess
http://web.com/depositfailhttp://web.com/depositcallbacknoti 
Converted MD5 sign_data:
0F92406B35DDDFAC57F7C6F64C97C35D

/***Sample Code for "Original signature string" convert to sign_data***/
var sign_data = strtoupper(hash('md5', 'Original signature string'));

3.0 Submit Parameters for Deposit Payment

• Request Url : api/fundin/deposit
• Request method : POST
• *Remark : When Submit the Deposit transaction, Don’t forget to include API_USER_NAME and API_PASSWORD in your CURL POST 
  (Example: curl_setopt($curl, CURLOPT_USERPWD, API_USER_NAME . ‘ : ‘ . API_PASSWORD) 😉

Note : All Parameters as shown below must include when your post. Otherwise it will show error. Some parameters can leave as Optional (Blank Value). See in below description table.

Sample Request

var requestParams = '{
"merchant_id":"13041720",
"business_email":"[email protected]",
”product_name”:“Toy”,
"order_id":"5a5c2a788ba25",
"deposit_method_id":"4",
"bank_id":"CIMB",
"deposit_amount":"200", 
"currency":"MYR",
"customer_name":"Jake",
“card_number”:”N/A”,
“card_month”:” N/A”,
“card_year”:” N/A”,
“card_cvv”:” N/A”,
”customer_name“:”Jake”,
“customer_ip”:”34.55.67.124”,
"customer_email":"[email protected]",
"customer_phone_no":"09450050331",
"customer_address":"2211 N First Street, Building 17",
"note":"Your Note Here",
"website_url":"https://yourwebsite.com",
"request_time":1516186610,
"success_url":https://yourwebsite.com/depositsuccess
"fail_url":https://yourwebsite.com/depositfail
"callback_noti_url":https://yourwebsite.com/depositcallbacknoti
"sign_data":"7E052FC01EC8CBA22F0704331CC0A66A"
}';
/*** Eample Convert "requestParams to Array and add into CURLOPT_POSTFIELDS ***/
var arrayPost = array('requestParams' => 'requestParams'); /*request parameter*/
curl_setopt($curl, CURLOPT_POSTFIELDS, arrayPost); 

Request Parameters Description for Deposit Payment

All of Your Deposit Verification Process are Passed (no error in your submitted data), Quomo.digital will send back to you below response parameters message.

{ 
"errCode":0, 
"status":success, 
"order_id":OID5d5a1eb8d7f71, 
"next_action":"redirect", 
"redirect_url":"https://Quomo.digital.com/redirect?refid=130417201522128216" 
}

• Please use redirect_url to go to Online Banking process Page.
• After Customer has been logined and made the payment was successful, Quomo.digital will send back the response parameters message via callback_noti_url

4.0 What is callback_noti_url?

callback_noti_url is the url that Quomo.digital will notify to merchant’s server side via HTTP request by using POST Method, or we can refer to say as Server to Server calls. The main purpose of having callback_noti_url is to enable Quomo.digital to directly notify merchant’s application when a payment has been made successfully. Since this is a server to server call, merchant will be able to secure the system by implementing IP whitelist and other measures to eliminate possible fraud attempts

4.1 Callback Notification Mechanism

After the process of payment uploaded by the Merchant System, response parameters will be sent to merchant via callback_noti_url.Once merchant received the result, merchant must sent back the acknowledgement response to Quomo.digital payment gateway. Eg: return array(‘received’ => ‘Yes’); After Quomo.digital received return “Yes” from Merchant, the page will redirect to success_url or fail_url.

Callback’s sign_data Combination

Combination of MD5_KEY + merchant_id + order_id + deposit_method_id + currency will become sign_data and change it into Uppercase and send as response message with others parameters.

Original signature string : xbc32080Z130417205ad691a92a8431CNY
Converted MD5 sign_data: 2DD9BEEC7984C6948CA3D93073985161

Sample Callback Response

requestParams = {
"merchant_id": "13041720",
"transaction_id": "130417201803271522119269",
"order_id": "5a5c2a788ba25",
"bank_id": "BJRCB",
"deposit_method_id": "b",
"deposit_amount": "200.00",
"merchant_fee_percent": "2.5",
"net_amount": "195.00",
"currency": "CNY",
"order_status": "Successful",
"sign_data": "2DD9BEEC7984C6948CA3D93073985161" }

5.0 Submit Parameters for Order Status Enquiry

• Request Url : checkfororderstatus
• Request method : POST
• *Remark : When Submit the Deposit transaction, Don’t forget to include API_USER_NAME and API_PASSWORD in your CURL POST 
  (Example: curl_setopt($curl, CURLOPT_USERPWD, API_USER_NAME . ‘ : ‘ . API_PASSWORD));

Note : All Parameters as showen below must include when your post. Otherwise it will show error. Some parameters can leave as Optional (Blank Value). See in below description table.

5.1 Order Status Enquiry’s sign_data Combination

Combination of md5_key + merchant_id + order_id will become sign_data and put it into md5 and change it into Uppercase.

Request Parameters Description for Order Status Enquiry

5.2 Order Status Enquiry Response sign_data Combination

Combination of md5_key + merchant_id + order_id + transaction_id + transaction_type_id + transaction_amount + order_status will become sign_data and put it into md5 and change it into Uppercase.

Sample Response

requestParams = {
"merchant_id": "13041720",
"transaction_id": "130417201803271522119269",
"order_id": "5a5c2a788ba25",
"transaction_amount": "195.00",
"transaction_type_id": "Deposit",
"order_status": "Successful",
"sign_data": "2DD9BEEC7984C6948CA3D93073985161" }

6.0 Reference Table

Error code

Deposit(FundIn) errCode and error Description

Deposit payment method code

Deposit Payment Method

IDR Bank List

VND Bank List

THB Bank List

MYR Bank List

INR Bank List

PHP Bank List

Visa/Master Currency Codes

PHP Sample Code For Deposit Payment Submit

/** * *Request Url : /api/fundin/deposit
*Request method : POST
* */  
define('API_USER_NAME','[email protected]');
define('API_PASSWORD','123456xyz'); 
define('API_POST_URL', 'https://Quomo.digital/api/fundin/deposit');
$md5_key = 'xbc32080Zdx';
$merchant_id = '13041720';
$product_name = ‘Toy’;
$deposit_method_id:’5’,
$bank_id:"N/A",
$deposit_amount":'200 ', 
$currency":'MYR',
$customer_name":'Jake',
$card_number”: 'nFrfBUFEVazHuyv9iyoSc22yTYAqAbXj258YO44JhCs=',
$card_month”: 'o9dc1kX0/5ByMWQmc0HXhg==',
$card_year: '0wxonR/51dAhmEWlrCCzsA==',
$card_cvv: ' UYKKU4ICWAi2C3nBNsR+lg==',
$customer_name: 'Jake',
$customer_ip”:”34.55.67.124”,
$business_email = '[email protected]';
$successUrl = "https://yourweb.com/depositsuccess";
$failUrl = "https://yourweb.com/depositfail";
$callbackNotiUrl = "https://yourweb.com/depositcallbacknoti";
$website_url = "https://yourweb.com";
$order_id = uniqid();
$deposit_method_id = $_POST['deposit_method_id']; //b - Online Banking
$bank_id = $_POST['bank_id'];
$deposit_amount = $_POST['deposit_amount'];
$currency = $_POST['currency'];
$customer_name = $_POST['customer_name'];
$customer_email = $_POST['customer_email'];
$customer_phone_no = $_POST['customer_phone_no'];
$customer_address = $_POST['customer_address'];
$note = $_POST['note'];
$request_time = time();//Unix Timestamp
$success_url = $successUrl; 
$fail_url = $failUrl;  
$callback_noti_url= $callbackNotiUrl;  

/***Make Signature***/
$signature = $md5_key.''.$merchant_id.''.$business_email.''.$order_id.''.$deposit_method_id.''.$bank_id.''.$deposit_amount.''.$currency.''.$customer_name.'
'.$customer_email.''.$customer_phone_no.''.$customer_address.''.$note.''.$website_url.''.$request_time.'
'.$success_url.''.$fail_url.''.$callback_noti_url;

/***change signature to UpperCase***/
$signData = strtoupper(hash('md5', $signature));

/***Create Request as Json Format***/
$requestParams = '{"merchant_id":"'.$merchant_id.'","business_email":"'.$business_email.'","order_id":"'.$order_id.'",
"deposit_method_id":"'.$deposit_method_id.'","bank_id":"'.$bank_id.'","deposit_amount":"'.$deposit_amount.'","currency":"'.$currency.'","customer_name":"'.$customer_name.'",
"customer_email":"'.$customer_email.'","customer_phone_no":"'.$customer_phone_no.'","customer_address":"'.$customer_address.'",
"note":"'.$note.'","website_url":"'.$website_url.'","request_time":"'.$request_time.'","success_url":"'.$success_url.'",
"fail_url":"'.$fail_url.'","callback_noti_url":"'.$callback_noti_url.'","sign_data":"'.$signData.'"}';

/*** Put $requestParams in requestParams to create Array ***/
$arrayPost = array('requestParams' => $requestParams); //request parameter

/*** POST WITH CURL Form ***/ 
$curl = curl_init(INRPAYS_API_POST_URL);  
curl_setopt($curl, CURLOPT_HEADER, 0);
curl_setopt($curl, CURLINFO_HEADER_OUT, 1);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST | CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, API_USER_NAME . ':' . API_PASSWORD);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, FALSE);  
curl_setopt($curl, CURLOPT_POSTFIELDS, $arrayPost); 

$result = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);

if (empty($result)) {
return array(
'status' => $status,
'error' => $error);}
}
$res = json_decode($result);
if($res->errCode == 0)  
{ 
ob_start();
header('Location: ' . $res->redirect_url);  
exit();
} 
else{ echo $res->error;}  

PHP Sample Code For Callback Receive.

if(isset($_POST))
{ 
/*Receive Callback Parameters*/
$req = json_decode($_POST['requestParams']);

/*Create and open log file*/
$logFile = "callback.log";
$file = fopen($logFile, 'a') or die("can't open log file"); 
/*Write Parameters to Log or update database*/
fwrite($file, "merchant_id : ". $req->merchant_id ."\n");
fwrite($file, "transaction_id : ". $req->transaction_id ."\n");
fwrite($file, "order_id : ". $req->order_id ."\n");
fwrite($file, "bank_id : ". $req->bank_id ."\n");
fwrite($file, "deposit_method_id : ". $req->deposit_method_id ."\n");
fwrite($file, "deposit_amount : ". $req->deposit_amount ."\n");
fwrite($file, "merchant_fee_percent : ". $req->merchant_fee_percent ."\n");
fwrite($file, "net_amount : ". $req->net_amount ."\n");
fwrite($file, "currency : ". $req->currency ."\n");
fwrite($file, "order_status : ". $req->order_status ."\n");
fwrite($file, "sign_data : ". $req->sign_data ."\n");

fclose($file);
return array('received' => 'Yes');

}