API Documentation for Fundout

Chapter 1 Overview

This document is the Payment Gateway Interface Specification for Quomo payment System.

It describes the interface details between online merchant and Quomo payment gateway. 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 payment gateway. Details of API specification shall be shown as below

Chapter 2 Digital Signature

To ensure the integrity and authenticity of request parameter transmitted to Quomo payment gateway, RSA algorithm 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 payment gateway. RSA private key to sign request message shall be agreed and set during merchant registration with Quomo payment gateway.

Both private key and public key are necessary for RSA signature. Both private key and public key are generated with OPENSSL by merchant. Merchant and Quomo need to exchange their own public key. Therefore, Merchant uses Quomo public key and Merchant private key.

During the merchant sending the pre-sign string when requesting, the merchant private key and the pre-sign string are used in the RSA signature algorithm by the RSA signature function to get the result string.

After receiving the pre-sign string during responding from Quomo system, the Quomo public key, the pre-sign string and the parameter “signData” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.

Chapter 3 Interface Specification

3.1 Query Account Balance

By calling to this API URL, merchant can query their account balance. Merchant system shall send the query message with correct parameters, Quomo digital will then reply with a response code and along with merchant’s current balance amount.

Payment Gateway API URL

https://www.quomo.digital/Payapi_Index_PBalance.html

Request parameters for Merchant to send to Quomo

Response parameters from Quomo

3.2 Submit Payout Transaction

Payment Gateway API URL

https://quomo.digital/Payapi_Index_TransdfUser.html

Request parameter for merchant to send to Quomo (Excel file format follow below sequence)

Response parameters from Quomo

3.3 Query Order Status

By calling to this API URL, merchant can query their payout order status. Merchant system shall send the query message with correct parameters, Quomo will then reply with a response code and along with merchant’s current order status.

Payment Gateway API URL

https://quomo.digital/Payapi_Orderenquiry_payout.html

Request parameters for Merchant to send to Quomo

Response parameters from Quomo

3.4 Query Order History

Payment Gateway API URL

http://quomo.digital/Payapi_Orderenquiry_orderhistory.html

Request parameters for Merchant to send to Quomo

Response parameters from Quomo

Chapter 4 Callback Mechanism

Callback URL shall be registered during merchant transaction send to Quomo system. After the business process of transaction uploaded by the Merchant System, transaction result will be sent to merchant by calling to the previously setup callback URL. And response of acknowledgement should be sent to Quomo payment gateway once merchant received transaction result. If above mentioned acknowledgement response are not sent by merchant, Quomo payment gateway shall send transaction result with certain time interval and max retry limit. If resend exceeds max retry limit, then transaction result will no longer being sent to merchant.

Parameters for callback request from Quomo System to Merchant

Parameters for callback response from Merchant

Appendix A

When the merchant signs with Quomo, it will be granted access right for the APIs. The API call that the merchant makes normally should contains MID and signature information. The digital signature used for the digital signature for this System supports RSA. Merchant and Quomo will exchange the public key for each side.

The typical use cases for the merchant’s private key during requests are:

• Payout
• Order Enquiry
  Please make sure combine the parameters in a correct declared order in the interface when generation the original signaturestring, otherwise wrong sign data will be generated.

1. Constructing Pre-sign String

• Choosing the parameters
  Get all the parameters. The parameters are converted into a set of name-value pairs. Keep those with no value. The “signData” key should not be included.
• Sorting
  The name-value pairs are sorted in the order of the sequence in requested parameters list.
• Concatenating
  Construct the string by concatenating the name value pair(‘name=value’) with the ampersand ‘&’•
• Signature Generation
  After the pre-signed string is constructed, it would be signed by the applicable signature method (e.g. RSA). The result is the digital signature that would be put into the parameter ‘signData’ . The parameter of ‘signData’ would be appended to the string. Append the previous result string to base address of Quomo API, then change It to json format and we will get the final string for the API call.
• Example Code (PHP):

$requestData = array(
"merchantId" => $merchantId, 
"merchantTransactionId" => $merchantTransactionId, 
"currencyCode" => $currencyCode,
"accountName" => $accountName,
"accountNum" => $accountNum,
"transactionAmount" => $transactionAmount,
"bankName" => $bankName,
"requestTime" => $requestTime,
"bankProv" => $val['bankProv,
"bankCity" => $bankCity,
"callback" => $callback
);

function signMsg($array){
$msg = "";
$i = 0;
foreach ($array as $key => $val) {
if($i == 0 ){
$msg = $msg."$key=$val"; }
else {$msg = $msg."&$key=$val"; } 
$i++; }
return $msg; }

$preSignString = signMsg($requestData);

function rsaSign($data, $private_key) {
//formatting
$private_key=str_replace("-----BEGIN PRIVATE KEY-----","",$private_key);
$private_key=str_replace("-----END PRIVATE KEY-----","",$private_key); 
$private_key=str_replace("\n","",$private_key);
$private_key="-----BEGIN RSA PRIVATE KEY-----".PHP_EOL .wordwrap($private_key, 64, "\n", true). PHP_EOL."-----END RSA PRIVATE KEY-----";
$res = openssl_pkey_get_private ( $private_key );

if ($res) {
openssl_sign($data, $sign, $res, OPENSSL_ALGO_SHA1); }
else {
"The format of your private_key is incorrect!"; 
exit ();
}

openssl_free_key ( $res );
$sign = base64_encode ( $sign ); 
return $sign; }
$signData = rsaSign($preSignString, $privateKey); //Merchant’s Private Key
$finalrequest = array( 
"merchantId" => $merchantId,
"merchantTransactionId" => $merchantTransactionId, 
"currencyCode" => $currencyCode,
"accountName" => $accountName,
"accountNum" => $accountNum, 
"transactionAmount" => $transactionAmount, 
"bankName" => $bankName,
"requestTime" => $requestTime, 
"bankProv" => $val['bankProv, 
"bankCity" => $bankCity, 
"callback" => $callback,
 "signData" => $signData
);

$finalrequestData = json_encode(finalrequest);

• Example of the pre sign String:

merchantId=99999&merchantTransactionId=15667877471566787747¤cyCode=RMB&accountName=XiaoMing& accountNum=9879988778868687687&transactionAmount=10&bankName=ICBC&requestTime=2015-01-23 14:27:30&bankProv=Guangzhou&bankCity=Guangzhou&callback=callback.com

Example Response from Quomo: (No Verification required)

{"responseCode":100,"responseMessage":"The order has been received successfully","merchantId":"10002","merchantTransactionId":"15667877471566787747"}

2. Verifying the Signature

Construct the string for signature verification

Only take the string from the response in JSON. Normally the values are already sorted by requested orders by the keys of all the JSON nodes. The JSON content should include the beginning and ending braces “{” and “}”, the quotation mark, etc.

Call the verification function

Call the verification function, passing in the string to be verified, Quomo public key, and signature. Decide if it will pass by the return value.

Example Code:

function verify($strData, $signature, $publicKey) {
if (!openssl_get_publickey($publicKey)) { 
echo 'verifyTaiping openssl_get_publickey failed.'; 
return false; } 
$base64Signature = base64_decode($signature); 
if (!openssl_verify($strData, $base64Signature, $publicKey, OPENSSL_ALGO_SHA1)) {
echo 'openssl_verify failed.'; return false; } 
return true; }

function signMsg($array){
$msg = "";
$i = 0;
foreach ($array as $key => $val) { 
if($i == 0 ){
$msg = $msg."$key=$val";
}else {
$msg = $msg."&$key=$val";}
$i++;} 
return $msg; }

$respdata= array(
'responseCode' => $responseCode,
'merchantId' => merchantId,
'merchantTransactionId' => $merchantTransactionId,
'currencyCode' => "RMB",
'accountName' => $accountName,
'accountNum' => $accountNum,
'transactionAmount' => $transactionAmount,
'bankName' => $bankName,
'transactionResult' => $transactionResult,
'failedReason' => $failedReason'
'completeTime' => $completeTime
);

$respdataFinal = signMsg($respdata); 
$res = verify($respdataFinal, $signData,$pubkey); // Verify if the signData match, uses Quomo public key

Example Response to Quomo: (No Verification required)

{"received":"100",""merchantId":"1234567","merchantTransactionId":"778899887 05ac80"}

Notes:

For Java developers, we need to removed the header, footer, , and space from the pkcs8 private key outout in the console. For.NET and PHP developer, there is no need for the pkcs8 operation.

Appendix B

Response Code Table

Appendix C

MYR Bank Name List

THB Bank Name List

VND Bank Name List

IDR Bank Name List

Appendix D

Currency Code