We are awesome Payment Gateway

API Documentation

Kindly get the following credentials ready in order to start integrating using API.

  • Merchant ID
  • API Key
Field Name Requirement Description Format
merchant_id
MANDATORY
Your merchant ID.
Eg: 10001
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
invoice
MANDATORY
Unique invoice number.
Eg: INV10124566
  • Accept alphabets, numbers and some special characters.
  • Length: Max 18 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
amount
MANDATORY
Final amount to be paid by buyer.
Include all taxes & charges in this field if applicable.
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
payment_desc
MANDATORY
Purpose of payment.
Eg: Parking Fee
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
hash
MANDATORY
The secure hash string to validate the payment request sent through our Payment Gateway.
  • Generated value must contain only alphabets and numbers
buyer_name
OPTIONAL
Buyer's name.
  • Accept only alphabets
buyer_email
OPTIONAL
Buyer's email. Buyer will receive payment notification at this address if specified.
  • Accept only valid email address
phone
OPTIONAL
Buyer's phone number.
  • Accept only digits and (+) symbol
add_line_1
OPTIONAL
Buyer's address line 1.
  • Accept only alphanumerics characters
add_line_2
OPTIONAL
Buyer's address line 2.
  • Accept only alphanumerics characters
postcode
OPTIONAL
Buyer's postcode.
  • Accept only digits
city
OPTIONAL
Buyer's city location.
  • Accept only alphanumerics characters
comment
OPTIONAL
Buyer's additional comments / notes on the purchase.
  • Accept only alphanumerics characters
callback_url_be
OPTIONAL
Callback URL for your back-end process.
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
callback_url_fe_succ
OPTIONAL
Callback URL for your front-end successful transaction process.
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
callback_url_fe_fail
OPTIONAL
Callback URL for your front-end failed transaction process.
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
baggage_variable
OPTIONAL
Name of the variable.
Eg: variable1|variable2
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
* Every variable name that has been stated in baggage_variable *
OPTIONAL
Value for each variable.
Eg: value1|value2
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
Field Name Description Format
fpx_fpxTxnId
OR
paypal_trx_id
OR
mastercard_trx_id
Unique transaction ID.
You can use this Transaction ID to track the transaction in QlicknPay's portal.
Eg: 1808241535340347
  • Returns alphanumerics characters.
fpx_sellerId Your FPX seller ID.
Eg: SE000008567
  • Returns alphanumerics characters.
invoice_no Unique invoice number.
Eg: INV10154632
  • Returns alphanumerics characters.
txn_status Response code of the status of payment. Eg: 00
* Refer table below for description of the response code.
  • Returns alphanumerics characters.
msg Status message of the payment depend on the response code from txn_status.
Eg: Transaction Approved
  • Returns alphanumerics characters.
txn_amount Final amount paid by buyer.
Eg: 192.00
  • Returns only digits.
pay_method Payment method chosen by buyer.
Eg: fpx/paypal/mastercard
  • Returns only alphabets.
hash Secure hash string to validate the response sent to your side by our Payment Gateway.
  • Returns alphanumerics characters.
Error Messages Problem
Unable to process payment due to invalid API or invalid merchant ID or no data entered. Please inform the merchant about this error. Invalid API or Merchant ID.
Maximum total of amount exceeded or invalid data entered. Please assume that every transaction must be less than RM30,000 and more than RM1.50. Amount must more than RM1.50 (RM1.50 is included) and less than RM30,000.
Unable to process payment due to invalid Product ID entered. Product description must be more than 0 and less than 1,000 characters.
Unable to process payment due to invalid API entered. Please inform to the merchant about this error. Invalid API. Your API must be less than 14 characters
Invalid data entered. Validation errors / Hashing variables does not match with data entered.
Invalid URL variable specified. Please inform to the merchant about this error. Your 'callback_url_be' host name is not have a same host name as Callback URL at your 'Manage API Setting'.
To solve this problem:

  • Empty the value on your 'callback_url_be' variable or on your Manage API Setting
  • OR specify your host name with with the same name as you specify on your Manage API Setting
  • EX: 'callback_url_be':
    www.hostname.com/callbackv1
    Callback Setting:
    www.hostname.com/sub/sub2/callbackv2
Invalid name of baggeges. Please inform to the merchant about this error. Invalid baggages name. Baggages name cannot same as others variables(required/optional fields) name. EX: 'merchant_id'
Your Invoice number is to long. Invoice number must be less than or equal to 14 characters. Please inform to the merchant about this error. Your invoices length must more than 0 and less than 14 characters.
Invalid email address. Please enter a valid email address. Invalid buyer email address specified.
Invalid invoices. Please inform to the merchant to check their invoice validation. The invoices content forbidden characters. EX: '-'
Invalid invoice or duplicated invoice entered. Please inform to the merchant about this error. Cannot use the same invoices that successfully made a transaction
Indirect error. Please inform to the merchant to specified their url in their dasboard. API URL, Opencart URL, Prestashop URL, Drupal URL, Ecwid URL or Woocommerce URL isn't specified in the dashboard.
Response Code Description
*Others* Unable To Trace An Error
00 Transaction Approved
03 Invalid Merchant
05 Invalid Seller or Acquiring Bank Code
13 Invalid Amount
00 Transaction Approved
09 Transaction Pending
12 Invalid Transaction
14 Invalid Buyer Account
20 Invalid Response
31 Invalid Bank
39 No Credit Account
45 Duplicate Seller Order Number
46 Invalid Seller Exhchange or Seller
47 Invalid Currency
48 Maximum Transaction Limit Exceeded RM30,000.00 for B2C
49 Merchant Specific Limit Exceeded
50 Invalid Seller for Merchant Specific Limit
51 Insufficient Funds
53 No Buyer Account Number
57 Transaction Not Premitted
58 Transaction To Merchant Not Premitted
70 Invalid Serial Number
76 Transaction Not Found
77 Invalid Buyer Name or Buyer ID
78 Decryption Failed
79 Host Decline When Down
80 Buyer Cancel Transaction
83 Invalid Transaction Model
84 Invalid Transaction Type
85 Internel Error At Bank System
87 Debit Failed Exception Handling
88 Credit Failed Exception Handling
89 Transaction Not Received Exception Handling
90 Bank Internet Banking Unavailable
92 Invalid Buyer Bank
96 System Manulfaction
98 MAC Error
99 Pending Authorization (Applicable for B2B model)
BC Transaction Cancelled By Customer
DA Invalid Applcaition Type
DB Invalid Email Format
DC Invalid Maximum Frequency
DD Invalid Frequency Mode
DE Invalid Expiry Date
DF Invalid e-Mandate
FE Internal Error
OE Transaction Rejected As Not In FPX Operating Hours
OF Transaction Timeout
SB Invalid Acquiring Bank Code
XA Invalid Source IP Address (Applicable for B2B2 model)
XB Invalid Seller Exchange IP
XC Seller Exchange Encryption Error
XE Invalid Message
XF Invalid Number of Orders
XI Invalid Seller Exchange
XM Invalid FPX Transaction Model
XN Transaction Rejected Due To Duplicate Seller Exchange Order Number
XO Duplicate Exchange Order Number
XS Seller Does Not Belong To Exchange
XT Invalid Transaction Type
XW Seller Exchange Date Difference Exceeded
1A Seller Buyer Session Timeout At Internet Banking Login Page
1B Buyer Failed To Provide The Necessary Info To Login To Internet Banking Login Page
1C Buyer Choose Cancel At Login Page
1D Buyer Session Timeout At Account Selection Page
1E Buyer Failed To Provide The Necessary Info To Login To Internet Banking Login Page
1F Buyer Choose Cancel At Account Selection Page
1G Buyer Session Timeout At TAC Request Page
1H Buyer Failed To Provide Necessary Info At TAC Request Page
1I Buyer Choose Cancel At TAC Request Page
1J Buyer Session Timeout At Confirmation Page
1K Buyer Failed To Provide Necessary Info At Confirmation Page
1L Buyer Choose Cancel At Confirmation Page
1M Internet Banking Session Timeout
2A Transaction Amount Is Lower Than Minimum Limit RM1.00 for B2C
Field Name Example Value
api APIKEY123456
merchant_id 1000034
invoice INV10154632
amount 1289.00
payment_desc Parking Fee

Sample code to hash above values:
md5($api."|".urldecode($merchant_id)."|".urldecode($invoice)."|".urldecode($amount)."|".urldecode($payment_desc));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
APIKEY123456|100055|INV10154632|1289.00|Parking Fee will generate something like e8f3ac1c718fa7e620b133d601fb4f73

When Receiving Payment Request Response
Field Name Example Value
fpx_fpxTxnId
OR
paypal_trx_id
OR
mastercard_trx_id
1808241535340347
fpx_sellerId SE000008567
invoice_no INV10154632
msg Transaction Approved
txn_status 00
txn_amount 1289.00
hash dc8e364d222d6025cbc505674b701asdw
pay_method fpx OR paypal OR mastercard
*Your baggage variable* *Your baggage value*

Sample code to hash above values:
md5($api.$fpx_fpxTxnId.$invoice_no.$txn_status.$msg);

For example, if the details received are as above, the hash string to be generated is constructed as follows:
APIKEY123456|1808241535340347|INV012345|00|Transaction Approved will generate something like dc8e364d222d6025cbc505674b7012df

If the generated hash string is the same with the hash sent in the response message, the data is safe from tampering.

<?php
/**
 * This is a sample code for manual integration with QlicknPay
 * It is so simple that you can do it in a single file
 * Make sure that in QlicknPay Dashboard you have key in the return URL referring to this file
 */

# please fill in the required info as below
$merchant_id '10001'// this refers to your Merchant ID that can be obtain from QlicknPay
$api 'APIKEY100001'// API key


# this part is to process data from the form that user key in, make sure that all of the info is passed so that we can process the payment
if(isset($_POST['amount']) && isset($_POST['invoice']) && isset($_POST['payment_desc']))
{

# assuming all of the data passed is correct and no validation required. Preferably you will need to validate the data passed
$hashed_string md5($api."|".urldecode($merchant_id)."|".urldecode($_POST['invoice'])."|".urldecode($_POST['amount'])."|".urldecode($_POST['payment_desc']));

# now we send the data to QlicknPay by using post method

$QlicknPay_link_sandbox '{Sandbox URL}';
$QlicknPay_link_live '{Live Production URL}';

    
?>
<html>
<head>
<title>QlicknPay Payment Gateway API Sample Code</title>
</head>
<body onload="document.order.submit()">
#Specified the link below either for sandbox or live production
    <form name="order" method="post" action="<?= $QlicknPay_link_sandbox ?>">
        <?=#  REQUIRED FORM START HERE ?>
          <input type="hidden" name="merchant_id" value="<?= $merchant_id?>">
          <input type="hidden" name="invoice" value="<?= $_POST['invoice']?>">
          <input type="hidden" name="amount" value="<?= $_POST['amount']; ?>">
          <input type="hidden" name="payment_desc" value="<?= $_POST['payment_desc']; ?>">
          <input type="hidden" name="hash" value="<?= $hashed_string?>">
        <?=#  REQUIRED FORM END HERE ?>

        <?=#   OPTIONAL FORM START HERE ?>
          <?=#  Set this as null or remove it if you're not required this form. This form will display on payment gateway and save the value in dashboard  ?>
          <?=#  Buyer Name ?>
          <input type="hidden" name="buyer_name" value="John">
          <?=#  Buyer Email. Must be valid email address. Buyer will get transaction status through this email ?>
          <input type="hidden" name="buyer_email" value="John@gmail.com">
          <?=#  Buyer Phone number with country code ?>
          <input type="hidden" name="phone" value="+0123456789">
          <?=#  Buyer Address form line 1?>
          <input type="hidden" name="add_line_1" value="10-3, 3rd Floor Jln PJU 5/9">
          <?=#  Buyer Address form line 2?>
          <input type="hidden" name="add_line_2" value="Dataran Sunway Kota Damansara">
          <?=#  Buyer Postcode ?>
          <input type="hidden" name="postcode" value="47810">
          <?=#  Buyer City ?>
          <input type="hidden" name="city" value="Petaling Jaya">
          <?=#  Buyer State ?>
          <input type="hidden" name="state" value="Selangor">
          <?=#  Buyer Comment ?>
          <input type="hidden" name="comment" value="">

          <?=#  Your callback url for backend process. If you already have specified it on your dashboard but want a different url for different process, please include this form. ?>
          <?=#  Your Back-end Process ?>
          <input type="hidden" name="callback_url_be" value="https://www.example.com/callback_url_be.php">
          <?=#  Your Front-end Process Success interface ?>
          <input type="hidden" name="callback_url_fe_succ" value="https://www.example.com/callback_fe_succ.php">
          <?=#  Your Front-end Process Fail interface ?>
          <input type="hidden" name="callback_url_fe_fail" value="https://www.example.com/callback_url_fe_fail.php">

          <?=#  If you required a variable that provide the same value when you return it after transaction, use this baggage form. You can have more than one variable.?>
          <?=# Please seperate each variable and value by using '|'. Please make sure that every form's value below not more than 5000 characters ?>
          <?=#   Your vaiable(s)?>
          <input type="hidden" name="baggage_variable" value="variable1|variable2|variable3|variable4">
          <?=#   Your value(s) of each variable(s). Must be synchonize with the total variable above ?>
          <input type="hidden" name="variable1" value="value1">
          <input type="hidden" name="variable2" value="value2">
          <input type="hidden" name="variable3" value="value3">
          <input type="hidden" name="variable4" value="value4">
        <?=#   OPTIONAL FORM END HERE ?>

    </form>
</body>
</html>

<?php
}
else
{
?>

<html>
<head>
  <title>QlicknPay Payment Gateway API Sample Code</title>
</head>
<body>
  <form method="post" action="<?= htmlentities($_SERVER['PHP_SELF']); ?>">
    <table>
      <tr>
          <td colspan="2">Please fill up the detail below in order to test the payment.</td>
      </tr>
      <tr>
        <?=#  AMOUNT VALUE  MUST MORE THAN RM1.50 AND WITH 2 DECIMAL POINTS ?>
          <td>Amount</td>
          <td>: <input type="text" name="amount" value="" placeholder="Amount to pay, for example 12.20" size="30"></td>
      </tr>
      <tr>
        <?=#   DESCRIPTION MUST BE LESS THAN 1,000 CHARACTERS ?>
          <td>Payment Description (Not more than 1,000 character)</td>
          <td>: <input type="text" name="payment_desc" value="" placeholder="Description of the transaction" size="30"></td>
      </tr>
      <tr>
         <?=#  MUST BE UNIQUE  ?>
          <td>Invoice (Not more than 17 char without '-')</td>
          <td>: <input type="text" name="invoice" value="" placeholder="Unique id to reference the transaction or order" size="30"></td>
      </tr>

      <tr>
          <td><input type="submit" value="Submit"></td>
      </tr>
    </table>
  </form>
</body>
</html>
<?php
}
?>
<?php

#Tracing the transaction which payment method is used by your customer
if($_REQUEST['pay_method'] == 'fpx'#Using FPX
{
  
$trx_id $_REQUEST['fpx_fpxTxnId']; #EX: 1808241535340347
}
else if(
$_REQUEST['pay_method'] == 'paypal'#Using PayPal
{
  
$trx_id $_REQUEST['paypal_trx_id']; #EX: 1808241535340347
}
else if(
$_REQUEST['pay_method'] == 'mastercard'#Using Mastercard
{
  
$trx_id $_REQUEST['mastercard_trx_id']; #EX: 1808241535340347
}

#These are the data that posible to get from the callback URL
$fpx_sellerId   $_REQUEST['fpx_sellerId']; #EX: SE10000001
$invoice_no $_REQUEST['invoice_no']; #EX: INV012345
$txn_status $_REQUEST['txn_status']; #EX: 00 *You can view more txn_status value from the documentation*
$msg $_REQUEST['msg']; #EX: Transaction Approved
$txn_amount $_REQUEST['txn_amount']; #EX: 1289.00
$pay_method $_REQUEST['pay_method']; #EX: fpx *Can be either fpx or PayPal
$hash $_REQUEST['hash']; #EX: dc8e364d222d6025cbc505674b7ASDDS
$sample_bagages_variables $_REQUEST['sample_bagages_variables']; # *The variable name is depend on what you have set when calling an API to the payment gateway. This is optional variables.

# assuming all of the data passed is correct and no validation required. Preferably you will need to validate the data passed
# This is important to prevent any attack from hackers
$hash =  md5($api.$trx_id.$invoice_no.$txn_status.$msg);

if(
$hash == $_REQUEST['hash'])
{
    echo 
'OK'# An 'OK' msg need to send to the QlicknPay as a valid respond received from the merchant.
    # QlicknPay will send the callback data at most 3 times every 10 minutes if QlicknPay doesn't received an 'OK' message

    #Do stuff
    #You can manage your callback data here
}

else
{
    echo 
'Invalid Data';
    
#Invalid Data entered or hashing error
}

 
?>