Introduction
Wowpay provides a web interface that allows integration with Merchant System which would like to accept online payment by 3D and non-3D credit card, direct debit and e-Wallet payments.This Merchant Integration Guide provides merchants with the necessary technical information to integrate their applications (Merchant Systems) with Wowpay.The manual contains message format required between Wowpay and Merchant System for various payment transaction types, namely Payment, Query and Reversal. It is intended as a technical guide for merchant developers and system integrators who are responsible for designing or programming the respective online applications to integrate with Wowpay
Pre-requisite
All merchants who would like to integrate with Wowpay must obtain a valid payment account from Wowpay. Upon payment account generated, Wowpay will provide credentials (merchant_code, merchant_id, username, password) to merchants to connect the APIs.
Payment Options
To start your online payment integration, you need to implement API calls from your server. This payment option request should be performed via Server-to-Server (webrequest) and post method.
Sending Payment Option request (Merchant System -> Wowpay)
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| merchant_code | a | 20 | y | provided by wowpay |
| username | a | 20 | y | provided by wowpay |
| password | a | 20 | y | provided by wowpay |
| merchant_id | an | 40 | y | provided by wowpay |
| currency | a | 3 | y | wowpay supports most of the major currencies |
| country | an | 30 | y | country code : "ALL" |
| product_code | an | 20 | y | default is "ALL". product code referring to the list of product parameter that wowpay will return in response. Refer 3.1 |
To start your online payment integration, you need to implement API calls from your server. This payment option request should be performed via Server-to-Server (webrequest) and post method.
API URL: http://api.wowpay/api/PayOption/Options
/* These details provided by Wowpay */
{
"merchant_code": "TESTMIDCODE",
"username": "TESTMIDCODE",
"password": "TESMIDCODE",
"merchant_id": f9a27d58-1172-4f7e-8da8-dacdf7662d56,
"currency": "THB",
"country": "ALL",
"product_code": "ALL"
}
Payment Option response (Wowpay -> Merchant System)
The following fields are the Payment information expected from Wowpay to Merchant System to perform an online payment transaction
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| req_datetime | AN | 50 | Y | Date & time in UTC : 2018-08-29T04:18:06.439112Z |
| payment_options[0] | ||||
| isdynamic_access | Boolen | Y | ||
| payment_optionid | AN | Y | GUID | |
| payment_type | A | 50 | Y | 1.CreditCard (Online 3D) 2.Online Banking 3.Offline PaymentOther payments type available upon request. |
| display_name | A | 20 | Y | You can use this to display the payment option name in your website. |
| request_method | A | 10 | Y | Http / Custom method to submit the payment request. (POST) |
| payment_options[0].payment_channels[0] | ||||
| payment_channels[0].payment_id | ANS | 15 | Y | Based on the user's payment selection It should be send in the Payment Request. |
| payment_channels[0].card_type | A | 16 | Y | Credit Card Type e.g. VISA/MASTERCARD/AMEX/JCB/DINERS *Only available as per request |
| payment_channels[0].channel_code | A | 17 | Y | |
| payment_channels[0].channel_name | A | 18 | Y | |
| payment_channels[0].request_url | AN | 200 | Y | Payment Request should be submitted to this url for this payment option: https://api.wowpay.net/api/pay |
| payment_channels[0].channel_id | AN | Y | GUID | |
| payment_channels[0].ProviderId | AN | Y | GUID | |
| payment_channels[0].iscredntialneed | Boolen | Y | ||
| payment_options[0].captureCard | N | Identifier for Capturing Card: 0 – None (if non card payment) 1 – CardDetails captured in Merchant Website 2 – In Wowpay page 3 – Bank / Provider Page | ||
| payment_options[0].display_order | N | 1 | Y | Indicate that the order information is display on merchant browser site. |
| payment_options[0].isasynchornous_payment | A | 10 | Y | False - PAY NOW (creditcard,directdebit,…) True - PAY LATER (ATM payment,OvertheCounter,…) |
| payment_options[0].currency | A | 3 | ||
| payment_options[0].country | AN | 30 | ||
| payment_options[0].ServiceCharge | N | 12(2) | ||
| payment_options[0].method_id | AN | GUID | ||
| payment_options[0].allowed | Boolen |
Request & Response
Sending Payment Request (Merchant System -> Wowpay)
The following fields are the Payment information expected from Merchant System to Wowpay in order to perform an online payment transaction. These parameters must be passed using POST method.
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| RequestSource | AN | 50 | Y | |
| Integrationtype | AN | 50 | Y | |
| is_webrq | Boolen | Y | ||
| language | A | 2 | Y | ISO 639-1 language Code for wowpay Payment Info Collection Page: EN |
| ex_merchantid | N | |||
| merchantid | AN | GUID | ||
| merchant_code | AN | 10 | ||
| requestid | AN | 10 | ||
| customerIP | AN | 20 | Y | Customer’s IP address captured by merchant system. |
| payment_Info[0] | ||||
| payment_Info[0].payment_ID | ANS | 15 | Y | Payment ID which is set by wowpay |
| payment_Info[0].merchant_txnid | AN | 16 | Y | Unique transaction ID/reference code assigned by merchant for each transaction (No duplicate merchant_txnid is allowed) |
| payment_Info[0].txn_amount | N | 12(2) | Y | Payment amount in 2 decimal places regardless whether the currency has decimal places or not.Please exclude “,” sign.(e.g. 1000.00 for IDR) |
| payment_Info[0].txn_Currency | A | 3 | Y | wowpay supports most of the major currencies |
| payment_Info[0].is_Installment | Boolen | O | Identifier for instalment entitlement: false – Not entitled for instalment true – Entitled for instalment | |
| payment_Info[0].installment_Period | N | 2 | O | Number of months for the instalment |
| payment_Info[0].capture_Card | N | 1 | O | Identifier for Capturing Card: 0 – None (Not CC) 1 – Merchant Website 2 – In wowpay page 3 – Bank / Provider Page |
| payment_Info[0].card_type | AN | 50 | ||
| payment_Info[0].merchant_Ref1,merchant_Ref2 | ANS | 16 | O | Additional data from merchant system that will be passed back to merchant in payment response |
| payment_Info[0].isstore_cardinfo | Boolen | |||
| payment_Info[0].customer_id | AN | 50 | ||
| payment_Info.card_info | ||||
| card_info.cardholder_Name | A | 16 | Y | Cardholder’s Name |
| card_info.card_No | N | 16 | Y | Credit Card Number used for payment authorization |
| card_info.cvv | N | 4 | Y | 3-4 digits Card Verification Value.Available on the back of credit card |
| card_info.card_Type | A | 16 | Y | VISA/MASTERCARD/AMEX/JCB/DINERS |
| card_info.exp_Month | N | 6 | Y | "Expiry date of credit card. Date format is MM, e.g.12 for December" |
| card_info.exp_Year | A | 16 | Y | "Expiry date of credit card. Date format is YYYY, e.g.2020 " |
| card_info.start_Month | A | 16 | O | "Date of Registering Credit Card available on the front of credit card “Member Since” Date format is MM, e.g.12 for December" |
| card_info.start_Year | A | 16 | O | "Date of Registering Credit Card available on the front of credit card “Member Since” Date format is YYYY, e.g.2020" |
| card_info.ExpDate | AN | 100 | ||
| card_info.StartDate | AN | 100 | ||
| order_info | ||||
| order_info.order_desc | AN | 50 | Y | Order Description |
| order_info.Item_list[0] | ||||
| Item_list[0].item_id | AN | 50 | Y | "Item index: ""1""" |
| Item_list[0].item_code | AN | 50 | Y | "e.g Hotel item Code: ""Hiltont001""" |
| Item_list[0].item_type | N | 10 | O | e.g Hotel item Type: “3” |
| Item_list[0].item_name | AN | 50 | Y | e.g Hotel item Name: “Hilton Hotel” |
| Item_list[0].item_desc | AN | 50 | Y | e.g Hotel item Description: “Miami Hilton” |
| Item_list[0].item_amount | N | 50 | Y | e.g Hotel item Amount: “100” |
| customer_info[0] | ||||
| customer_info[0].first_name | AN | 50 | Y | Customer’s first name |
| customer_info[0].last_name | AN | 50 | Y | Customer’s last name |
| customer_info[0].full_name | AN | 100 | ||
| customer_info[0].mobile | N | 20 | Y | Customer’s Contact Number |
| customer_info[0].email | AN | 150 | Y | |
| customer_info[0].islead_pax | AN | 50 | Y | It should be true for the lead pax |
| customer_info[0].address | AN | 50 | Y | Customer’s address |
| customer_info[0].city | AN | 50 | Y | "Customer’s city: ""Kuala Lumpur""" |
| customer_info[0].state | AN | 100 | ||
| customer_info[0].postcode | N | 50 | Y | "Customer’s postcode: ""548010""" |
| customer_info[0].country | A | 10 | Y | "Customer’s country: ""MY""" |
| merchant_rtn_url | AN | 200 | Y | Merchant system’s browser redirect URL which receives payment response from wowpay when transaction is completed (approved/declined/system error/cancelled by customer on Payment Page) |
| merchant_callback_url | AN | 200 | Y | Server-to-server URL as an additional link to merchant’s website to be informed of transaction status |
| merchant_request_time | AN | 20 | Y | "Must be in UTC : ""2019-10-30T16:13:04""" |
| payment_expiry | NS | 200 | O | "Expiry/Timeout of the payment: ""2018-08-29T14:45:37.3141418+08:00""" |
| signature | AN | 200 | Y | "Example : ""DF923FA46B5E2226495D8441EE058D295E263698B60E3DFD6521BE8""" |
| ItemDesc_PNR | AN | 300 | ||
| device_info | ||||
| device_info.useragent | AN | 1000 | ||
| device_info.acceptheader | AN | 1000 | ||
| device_info.acceptlanguage | AN | 100 | ||
| IsRecurringPayment | Boolen |
Sample HTML Form in Payment Request
<form id="pay_form" action="https://<url to be provide by GoQuo>" method="post">
<input type="hidden" name="MerchantId" id="MerchantId" value='6' />
<input type="hidden" name="paymentRq" id="paymentRq" value='GzIt4pQN7JYsV2OstHwW0T6vW/=' />
<input type="hidden" name="MerchantTxnId" id="MerchantTxnId" value='Z1911aa76dcb5c9' />
<input type="hidden" name="EncValue" id="EncValue" value=bbffdbfdhjytye32361bgbu2vb==' />
</form>
Payment Response (Wowpay -> Merchant System)
Upon payment process completion, the following fields will be returned from Wowpay to Merchant System’s (merchant_rtn_url) in order to complete an end-to-end payment process
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| txnentry_id | AN | GUID | ||
| merchant_txnid | AN | 20 | Y | "Follows request e.g: ""M201254""" |
| Error | ||||
| Error.error_code | AN | 20 | O | "Message string containing description of the error code (if any), or the description of the response error from bank." |
| Error.error_type | AN | 20 | O | "Message string containing description of the error type (if any), or the description of the response error from bank" |
| Error.error_description | AN | 20 | O | "Message string containing description of the error (if any), or the description of the response error from bank." |
| paymentrs_info | ||||
| paymentrs_info.txn_status | AN | 20 | Y | Status of the transaction |
| paymentrs_info.txn_statuscode | AN | 20 | Y | Numerical containing value of the txn_status |
| paymentrs_info.txn_statusdesc | AN | 50 | ||
| paymentrs_info.provider_desc | AN | 500 | ||
| paymentrs_info.signature | AN | 100 | Y | Message digest value calculated by Merchant System in hexadecimal string using SHA512 hash algorithm |
| paymentrs_info.approval_code | AN | 20 | Y | "Numerical value containing approval code(if any),of the response error from bank" |
| paymentrs_info.transaction_no | AN | 20 | Y | Unique Transaction ID or Reference Code assigned by Wowpay for each of the transaction |
| paymentrs_info.transaction_ref | AN | 20 | Y | Unique Transaction reference code assigned by Wowpay for each of the transaction. |
| paymentrs_info.payment_method | AN | 50 | Y | |
| paymentrs_info.channel_code | AN | 50 | ||
| payment_info | ||||
| payment_info.merchant_txnid | AN | 20 | Y | "Follows request e.g: ""M201254""" |
| payment_info.txn_amount | AN | 20 | Y | "Follows request e.g: ""10.00""" |
| payment_info.txn_currency | AN | 20 | Y | "Follows request e.g: ""MYR""" |
| payment_info.is_installment | AN | 20 | Y | Static Value: FALSE / TRUE |
| payment_info.installment_period | AN | 20 | Y | Numerical Value : “0” “6” “12” |
| payment_info.card_info | ||||
| card_info.cardholder_name | A | 16 | O | Cardholder’s Name |
| card_info.card_no | N | 16 | O | Credit Card Number used for payment authorization |
| card_info.card_type | A | 16 | O | Credit Card Type e.g VISA/MASTERCARD/AMEX/JCB/DINERS *Only available as per request |
| card_info.exp_month | N | 6 | Y | "Expiry date of credit card. Date format is MM, e.g.12 for December" |
| card_info.exp_year | N | 16 | Y | "Expiry date of credit card. Date format is YYYY, e.g.2020" |
| card_info.start_month | A | 16 | O | Date of Registering Credit Card available on the front of credit card “Member Since” |
| card_info.start_year | A | 16 | O | "Date of Registering Credit Card available on the front of credit card “Member Since” Date format is YYYY, e.g.2020" |
| card_info.ExpDate | AN | 50 | ||
| card_info.StartDate | AN | 50 | ||
| payment_info.isstore_cardinfo | Boolen | |||
| payment_info.customer_id | AN | 50 | ||
| payment_info.card_token | AN | 50 |
Sample HTML Form for Redirect Response.
<form id="pay_form" action="http://<merchant’s redirect URL" method="post">
<input type="hidden" name="MerchantTxnId" id="MerchantTxnId" value='Z1911aa75c9' />
<input type="hidden" name="PaymentRS" id="PaymentRS" value='bHAIXg0FAcGzNXrlX9dNBsDKc3//>
<input type="hidden" name="EncValue" id="EncValue" value='OmO7NjQFykL+TF7Masqpy9UKOwXiyV==' />
</form>
Sample Server-to-Server Response
MerchantTxnId=Z1911aa76dcb5c9&PaymentRS=SJ02fvok678lXG1H%2BDPPP39jr5jYTMY2RNvAK7gCscsdxjNw11QJtwfEEIVMjfimudoxmEM8OtjZDEAELlQmpJ3ECAPsmkiOKQZAY%2Fn2oBgNsejHDuO6FdgEkxzPiSIWYKthbsygn0%2FyPsmDxgbwbfnsEUh0M3Na5udr5u6GCPuF3ELw5y8Z%2BtdEek5BW2pJTNFRNoQya9f42rT1DCqKmVcKO0t1v0amXf727SUtEkdfKy06J7edIrBnCNeJYjCvXc4eBqBfcbXXn0V0CUOc06wjXHO1gzSCQ423uFWNNIFS8qYMp9W%2BXxUrV1DBo5McLrMmF3cu941FpkTE7aHpwYz83jIo28mUwGoABQhLDHqzUhyBAa986AwbQ0FiLoL5h0y1MSxrYWWXU5NbDCkW1MdMmHmcIbZBvPmByihaBO2O6LpW35oY%2FzM0ufFSJMWYORDLmdhOZ6J7KVeIdqce1JX69LUX%2F14N%2BGFcosez%2F51trEcdmdBYzUiAd%2Fx%2BUMJm6R&EncValue=Rnz4YCVeWCtCgJOZAjdFD2ux4qfyHxyH7zyRiwSP3VefrzoPBi6NddFSqEBEs4mU2Qw%2Bi57XphykSlkJM8tme8aBFPiqbFuGt9mOqQBezN8AauXtEBniPR%2F79u2mq5pHm0QM9HurtJoTNanlwdva3Gn3l%2FcZM88mTugxdhiBwIAWobFKztdZ4fm0%2FlGPnqyGMx5v%2BIoDHxrVbwWSKPO53GnuGorsbUmdPCHNBGzUqn2dofP1YlKaARHQYruLIxJdMkeEOfrc29ftSXKTGEsbjf8vzkajjR27zY%2B8QEu3YxPLc4xcmByLh4YeWkMLL4lJiWuko3LnCJMtxBCgYhyH%2Bg%3D%3D
Usage of Signature
A signature (or simply hash), also called a message digest, is a number generated from a text string. The hash is substantially smaller than the text string itself and is generated by a formula or hash algorithm in such a way that it is extremely unlikely that some other texts will produce the same hash value. For online payment processing, hashing plays an important role to ensure the transmitted request and response messages have not been tampered with, in order to achieve data integrity. For transaction request, Merchant System is required to use SHA512 hash algorithm to generate a hash value from a combination of certain transaction fields, and then includes the value in signature field before sending the request to Wowpay which will then generate a signature value based on the same method and then verify these two hash values. If both signatures matched, Wowpay will further process the payment request or else it will discard the request message and will treat it as an invalid message.
Signature in the Payment Request & Response using SHA512
Payment request’s signature should be generated based on the following fields
Signature = ToUpperCase(txn_currency + txn_amount.Tostring("#0.00”)+ merchant_txnid)
Payment response’s signature should be generated based on the following fields
Signature = ToUpperCase(txn_status + txn_amount.Tostring("#0.00”)+ merchant_txnid + txn_currency + approval_code)
Sample to generate signature
public static string CreateSha512Hash(string rawData)
{
string hashkey = "";
var objSha512 = SHA512.Create();
byte[] bytValue = Encoding.UTF8.GetBytes(rawData);
byte[] bytHash = objSha512.ComputeHash(bytValue);
hashkey = BitConverter.ToString(bytHash).Replace("-", "");
return hashkey;
}
Sample to generate random password
public static string GenerateRandomPassword(string salt=null,int bytelen=32)
{
return GetHashSha256($"#{salt}{DateTime.Now.ToString("ddMMmYYyyHHmmss")}{new Random().Next(100,1000)}", bytelen);
}
public static string GetHashSha256(string text, int length)
{
byte[] bytes = Encoding.UTF8.GetBytes(text);
SHA256Managed hashstring = new SHA256Managed();
byte[] hash = hashstring.ComputeHash(bytes);
string hashString = string.Empty;
foreach (byte x in hash)
{
hashString += string.Format("{0:x2}", x);
}
if (length > hashString.Length)
{
return hashString;
}
else
{
return hashString.Substring(0, length);
}
}
Sample to encrypt / decrypt (using Org.BouncyCastle.Crypto) random password
public static string Encrypt(string info, string publicKey)
{
if (publicKey.IsValidString())
{
publicKey = publicKey.Replace(Environment.NewLine, "\n");
byte[] bytes = Encoding.ASCII.GetBytes(info);
byte[] encBytes = RSAEncryption(bytes, ReadAsymmetricKeyParameterfromString(publicKey));
var result = Convert.ToBase64String(encBytes).Trim();
return result;
}
return null;
}
public static string Decrypt(string data, string privatekey)
{
string DecryptedPassword = string.Empty;
if (!string.IsNullOrWhiteSpace(data) && !string.IsNullOrWhiteSpace(privatekey))
{
if (Utility.IsUrlEncodedText(data))//if the text url encoded
{
data = WebUtility.UrlDecode(data);
}
//When we update the key from the keyfile to our db, we noticed the "\r\n" added
but actually its "\n".
privatekey = privatekey.Replace(Environment.NewLine, "\n");
byte[] bytes = Convert.FromBase64String(data);
byte[] decBytes = RSADecryption(bytes, AsymmetricCipherKeyPairParameterfromString(privatekey));
DecryptedPassword = Encoding.ASCII.GetString(decBytes).Trim();
}
return DecryptedPassword;
}
Sample to encrypt / decrypt (using Org.BouncyCastle.Security) paymentRq & PaymentRs
pu1. public static string EncryptString(string info,string passwordPhase,string ivVector)
{ string _result = "";
try
{
// Get UTF8 byte array of input string for encryption
// Again, get UTF8 byte array of key for use in encryption
byte[] keyBytes = ASCIIEncoding.ASCII.GetBytes(passwordPhase);
// Initialize AES CTR (counter) mode cipher from the BouncyCastle cryptography library
IBufferedCipher cipher = CipherUtilities.GetCipher("AES/CTR/NoPadding");
byte[] inputBytes = ASCIIEncoding.ASCII.GetBytes(info);
//true is for encryption
cipher.Init(true, new ParametersWithIV(ParameterUtilities.CreateKeyParameter("AES", keyBytes), ASCIIEncoding.ASCII.GetBytes(ivVector)));
byte[] encryptedBytes = cipher.DoFinal(inputBytes);
_result = Convert.ToBase64String(encryptedBytes);
}
catch (Exception err)
{
//log here and take action
}
return _result;
}
ppublic static string DecryptString(string info, string passwordPhase, string ivVector)
{
string _result = "";
try
{
// Get UTF8 byte array of input string for encryption
// Again, get UTF8 byte array of key for use in encryption
byte[] keyBytes = ASCIIEncoding.ASCII.GetBytes(passwordPhase);
// Initialize AES CTR (counter) mode cipher from the BouncyCastle cryptography library
IBufferedCipher cipher = CipherUtilities.GetCipher("AES/CTR/NoPadding");
byte[] inputBytes = Convert.FromBase64String(info);
//true is for encryption
cipher.Init(false, new ParametersWithIV(ParameterUtilities.CreateKeyParameter("AES", keyBytes), ASCIIEncoding.ASCII.GetBytes(ivVector)));
byte[] encryptedBytes = cipher.DoFinal(inputBytes);
_result = System.Text.Encoding.ASCII.GetString(encryptedBytes);
}
catch (Exception err)
{ //log here and take action }
return _result;
Payment Actions (Void/Capture/Refund)
Payment action allows the merchant to perform Void / Capture / Refund against existing successful transactions. Json data should be submitted using Http POST via server-to-server
The payment action api need a header authentication for each request
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| merchant_txnid | AN | 6-15 | Y | This is value “PAYMENT_REFERENCE3” returned to merchant in the payment response.Its mandatory for Void/Refund/Capture |
| order_ref | AN | 6-15 | O | For inquiry, merchant can use order_ref (the one used in payment request). Or merchant_txnid (Wowpay reference) |
| txn_amount | A | 30 | Y | Amount needs to be refunded /voided/captured. It should not exceed original transaction amount. For Inquiry, amount is optional |
| request_type | A | 30 | Y | Request Type must be any one of the following 1.Void 2.Refund 3.Capture Inquiry |
| signature | N | 500 | Y |
Please refer the below section to generate and add header
Header Name: BasicAuth, Token: It will be provided by Wowpay
Generate Header Value: Input = To UpperCase (request_type + merchant_txnid + Token) Headervalue = Base64Encode(Input)
Input: REFUNDSIM0000000130C3BYK1MRZTMWCC9HBEK0TGI3BG16C21ZKZZ3ZUXWV3A=
Output: UkVGVU5EU0lNMDAwMDAwMDEzMEMzQllLMU1SWlRNV0NDOUhCRUswVEdJM0JHMTZDMjFaS 1paM1pVWFdWM0E9
var authValue = new AuthenticationHeaderValue(HeaderName, Headervalue);
HttpClient oclient = new HttpClient()
{
DefaultRequestHeaders = { Authorization = authValue }S
};
public static string Base64Encode(string str)
{
byte[] b = new byte[str.Length];
for (int i = 0; i < str.Length; i++)
{
b[i] = Convert.ToByte(str[i]); };
return Convert.ToBase64String(b);
}
}
Response
| Field | Datatype | Length | Req | Description |
|---|---|---|---|---|
| merchant_txnid | AN | 6-15 | Y | This is value “PAYMENT_REFERENCE3” returned to merchant in the payment response. |
| txn_amount | N | Y | Amount needs to be refunded /voided/captured. It should not exceed original transaction amount | |
| request_type | A | 30 | Y | Request Type must be any one of the following Void/Refund/Capture/Inquiry |
| signature | AN | 500 | Y | |
| txn_status | A | 25 | Y | |
| txn_statuscode | N | 2 | O | |
| provider_desc | AN | O | ||
| approval_code | 50 | O | ||
| transaction_no | 50 | O | ||
| transaction_ref1 | 50 | O | ||
| txn_currency | A | 3 | O | Available in inquiry response |
| masked_cardno | AN | 16-19 | O | Available in inquiry response |
| payment_method | AN | 50 | O | Available in inquiry response |
| channel_code | AN | 50 | O | |
| txn_entryId | AN | 36 | O |
Signature
A signature (or simply hash), also called a message digest, is a number generated from a text string. The hash is substantially smaller than the text string itself and is generated by a formula or hash algorithm in such a way that it is extremely unlikely that some other texts will produce the same hash value.For online payment processing, hashing plays an important role to ensure the transmitted request and response messages have not been tampered with, to achieve data integrity. For transaction request, Merchant System is required to use SHA512 hash algorithm to generate a hash value from a combination of certain transaction fields, and then includes the value in signature field before sending the request to Payment Gateway which will then generate a signature value based on the same method and then verify these two hash values. If both signatures matched, Payment Gateway will further process the payment request or else it will discard the request message and will treat it as an invalid message. Merchant system also must check the same against the response received from payment gateway.
Signature in the Payment Request / Response & Payment Actions using SHA512
Payment request’s signature should be generated based on the following fields:
Signature = To Uppercase (ORDERREF+ AMOUNT ("#0.00”) + CURRENCY+ MERCHANT_ID+ APIPASSWORD)
Input String: PL22072017382548511.00MYR914F825E-2B51-4318-B0A8- 22C601B5979EKRTPLVGMIR8R42OV2L+C0
Signature: FAD39492A926A2E37846E67E7A7BDCA24B58E51D316F07CFC4FD8749CF6DA04E3449A60896BC3B 24CF37C5CCD86793DA384671CB94342B37E5EB413E6FB79B54
Payment response signature should be generated based on the following fields:
Signature = To Uppercase (PAYMENT_REFERENCE3+ PAYMENT_STATUS+ AMOUNT ("#0.00”) + CURRENCY+ APIPASSWORD)
Input String: SIM0000000130APPROVED11.00MYRKRTPLVGMIR8R42OV2L+C0
Signature: 5873702BBE78C2DDC1742C2AED8F1264A6852422CD414F7016E2EDE2A2CBE69131 FE6130979F061A65EECEF5E2B727422DB41729C2D634CEB0CF827B79038A4C
Payment Action request’s signature should be generated based on the following fields:
To Uppercase (merchant_txnid+ txn_amount ("#0.00”) + request_type + APIPASSWORD)
Input String: SIM000000013011.00REFUNDKRTPLVGMIR8R42OV2L+C0
Signature: CB466D4B1459F4F508944C4F4E427BD1434800B027F258F28D45BF8AA4461FD1EFCC374692B84E 7E354EE33384B6235846668D0D33AA3789FBB487F7E64332E5
Payment Action response signature should be generated based on the following fields:
To Uppercase (merchant_txnid+ txn_amount ("#0.00”) + txn_status + APIPASSWORD)
Input String: SIM000000013011.00REFUNDFAILKRTPLVGMIR8R42OV2L+C0
Signature: 8D36EF437F524E800E17ACC9891018C24FC8BEA1A769C7DE61962C914E74023848D 1ECF8E843DC1D01F05D10FA10BF22E481F19C56E3DC89054D3AA46F973681
We advise to compare the signature string with either lower or upper case
public static string CreateSha512Hash(string rawData)
{
var objSha512 = SHA512.Create();
byte[] bytValue = Encoding.UTF8.GetBytes(rawData);
byte[] bytHash = objSha512.ComputeHash(bytValue);
string hashkey = BitConverter.ToString(bytHash).Replace("-", "");
return hashkey;
}
Sample Payment Request
<form name="PaymentReturn" method="POST" action='{HOSTED PAYMENT URL}' >
<input type="hidden" name="AMOUNT" value="11.00"/>
<input type="hidden" name="CURRENCY" value="MYR"/>
<input type="hidden" name="MERCHANT_ID" value="914f825e-2b51-4318-b0a8-22c601b5979e"/>
<input type="hidden" name="ORDERREF" value="PL220720173825485"/>
<input type="hidden" name="FIRSTNAME" value="Demo"/>
<input type="hidden" name="LASTNAME" value="Customer"/>
<input type="hidden" name="EMAIL" value="suresh@goquo.com"/>
<input type="hidden" name="MOBILENO" value="+60103103103"/>
<input type="hidden" name="SIGNATURE"
value="FAD39492A926A2E37846E67E7A7BDCA24B58E51D316F07CFC4FD8749CF6DA04E3449A60896BC3B24CF37C5CCD8
6793DA384671CB94342B37E5EB413E6FB79B54"/>
<input type="hidden" name="DESCRIPTION" value="Demo Order"/>
<input type="hidden" name="RETURNURL" value="https://localhost:44396/simulator/confirm"/>
<input type="hidden" name="NOTIFYURL" value=""/>
<input type="hidden" name="LANGUAGE" value="GB"/>
<input type="hidden" name="ORDERSUMMARY" value=""/>
<input type="hidden" name="STATEMENTDESCRIPTION" value=""/>
<input type="hidden" name="ADDRESS" value=""/>
<input type="hidden" name="POSTALCODE" value=""/>
<input type="hidden" name="CITY" value=""/>
<input type="hidden" name="COUNTRY" value=""/>
</form>
Sample Payment Response
<form name="PaymentReturn" method="POST" action='{MERCHANT RETURN URL}' >
<input type="hidden" name="ACKNOWLEDGEMENT_URL" value=""/>
<input type="hidden" name="ORDERREF" value="PL220720173825485"/>
<input type="hidden" name="AMOUNT" value="11.00"/>
<input type="hidden" name="CURRENCY" value="MYR"/>
<input type="hidden" name="APPROVAL_CODE" value="115893"/>
<input type="hidden" name="PAYMENT_DESCRIPTION" value="Success (Paid)"/>
<input type="hidden" name="PAYMENT_REFERENCE1" value="3264188"/>
<input type="hidden" name="PAYMENT_REFERENCE2" value="3141268"/>
<input type="hidden" name="PAYMENT_REFERENCE3" value="SIM0000000130"/>
<input type="hidden" name="PAYMENT_STATUS" value="APPROVED"/>
<input type="hidden" name="PAYMENT_STATUSCODE" value="1"/>
<input type="hidden" name="PAYMENT_TYPE" value="Credit and debit cards"/>
<input type="hidden" name="PAYMENT_CHANNEL" value="Visa"/>
<input type="hidden" name="MERCHANT_ID" value="914f825e-2b51-4318-b0a8-22c601b5979e"/>
<input type="hidden" name="CARD_NUMBER" value="411111XXXXXX1111"/>
<input type="hidden" name="SIGNATURE"
value="5873702BBE78C2DDC1742C2AED8F1264A6852422CD414F7016E2EDE2A2CBE69131FE6130979F061A65EECEF5E2B
727422DB41729C2D634CEB0CF827B79038A4C"/>
</form>
Sample Payment Action Request
{
"merchant_txnid": "SIM0000000130",
"txn_amount": 11.0,
"request_type": "Refund",
"signature":
"CB466D4B1459F4F508944C4F4E427BD1434800B027F258F28D45BF8AA4461FD1EFCC374692B84E7E354EE33384B623584
6668D0D33AA3789FBB487F7E64332E5"
}
Sample Payment Action Response
{
"request_type": "Refund",
"txn_status": "REFUNDFAIL",
"txn_statuscode": "12",
"txn_statusdesc": "REFUNDFAIL",
"provider_desc": "Transaction status is not valid to perform your action.",
"signature":
"8D36EF437F524E800E17ACC9891018C24FC8BEA1A769C7DE61962C914E74023848D1ECF8E843DC1D01F05D10FA10BF22
E481F19C56E3DC89054D3AA46F973681",
"approval_code": "115893",
"transaction_no": "3264188",
"transaction_ref1": "3264188",
"txn_amount": 11.00,
"txn_currency": "MYR",
"merchant_txnid": "SIM0000000130",
"txn_entryId": "3cfcc9a6-7c91-415b-8fb9-389804e8f95f"
}
Sample Request for Inquiry
{
"merchant_txnid": "SIM0000000130",
"order_ref": null,
"request_type": "Inquiry",
"signature":
"9759ABB5B51532335AAD5427F4475E38624F5FF25E9A0708B3B625A53F52230160EA1D49CCB65CCD8AD43C2F3765F1AE
3892A48D53EF74C75EF57B345635CCDB"
}
Sample Response for Inquiry
{
"request_type": "Inquiry",
"txn_status": "APPROVED",
"txn_statuscode": "1",
"provider_desc": "Approved",
"signature":
"5F88FEAE1B21BCEDEDF9238779B9D99B0DF0FE6609D7D1562968D10E762FC255B96F351F71B97838AEC9E5AEFD241A19
4642B880711D70F3A6EC8685DD04E42D",
"approval_code": "115893",
"transaction_no": "3264188",
"txn_amount": 11.17,
"txn_currency": "MYR",
"merchant_txnid": "SIM0000000130",
"txn_entryId": "3cfcc9a6-7c91-415b-8fb9-389804e8f95f",
"masked_cardno": "411111XXXXXX1111"
}
Appendix
Product Code
| Product Code | Product Name |
|---|---|
| ALL | All |
| HO | Hotel Only |
| FO | Flight Only |
| PKGE | Package |
| TO | Tour Only |
| Test | Test Product |
| ACT | Activities |
| OTH | Others |
Transaction Status
| Code | Status |
|---|---|
| 0 | DECLINED |
| 1 | APPROVED |
| 2 | WAITTOPAY |
| 3 | CANCELLED |
| 4 | PREAUTHORIZED |
| 5 | DUPLICATERQ |
| 6 | VOIDED |
| 7 | FULLYREFUNDED |
| 8 | PARTIALLYREFUNDED |
| 9 | FULLYCAPTURED |
| 10 | PARTIALLYCAPTURED |
| 11 | VOIDFAIL |
| 12 | REFUNDFAIL |
| 13 | CAPTUREFAIL |
| 14 | ERROR |
| 15 | EXPIRED |
| 16 | NON3DNOTALLOWED |
| 17 | REQUESTRECEIVED |
| 18 | PROCESSING |
| 19 | NORESPONSE |
| 20 | REFUNDPROCESSING |
| 21 | CAPTUREPROCESSING |
| 22 | VOIDPROCESSING |
| 23 | SESSIONEXPIRED |
| 24 | SETTLED |
| 25 | CREATED |
| 26 | CUSTOMERPAYING |
| 27 | FRAUD |
| 28 | TXNIDMISMATCH |
Payment flow diagram
Credit Card
Integration Guide
Credit card
Online Banking
Credit card (Preauth)
