NAV

shell php

IP

  is now known as .   All API endpoints using the TLD Betterpay.me or qnp.com is valid ×

Introduction

Welcome to the QlicknPay API! You can use our API to access QlicknPay API endpoints for bill presentation and payment collection. Our gateway supports multiple payment options (FPX/Credit Card/E-Wallet) and many e-commerce platforms as well as marketplaces such as Lazada & Shopee.

In order to use the API, you will need your Merchant ID and API Key. These credentials can be retrieved in QlicknPay Payment Gateway portal, under Manage API Tab. Please keep this credentials secure. Do not disclose to anyone.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. All request must be hashed for authentication.

Rate Limit

All API GET method Endpoints are subject to rate limit.

The limit is 100 requests per request window (5 minutes period). The limit is cumulative either per IP address or account, and is not counted per API Endpoint Basis. Requesting for specific API Endpoint will reduce the limit for another API Endpoint within a request window.

Exceeding the rate limit will result to 429 Too Many Requests.

RESPONSE PARAMETER

Example response (429):

      

      {
          "response": "99",
          "msg": "Rate limit exceeded 25/42s[60.49.75.249]. Expire in 28",
      }
  

    
      

      {
          "response": "99",
          "msg": "Rate limit exceeded 25/42s[60.49.75.249]. Expire in 28",
      }

Response parameter will be as usual if didn't exceed the rate limit. Otherwise, the response parameters will be as follows:

Parameter Value
response 99
msg Rate limit exceeded 25/42s[60.49.75.249]. Expire in 28



 

 

Standard Payment Gateway

This feature will redirect your payer to QlicknPay checkout page. You payer can then select the different payment options provided.

API Endpoint URLs

Requirement to Use the API

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

  • Merchant ID
  • API Key

You can retrieve this information at API Management page.

How to send a Payment Request?

Kindly ensure the payment request you send to either of the above mentioned endpoints comply to the following format using POST method. You can set fields with OPTIONAL tag to NULL or exclude it entirely if it is not required.

Required Arguments

Example request:

      
Please select PHP to view the sample code

    




<?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">

          <?=#   Custom your payment title and contact. ?>
          <input type="hidden" name="header_title" value="Payment Title">
          <input type="hidden" name="header_email" value="contact@gmail.com">
          <input type="hidden" name="header_phone" value="0123456789">
          <?=#   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
}
?>

Response (200):

      
# Directly to Payment Gateway.

    
      
# Directly to Payment Gateway.

Response (400):

      
# Invalid format data entered

    
      
# Invalid format data entered

Response (401):

      
# Invalid Merchant ID or API Key

    
      
# Invalid Merchant ID or API Key
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
amount Final amount to be paid by buyer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE:250
payment_desc Purpose of payment
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
  • Length: Max 1000 characters.
TYPE: STRING
EXAMPLE:PARKING FEE
currency Currency of payment
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
  • 'THB' is for Thailand Currency
  • 'PHP' is for Philippines Currency
TYPE: STRING
EXAMPLE:MYR
hash The secure hash string to validate the payment request sent to our Payment Gateway.
  • Accept only alphabets
TYPE: STRING

Optional Arguments

Parameter Description
buyer_name Buyer's name
  • Accept only alphabets
TYPE: STRING
EXAMPLE:JOHN
buyer_email Buyer's email. Buyer will receive payment notification at this address if specified
  • Accept only valid email address
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
phone Buyer's phone number
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
add_line_1 Buyer's address line 1
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
add_line_2 Buyer's address line 2
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
postcode Buyer's postcode
  • Accept only digits
TYPE: INTEGER
EXAMPLE:47810
city Buyer's city location
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:PETALING JAYA
comment Buyer's additional comments / notes on the purchase
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
callback_url_fe_succ 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
callback_url_fe_fail 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_FAILURE
baggage_variable If you required a variable that provide the same value after transaction has been made, use this baggage form. You can have more than one variable.
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your bagages variable name* Your value(s) of each variable(s). Must be synchonize with the total number of variable above
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VALUE1
header_title Modify your company name at payment gateway checkout page
  • Accepts only alphanumeric characters
  • Length: Not more than 80 characters
TYPE: STRING
EXAMPLE:PAYMENT HEADER TITLE
header_email Modify your company email address at payment gateway checkout page
  • Accepts only alphanumeric characters
  • Length: Not more than 50 characters
TYPE: STRING
EXAMPLE:SUPPORT@MERCHANT.COM
header_phone Modify your company phone number at payment gateway checkout page
  • Accepts only alphanumeric characters
  • Length: Not more than 50 characters
TYPE: STRING
EXAMPLE:+603283928242

How to receive the Payment Request response (via callback)?

The response to your payment request will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your payer complete or cancel a transaction.

Sample response:

      
{
    "fpx_fpxTxnId": "1808241535340347",
    "fpx_sellerId": "SE000008567",
    "invoice_no": "INV10154632",
    "txn_status": "00",
    "msg": "Transaction Approved",
    "txn_amount": "192.00",
    "pay_method": "fpx",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

    
      
{
    "fpx_fpxTxnId": "1808241535340347",
    "fpx_sellerId": "SE000008567",
    "invoice_no": "INV10154632",
    "txn_status": "00",
    "msg": "Transaction Approved",
    "txn_amount": "192.00",
    "pay_method": "fpx",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}
Parameter Description
fpx_fpxTxnId
OR
paypal_trx_id
OR
mastercard_trx_id OR
others_trx_id 		Unique transaction ID. You can use this Transaction ID to track the transaction in QlicknPay's portal.
TYPE: STRING
*trx_txt Only if 'others_trx_id' is received AND not NULL. Example: eWallet 2C2P (TNG)
TYPE: STRING
fpx_sellerId Your FPX seller ID.
TYPE: STRING
invoice_no Unique invoice number.
TYPE: STRING
txn_status Response code of the status of payment.* Refer table below for description of the response code.
TYPE: STRING
msg Status message of the payment depend on the response code from txn_status.
TYPE: STRING
txn_amount Final amount paid by buyer.
TYPE: STRING
pay_method Payment method chosen by buyer. Eg: fpx/paypal/mastercard/others
TYPE: STRING
hash Secure hash string to validate the response sent to your side by our Payment Gateway.
TYPE: STRING

API Errors Guide

The API will return error messages if any of the variables sent is invalid.

Error Messages Issue
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 (B2C) and more than RM1.50. Amount must be more than or equal to RM 1.50 and less than RM 30,000 (B2C).
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 the merchant about this error. Invalid API. Your API key must be less than 14 characters.
Invalid data entered. Validation errors / Hashing variables do not match the data entered.
Invalid URL variable specified. Please inform the merchant about this error. Your callback_url_be host name is not the same host name as Callback URL specified in your API Management setting. To solve this problem, do these steps:
    1. Set to null the value of callback_url_be variable OR
    2. Specify the same host name for both callback_url_be and in your API Management setting.
    Example: callback_url_be:
    www.hostname.com/callbackv1
    API Management setting:
    www.hostname.com/sub/sub2/callbackv2
Invalid name of baggages. Please inform to the merchant about this error. Invalid baggages name. Baggages name cannot same as other variables(required/optional fields) name.
Example: 'merchant_id'
Your Invoice number is too long. Invoice number must be less than or equal to 14 characters. Please inform to the merchant about this error. Your invoice 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.
Example: '-'
Invalid invoice or duplicated invoice entered. Please inform to the merchant about this error. Invoice number must be unique for each transaction initiated.
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 is not specified in the API Management setting.

Response Code and Description

Refer to this table for the description of the returned response code.

Example response:

      
Please select PHP to view the sample code

    
  

    <?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
}
else if($_REQUEST['pay_method'] == 'others')
{
  $trx_id = $_REQUEST['others_trx_id']; #EX: 1808241535340347
  $_REQUEST['pay_method'] = $_REQUEST['trx_txt']; #EX: Boost eWallet and etc
}

#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
}

 ?>
Response Code Description
*Others* Unable To Trace An Error
B0 Order list format error
B1 Invalid seller ID
B2 Seller is not allow to refund
B3 Seller is not allow to do multiple refund
B4 Requested refund amount exceed maximum allowable
B5 Original transcation ID is not found
B6 Original transcation ID status is still pending debit/credit
B7 Original transcation ID status was not successful
B8 Previous refund request still pending debit/credit
B9 Requested refund amount below minimun allowable
C1 Invalid refund transcation model
C2 Invalid refund buyer bank
C3 Invalid refund seller bank
C4 Refund request fail due to no valid order list
C5 Order list contain duplicate seller order number
1S Refund Successful Submited
03 Invalid Merchant
05 Invalid Seller or Acquiring Bank Code
13 Invalid Amount
00 Transaction Approved
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

Hashing Guide

This section will explain how to secure your payment request & response using hashing method. This will be used to generate the hash field in your payment request as well as to validate the return hash from QlicknPay.

When Sending Payment Request

Field Name Example Value
api APIKEY123456
merchant_id 1000034
invoice INV10154632
amount 1289.00
payment_desc Parking Fee
currency MYR

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

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|MYR will generate something like c0f29c5f03b96cb33df310369e3ce05d

When Receiving Payment Response

Field Name Example Value
fpx_fpxTxnId
OR
paypal_trx_id
OR
mastercard_trx_id
OR
others_trx_id		 1808241535340347
*trx_txt
(Only if 'others_trx_id' is received AND not NULL)		 eWallet 2C2P (TNG)
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 OR others
*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:
APIKEY1234561808241535340347INV01234500Transaction 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.

An 'OK' message need to display from your callback endpoint as a valid respond received. Betterpay will send the callback data at most 3 times every 10 minutes if Betterpay doesn't received an 'OK' message. (Refer sample codes given on how to display the 'OK' message from your callback endpoint)

Create Bill

You can use this API to retrieve a payment URL. This is useful if you want to contruct all the parameters of the bill from your own system, and send a final url for your payer to complete the transaction.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at the API Management page.

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
      -d merchant_id: 10010\
      -d invoice: FS789\
      -d amount: 150\
      -d payment_desc: Parking Fee\
      -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
      -d buyer_name: John\
      -d buyer_email: John@domain.com\
      -d phone: +6017123123\
      -d add_line_1: 10-3, 3rd Floor Jln PJU 5/9\
      -d add_line_2: Dataran Sunway Kota Damansara\
      -d postcode: 47810\
      -d city: Petaling Jaya\
      -d state: Selangor\
      -d comment: Comment Here For Merchant Reference\
      -d callback_url_be: https://www.example.com/callback_url_be\
      -d callback_url_fe_succ: https://www.example.com/callback_fe_succ\
      -d callback_url_fe_fail: https://www.example.com/callback_url_fe_fail\
      -d baggage_variable: variable1|variable2\
      -d variable1: value1\
      -d variable2: value2\
      -d header_title: Payment Title\
      -d header_email: contact@gmail.com\
      -d header_phone: 0123456789\
      

  
    
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&invoice=INV0001&amount=250&payment_desc=Parking Fee&hash=dc8e364d222d6025cbc505674b7012df&buyer_name=John&buyer_email=john@domain.com&phone=+60171234567&add_line_1=10-3, 3rd Floor Jln PJU 5/9&add_line_2=Dataran Sunway Kota Damansara&postcode=47810&city=Petaling Jaya&comment=Comment Here For Merchant Reference&callback_url_be=https://www.example.com/callback&callback_url_fe_succ=https://www.example.com/callback_success&callback_url_fe_fail=https://www.example.com/callback_success&baggage_variable=variable1|variable2&variable1=value1&variable2=value2&header_title=Payment Header Title&header_email=support@merchant.com&header_phone=+603283928242");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response (200):

    
{
    "response": "00",
    "merchant_id": "10010",
    "invoice": "FS789",
    "amount": "150",
    "payment_desc": "Parking Fee",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "buyer_name": "John",
    "buyer_email": "John@domain.com",
    "phone": "+6017123123",
    "add_line_1": "10-3, 3rd Floor Jln PJU 5/9",
    "add_line_2": "Dataran Sunway Kota Damansara",
    "postcode": "47810",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "comment": "Comment Here For Merchant Reference",
    "callback_url_be": "https://www.example.com/callback_url_be",
    "callback_url_fe_succ": "https://www.example.com/callback_fe_succ",
    "callback_url_fe_fail": "https://www.example.com/callback_url_fe_fail",
    "baggage_variable": "variable1|variable2",
    "variable1": "value1",
    "variable2": "value2",
    "header_title": "Payment Title",
    "header_email": "contact@gmail.com",
    "header_phone": "0123456789",
    "url": "https://www.qlicknpay.com/receiver-disp?34-INV0001-024939-iXO"
}

  
    
{
    "response": "00",
    "merchant_id": "10010",
    "invoice": "FS789",
    "amount": "150",
    "payment_desc": "Parking Fee",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "buyer_name": "John",
    "buyer_email": "John@domain.com",
    "phone": "+6017123123",
    "add_line_1": "10-3, 3rd Floor Jln PJU 5/9",
    "add_line_2": "Dataran Sunway Kota Damansara",
    "postcode": "47810",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "comment": "Comment Here For Merchant Reference",
    "callback_url_be": "https://www.example.com/callback_url_be",
    "callback_url_fe_succ": "https://www.example.com/callback_fe_succ",
    "callback_url_fe_fail": "https://www.example.com/callback_url_fe_fail",
    "baggage_variable": "variable1|variable2",
    "variable1": "value1",
    "variable2": "value2",
    "header_title": "Payment Title",
    "header_email": "contact@gmail.com",
    "header_phone": "0123456789",
    "url": "https://www.qlicknpay.com/receiver-disp?34-INV0001-024939-iXO"
}

Response (400):

    
{
    "response": "98",
    "merchant_id": "Fail to created bill."
}

  
    
{
    "response": "98",
    "merchant_id": "Fail to created bill."
}

Response (401):

    
{
    "response": "99",
    "merchant_id": "Invalid data entered. Please inform the merchant about this error."
}

  
    
{
    "response": "99",
    "merchant_id": "Invalid data entered. Please inform the merchant about this error."
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
amount Final amount to be paid by buyer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE:250.00
payment_desc Purpose of payment
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
  • Length: Max 1000 characters
TYPE: STRING
EXAMPLE: PARKING FEE
currency Currency of payment
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
  • 'THB' is for Thailand Currency
  • 'PHP' is for Philippines Currency
TYPE: STRING
EXAMPLE: MYR
hash The secure hash string to validate the request. Refer our Hashing Guide Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Parameter Description
buyer_name Buyer's name
  • Accept only alphabets
TYPE: STRING
EXAMPLE:JOHN
buyer_email Buyer's email. Buyer will receive payment notification at this address if specified
  • Accept only valid email address
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
phone Buyer's phone number
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
add_line_1 Buyer's address line 1
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
add_line_2 Buyer's address line 2
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
postcode Buyer's postcode
  • Accept only digits
TYPE: INTEGER
EXAMPLE:47810
city Buyer's city location
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:PETALING JAYA
comment Buyer's additional comments / notes on the purchase
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
callback_url_fe_succ 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
callback_url_fe_fail 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_FAILURE
baggage_variable If you required a variable that provide the same value after transaction has been made, use this baggage form. You can have more than one variable.
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your bagages variable name* Your value(s) of each variable(s). Must be synchonize with the total number of variable above
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VALUE1
header_title Modify your company name at payment gateway pages
  • Accepts only alphanumeric characters
  • Length: Not more than 80 characters
TYPE: STRING
EXAMPLE:PAYMENT HEADER TITLE
header_email Modify your company email address at payment gateway pages
  • Accepts only alphanumeric characters
  • Length: Not more than 50 characters
TYPE: STRING
EXAMPLE:SUPPORT@MERCHANT.COM
header_phone Modify your company phone number at payment gateway pages
  • Accepts only alphanumeric characters
  • Length: Not more than 50 characters
TYPE: STRING
EXAMPLE:+603283928242

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192
Invoice No FS789
Amount 150.00
Payment Description Description
Currency MYR

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034|FS789|19.90|Description|MYR will generate something like 9a360e54d7bc9de2b8850838cf4e7b11

Error Guide

The API will return error messages if any of the variables sent is invalid

Error Code Description
00 Success / No error
99 Fail to created a bill

Remove Created Bill

You can use this API to disable the payment URL created from Create Bill API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at the API Management page.

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
      -d merchant_id: 10010\
      -d invoice: FS789\
      -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
      

  
    
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&invoice=INV0001&hash=dc8e364d222d6025cbc505674b7012df");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response (200):

    
{
    "response": "00",
    "msg": "Payment URL successfully removed",
    "merchant_id": "10010",
    "invoice": "FS789",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

  
    
{
    "response": "00",
    "msg": "Payment URL successfully removed",
    "merchant_id": "10010",
    "invoice": "FS789",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

Response (400):

    
{
    "response": "99",
    "merchant_id": "Invoice does not exist"
}

  
    
{
    "response": "99",
    "merchant_id": "Invoice does not exist"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
hash The secure hash string to validate the request. Refer our Hashing Guide Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192
Invoice No FS789

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034|FS789 will generate something like a6f38ade42e7d8b9ce2a5879a626cc0c

Direct Payment

Use this feature if you would like to bypass QlicknPay checkout page, and direct payers straight from your system to the selected payment gateway (FPX) seamlessly. This is useful for developers who want to customize the full payment experience on their own website or mobile app and direct the payers to their Internet Banking login page.

Direct Payment Flow

  1. Request an API called ‘Get Bank List’ to get list of banks available for the payer.
  2. Merchant send a payment request to an API called ‘Direct Payment’.
  3. Payer directly to selected bank portal
  4. After payment is done, payer will directly to QlicknPay receipt page with a transaction status. Receipt page provide a button for them to return to merchant site (optional). Merchant can disable this receipt page and let the payer to skip and directly to selected pages by specify the variable called ‘skip_receipt’ and send it to Direct Payment API during request a payment.
  5. In a meantime, callback data will send to the merchant site. Please specify Callback Endpoint at your API request or you can specify it at your QlicknPay Dashboard

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information from the API Management page.

Kindly ensure the payment request you send to either of the mentioned endpoints comply to the following format using POST method. You can set fields with OPTIONAL tag to NULL or exclude it entirely if it is not required.

Required Arguments

Example request:

    
Please select PHP to view the sample code

  
  

  <?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 QlicnPay Dashboard you have key in the return URL referring to this file
  
*/
  

  
# please fill in the required info as below
  
$merchant_id = 'YOURMERCHANTID'; // this refers to your Merchant ID that can be obtain from PayDirect
  
$api = 'YOURAPIKEY'; // 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'])."|".urldecode($_POST['bank_code'])."|".urldecode($_POST['payment_method']));
  
  # now we send the data to PayDirect by using post method
  

  
  $payment_url = '{Endpoint URL}';
  

  
  ?>
  
  <html>
  
  <head>
  
  <title>Pay Direct 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="<?= $payment_url ?>">
  

  
          <!-- REQUIRED FORM START HERE -->
  
            <input type="hidden" name="merchant_id" value="<?php echo $merchant_id; ?>">
  
            <input type="hidden" name="invoice" value="<?php echo $_POST['invoice']?>">
  
            <input type="hidden" name="amount" value="<?php echo $_POST['amount']; ?>">
  
            <input type="hidden" name="payment_desc" value="<?php echo $_POST['payment_desc']; ?>">
  
            <input type="hidden" name="hash" value="<?php echo $hashed_string; ?>">
  

  
            <input type="hidden" name="bank_code" value="<?php echo $_POST['bank_code']; ?>">
  
            <input type="hidden" name="payment_method" value="<?php echo $_POST['payment_method']; ?>">
  

  

  
          <!-- 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@domain.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="Comment">
  

  
            <!-- 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.sample.com/callback_url_be.php">
  
            <!-- Your Front-end Process Success interface -->
  
            <input type="hidden" name="callback_url_fe_succ" value="https://www.sample.com/callback_fe_succ.php">
  
            <!-- Your Front-end Process Fail interface -->
  
            <input type="hidden" name="callback_url_fe_fail" value="https://www.sample.com/callback_url_fe.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 variable(s)-->
  
            <input type="hidden" name="baggage_variable" value="variable2|variable3|variable4">
  
            <!--  Your value(s) of each variable(s). Must be synchonize with the total variable above -->
  
            <input type="hidden" name="variable2" value="value2">
  
            <input type="hidden" name="variable3" value="value3">
  
            <input type="hidden" name="variable4" value="value4">
  

  
            <!-- Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true -->
  
            <input type="hidden" name="skip_receipt" value="1">
  

  
          <!--  OPTIONAL FORM END HERE -->
  

  
      </form>
  
  </body>
  
  </html>
  
  <?php
  
}
  

  
else
  
{
  
?>
  

  
  <html>
  
  <head>
  
    <title>Pay Direct Payment Gateway API Sample Code</title>
  
  </head>
  
  <body>
  
      <form method="post" action="<?php echo htmlentities($_SERVER['PHP_SELF']); ?>">
  
          <table>
  
              <tr>
  
                  <td colspan="2">Please fill up the detail below in order to test the payment.</td>
  
              </tr>
  
              <tr>
  
                  <td>Amount</td>
  
                  <td>: <input type="text" name="amount" value="" placeholder="Amount to pay, for example 12.20" size="30"></td>
  
              </tr>
  
              <tr>
  
                  <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="<?= date('His') ?>" placeholder="Unique id to reference the transaction or order" size="30"></td>
  
              </tr>
  

  
              <tr>
  
                  <td>Bank</td>
  
                  <td>:
  
                    <select name='bank_code'>
  
                      <option value='ABB0233'>Affin Bank</option>
  
                      <option value='ABMB0212'>Alliance Bank (Personal)</option>
  
                      <option value='AMBB0209'>AmBank</option>
  
                      <option value='BIMB0340'>Bank Islam</option>
  
                      <option value='BKRM0602'>Bank Rakyat</option>
  
                      <option value='BMMB0341'>Bank Muamalat</option>
  
                      <option value='BSN0601'>BSN</option>
  
                      <option value='BCBB0235'>CIMB Clicks</option>
  
                      <option value='CIT0219'>Citibank</option>
  
                      <option value='HLB0224'>Hong Leong Bank</option>
  
                      <option value='HSBC0223'>HSBC Bank</option>
  
                      <option value='KFH0346'>KFH</option>
  
                      <option value='MB2U0227'>Maybank2U</option>
  
                      <option value='MBB0228'>Maybank2E</option>
  
                      <option value='OCBC0229'>OCBC Bank</option>
  
                      <option value='PBB0233'>Public Bank</option>
  
                      <option value='RHB0218'>RHB Bank</option>
  
                      <option value='SCB0216'>Standard Chartered</option>
  
                      <option value='UOB0226'>UOB Bank</option>
  
                      <option disabled>-------------------</option>
  
                      <option value='CC00001'>Credit Card</option>
  
                      <option disabled>-------------------</option>
  
                      <option value='BOOST'>Boost eWallet</option>
  
                      <option value='TNG'>TouchNGo eWallet</option>
  
                      <option value='GRAB'>Grab eWallet</option>
  
                      <option value='SHPPAY'>Shopee Pay</option>
  
                      <option value='OVO'>OVO eWallet</option>
  
                      <option value='LINKAJA'>LinkAJA eWallet</option>


  

  
                    </select>
  
                  </td>
  
              </tr>
  

  
              <tr>
  
                  <td>Payment Method</td>
  
                  <td>:
  
                    <select name='payment_method'>
  
                      <option value='b2c'>FPX B2C</option>
  
                      <option value='b2b'>FPX B2B</option>
  
                      <option value='cc'>Credit Card</option>
  
                      <option value='ewallet'>eWallet</option>
  
                    </select>
  
                  </td>
  
              </tr>
  

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

Response (200):

    
# Directly to Payment Gateway.

  
    
# Directly to Payment Gateway.

Response (400):

    
# Invalid format data entered

  
    
# Invalid format data entered

Response (401):

    
# Invalid Merchant ID or API Key

  
    
# Invalid Merchant ID or API Key
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
amount Final amount to be paid by buyer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE:250
payment_desc Purpose of payment
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
  • Length: Max 1000 characters.
TYPE: STRING
EXAMPLE:PARKING FEE
currency Currency of payment
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
  • 'THB' is for Thailand Currency
  • 'PHP' is for Philippines Currency
TYPE: STRING
EXAMPLE:IDR
payment_method Payment Method of the payment.
  • 'b2c' for Online Banking (MYR/SGD/THB/PHP)
  • 'b2b' FPX Online Banking Business Account (MYR)
  • 'cc' for Credit Card Payment
  • 'ewallet' for eWallet Payment
  • 'indo_bank' for Indonesia Bank Portal Payment
  • 'bnpl' for Buy Now Pay Later Payment
  • 'ipp' for Instalment Payment Plan (IPP)
TYPE: STRING
EXAMPLE:b2c
agent_channel_code Conditional. This parameter is required if you are choosing 'indo_bank' as a 'payment_method'
  • 'ATM' for ATM Payment
  • 'IBANKING' for iBanking Payment
TYPE: STRING
EXAMPLE:ATM
bank_code For Online Banking (B2B, B2C):
For Credt Card Payment:
  • please set your 'bank_code' as 'CC00001'

For eWallet Payment, please choose one and set your 'bank_code' as per shown below:

Bank Code Description
BOOST Boost eWallet
GRAB GrabPay eWallet
TNG Touch N Go eWallet
SHPPAY Shopee Pay
RPP_DUITNOWQR DuitNow QR
ALIPAY Ali Pay
WECHATPAY WeChat Pay
UPOP China Union Pay
OVO OVO eWallet
LINKAJA LinkAJA eWallet
ALIPAY Ali Pay
SHPQR ShopeePay/QRIS (Indonesia)
WECHATPAY WeChat Pay
LINEPAY LINE Pay
PAYMAYA-EWALLET Maya
GCASH GrabPay eWallet (Philippines)
PN_GRABPAY GCash

For Indonesia Bank Portal Payment, please choose one and set your 'bank_code' as per shown below:

Bank Code Description
BNIS BNI Syariah
BNI BNI Bank
CIMBVA Bank CIMB
PERMATA Bank Permata
BIIVA BII Bank
MANDIRI Mandiri
BANK_OTHER ATM bersama/ Prima/ Alto
SPRINT Bank Central Asia
CIMBCLICKS OCTO CLICKS
KREDIVO Kredivo
INDOMARET Indomaret
IDFNALF Alfamart Group
AKULAKU_IDN AKULAKU

For Buy Now Pay Later Payment:

Bank Code Description
BNPL00001 PaySlowSlow / Riipay
IOUPay-PW IOUPay
Atome Atome BNPL

For Instalment Payment Plan (IPP):

Bank Code Description
IPP00001 Default IPP

TYPE: STRING
EXAMPLE:MB2U0227
hash The secure hash string to validate the payment request sent through our Payment Gateway.
  • Accept only alphabets
TYPE: STRING
EXAMPLE:PARKING FEE

Optional Arguments

Parameter Description
respond Enable or disable response data from the API. By default, an API will directly send the payer once the API is called (By using the Form POST method).

Set this value into '1' will return the response data from the API in JSON format including the URL variable called 'payment_url'. This 'payment_url' will send directly the payer to the payment portal.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE:1
buyer_name Buyer's name
  • Accept only alphabets
TYPE: STRING
EXAMPLE:JOHN
buyer_email Buyer's email. Buyer will receive payment notification at this address if specified
  • Accept only valid email address
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
phone Buyer's phone number
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
add_line_1 Buyer's address line 1
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
add_line_2 Buyer's address line 2
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
postcode Buyer's postcode
  • Accept only digits
TYPE: INTEGER
EXAMPLE:47810
city Buyer's city location
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:PETALING JAYA
comment Buyer's additional comments / notes on the purchase
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
callback_url_fe_succ 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
callback_url_fe_fail 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_FAILURE
baggage_variable If you required a variable that provide the same value after transaction has been made, use this baggage form. You can have more than one variable.
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your bagages variable name* Your value(s) of each variable(s). Must be synchonize with the total number of variable above
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VALUE1
skip_receipt Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
  • Accepts only integer
TYPE: INTEGER
EXAMPLE:1

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 1000034
Invoice No FS789
Amount 192.00
Payment Description Parking
Bank code MB2U0227
Payment Method b2c
Currency MYR

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034|FS789|19.90|Parking|MB2U0227|b2c|MYR will generate something like f175d40f33c9ab1eb26118951a147e4a

Collection Payment Link API

This API allow you to create a single Payment Link and do a multiple collection.

API Endpoint URLs

Required Arguments

Example request:

        
            
curl POST {Endpoint URL}\
            -d merchant_id: R1001\
            -d purpose: Annual Payment\
            -d amount: 1.50\
            -d delivery_option: 0\
            -d amount_option: Fixed\
            -d due_date: 2024-04-20\
            -d usage: 1\
            -d max_collection: 100.00\
            -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
            
 
        
    
        
            
 $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&purpose=Annual Payment&amount=1.50
                                &delivery_option=0&amount_option=Fixed&due_date=2024-04-20                                &usage=1&max_collection=100.00&hash=fc85b97551f5a2b8bf28d916f2f8055d");
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                $server_output = curl_exec($ch);
                curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
purpose Description of the payment link. Must be a unique
  • Accept only numbers, alphabets and spaces
  • Not more than 200 characters
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
amount_option Type of amount for payment link. Only accept a fixed or flexi amount
  • The value is "Fixed" or "Unfixed" only
  • Fixed. Customer unable to change the payment link amount
  • Unfixed. Customer able to enter their own amount.
TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed"
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
  • Must be more than RM1.50
TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields.
  • Accept ONLY numbers
  • The value is either 0 or 1
  • 0 - Disable delivery form
  • 1 - Enable delivery form
TYPE: INTERGER
EXAMPLE: 0
currency Currency of payment
  • Only 'MYR', 'IDR', and 'SGD' are available
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
TYPE: STRING
EXAMPLE:MYR
hash The secure hash string to validate the request. Refer below hashing guide for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
due_date Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE
EXAMPLE: 2024-04-20
usage Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments.
  • The payment link will automatically disable once the maximum total is reached
  • Only accept interger
TYPE: INTERGER
EXAMPLE: 44
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50.
  • The payment link will automatically disable once the maximum amount collection is reached
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
  • Must be more than RM1.50
TYPE: STRING
EXAMPLE: 1500.55

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant_id R1001
purpose Annual Payment
delivery_option 0
amount_option Fixed
amount 10.00
currency MYR

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Sample code to hash above values:
md5("$api|$merchant_id|$purpose|$amount_option|$amount|$delivery_option|$currency");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

"YOURAPIKEY00192|R1001|Annual Payment|Fixed|10.00|0|MYR" will generate something like 40a78c01b5e2e9565b0d02196ec28047

For "Unfixed" payment link, below is a sample details:
"YOURAPIKEY00192|R1001|Annual Payment|Unfixed||0|MYR" will generate something like f262522ea66154fd83d2068ee3820235

Respond data

The response data after calling the API

Example response:

        
            

                 
                     {
                    "response":"00",
                    "payment_link_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                    "purpose":"Donation for kids",
                    "amount_option": "Fixed",
                    "amount":100,
                    "delivery_option":1,
                    "merchant_id":"R1233"
                    "due_date":"2023-08-02",
                    "usage":8,
                    "max_collection":"6779"
                    "hash":"fc85b97551f5a2b8bf28d916f2f8055d"
                    } 
                
            

        
    
        
            

                 
                 {
                    "response":"00",
                    "payment_link_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                    "purpose":"Donation for kids",
                    "amount_option": "Fixed",
                    "amount":100,
                    "delivery_option":1,
                    "merchant_id":"R1233"
                    "due_date":"2023-08-02",
                    "usage":8,
                    "max_collection":"6779"
                    "hash":"fc85b97551f5a2b8bf28d916f2f8055d"
                    }
Parameter Description
response
Response code of the status of created Payment Link.
00 - Successfull
99 - Unsucessfull
TYPE: INTERGER
payment_link_url
Response Unique Url of the created Payment Link.
TYPE: INTERGER
purpose
Description of the payment link. Must be a unique
TYPE: INTERGER
amount_option
Type of amount for payment link. Only accept a fixed or flexi amount.
TYPE: STRING
merchant_id
Your merchant ID
TYPE: STRING
due_date
Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE
usage
Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments. TYPE: INTERGER
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50. TYPE: STRING

Delete Collection Payment Link API

This API allows you to Delete collection of Payment Links.

API Endpoint URLs

Example request:

    
                         
curl POST {Endpoint URL}\
          -d id: 7\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "id=7&merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $server_output = curl_exec($ch);
    curl_close ($ch)
Field Name Description
Id Your Payment link ID. You can get your Payment Link ID by calling List Collection Payment Link API
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: 1
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer below hashing guide for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

"YOURAPIKEY00192|R1001|13" will generate something like a68115315fbc9759076dcf7a058ce221

Respond data

The response data after calling the API

Example response:

    
  {
    "id": "13",
    "merchant_id": "R1001",
    "response": "00",
    "msg": "Success Deleted",
} 

  
    
  {
    "id": "13",
    "merchant_id": "R1001",
    "response": "00",
    "msg": "Success Deleted",
}
Parameter Description
Id
 Your Payment Link ID.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
response Response code of the status of deleted Payment Link.
msg Status message of the payemnet link depend on the response code from response.
TYPE: STRING

List Collection Payment Link API

This API allows you to access a list collection of Payment Links.

API Endpoint URLs

Example request:

    
          
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
        
            

            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS,
            "merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d");
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            $server_output = curl_exec($ch);
            curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer below hashing guide for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Sample code to hash above values:
md5("$api|$merchant_id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

"YOURAPIKEY00192|R1001" will generate something like e4a9dd90a49380fa4a34105fb8bacba5

Respond data

The response data after calling the API

Example response:

        
            


{
    "respon":"00",
    "merchant_id":"R1233",
    "data": [
                {
                "id":17,
                "inv_number":"INV0004",
                "amount_option":"Fixed",
                "amount":3131,
                "delivery_option":0,
                "status":"Active",
                "payment_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                "logo_url":null,
                "qr_url": URL,
                "created_at":"2023-07-28T02:28:17.000000Z",
                "updated_at":"2023-07-28T02:28:17.000000Z",
                "deleted_at":null
                },
            ]
} 

            

        
  
    
        

             
{
    "respon":"00",
    "merchant_id":"R1233",
    "data": [
                {
                "id":17,
                "inv_number":"INV0004",
                "amount_option":"Fixed",
                "amount":3131,
                "delivery_option":0,
                "status":"Active",
                "payment_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                "logo_url":null,
                "qr_url": URL,
                "created_at":"2023-07-28T02:28:17.000000Z",
                "updated_at":"2023-07-28T02:28:17.000000Z",
                "deleted_at":null
                },
            ]
}
Parameter Description
merchant_id Your Merchant ID.
TYPE: STRING
Id
 Your Payment Link ID.
TYPE: STRING
inv_number Unique invoice number.
TYPE: STRING
purpose Description of the payment link.
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
amount_option Type of amount option for payment link.
TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed"
TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields.
TYPE: INTERGER
EXAMPLE: 0
logo_url The URL for payment is generated by the system.
TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
qr_url The URL for payment is generated by the system.
TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
usage
Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments. TYPE: INTERGER
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50. TYPE: STRING
due_date
Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE

Report Collection Payment Link API

This API allows you to access a list collection of Payment Links.

API Endpoint URLs

Example request:

    
          
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          -d date_from: 2023-06-01\
          -d date_to: 2023-07-27\ 
          -d purpose: donation for kids\
          
 
  
        
            

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d
                                &date=2023-06-01&date_to=2023-07-27
                                &purpose=donation for kids");
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                $server_output = curl_exec($ch);
                curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
TYPE: STRING
EXAMPLE: R1001
date_from By default the date will be the date of first transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
date_to By default the date will be the date of last batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
status By default the status will display all the status of the transactions.
0 - All successful payments
1 - All fail payments
TYPE: STRING
EXAMPLE: 1
purpose Description of the payment link. TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Sample code to hash above values:
md5("$api|$merchant_id|$purpose|$date_to|$date_from");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

"YOURAPIKEY00192|R1001|donation for kids|2023-07-27|2023-06-01" will generate something like b280fb8b6d0a7d81a5be475a64107db6

Respond data

The response data after calling the API

Example response:

    
 
{
    "response": "00",
    "merchant_id": "R1233",
    "date_from": "2023-07-01",
    "date_to": "2023-08-01",
    "purpose": null,
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "data": [
        {
            "transaction_id": null,
            "total_amount": null,
            "invoice": null,
            "buyer_name": null,
            "buyer_email": null,
            "phone": null,
            "address": null,
            "city": null,
            "state": null,
            "postcode": null,
            "comment": null,
            "status": null,
            "pay_method": null,
            "callback_be": null,
            "currency": null,
            "created_at": "2023-07-10T08:01:03.000000Z"
        }
],
}



  
    
 
    {
    "response": "00",
    "merchant_id": "R1233",
    "date_from": "2023-07-01",
    "date_to": "2023-08-01",
    "purpose": null,
    "data": [
        {
            "transaction_id": null,
            "total_amount": null,
            "invoice": null,
            "buyer_name": null,
            "buyer_email": null,
            "phone": null,
            "address": null,
            "city": null,
            "state": null,
            "postcode": null,
            "comment": null,
            "status": null,
            "pay_method": null,
            "callback_be": null,
            "currency": null,
            "created_at": "2023-07-10T08:01:03.000000Z"
        }
],
}
Parameter Description
response Response code of the status of list collection Payment Link.
00 - Successfull
99 - Unsuccessfull
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
Id
 Your Payment Link ID.
TYPE: STRING
date_from By default the date will be the date of first batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
date_to By default the date will be the date of last batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
purpose Description of the payment link. TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
transaction_id Unique transaction ID generate by Betterpay.
TYPE: INTERGER
amount_option Type of amount option for payment link. TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed" TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields. TYPE: INTERGER
EXAMPLE: 0
buyer_name Description of the payment link. TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
phone Buyer's phone number TYPE: STRING
EXAMPLE: 017-86331311
address Buyer's address
TYPE: STRING
EXAMPLE: LOT 12, Taman Jaya
city Buyer's city
TYPE: STRING
EXAMPLE: kOTA BHARU
state Buyer's state
TYPE: STRING
EXAMPLE: KELANTAN
postcode Buyer's postcode
TYPE: INTERGER
EXAMPLE: 160000
comment Buyer's additional comments / notes on the purchase TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
status By default the status will display all the status of the transactions.
TYPE: STRING
EXAMPLE: OMMENT HERE FOR MERCHANT REFERENCE
callback_be Description of callback TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
currency Currency of payment
TYPE: STRING
EXAMPLE: MYR
created_at Date of the transaction being make TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
logo_url The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
qr_url The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
created_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
updated_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
deleted_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004

Recurring Payment - Direct Debit

Direct Debit Recurring payments are automated payments that are carried out periodically (daily*, monthly, weekly, annually), of those consumption charges of goods or services such as memberships, subscriptions, policies or receipts with fixed value; that were previously authorized by the customer.

Direct Debit Recurring payments happen in the background. Authorization or Enrollment is done one via E-Mandate . The customer goes through the payment steps only once, for the first payment that will be charged RM1.00.

In the following sections we explain the following APIs.

  • Create subscription package
  • Adding new subscribers by referring to available subscriptions
  • Modify subscribers agreement or terminate subscription
  • View your current subscription package and subscribers

You must create/add subscription package before you can add subscribers

Add subscriptions

QlicknPay allows flexibility for merchants to create subscription models for their business. We provide 3 different subscription types:

Fixed : Merchants that charges the same amount every billing period - e.g Gym Membership
Flexi : Allow subscribers to determine bill amount - e.g. Donation
Calculated : Merchants that offer Tiering amount according to expiry date - e.g. Hire Purchase

API Endpoint URLs

Required Arguments (Add Subscriptions)

Example request (Add New Fixed Package):

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_type":"fixed","terms":"Monthly","subscription_id":"FIXED001","name":"Monthly Subs","price":"105.00","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$ch = curl_init();
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  "merchant_id=10010&subscription_type=fixed&terms=Monthly&subscription_id=FIXED001&name=Monthly Subs&price=105.00&purpose=Music Subscription&hash=fc85b97551f5a2b8bf28d916f2f8055d");

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Example request (Add New Flexi Package):

      
curl POST {Endpoint URL}\
        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_type":"flexi","terms":"Monthly","subscription_id":"FLEX001","name":"Monthly Subs","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$ch = curl_init();
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  "merchant_id=10010&subscription_type=flexi&terms=Monthly&subscription_id=FLEX001&name=Monthly Subs&purpose=Music Subscription&hash=fc85b97551f5a2b8bf28d916f2f8055d");

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Example request (Add New Calculated Subscription Package):

      
curl POST {Endpoint URL}\
        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_type":"calculated","terms":"Monthly","subscription_id":"CALC001","name":"Monthly Subs","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d","repayment_periods":{{"total":"2","terms":"Month","amount":"105.00"},{"total":"4","terms":"Month","amount":"195.00"}}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'subscription_type' => 'calculated',
          'terms' => 'Monthly',
          'subscription_id' => 'CALC001',
          'name' => 'Monthly Subs',
          'purpose' => 'Music Subscription',
          'repayment_periods' =>
           array(
             1 =>
              array(
               'total' => '2',
               'terms' => 'Month',
               'amount' => '105.00',
               ),

             2 =>
              array(
               'total' => '2',
               'terms' => 'Month',
               'amount' => '',
               ),
            ),
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Response (200):

      
{
    "response": "00",
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "calculated",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "2": {
            "amount": "195.00"
        }
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}

    
      
{
    "response": "00",
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "calculated",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "2": {
            "amount": "195.00"
        }
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscription_type Your type of subscription package. Use 'fixed' if your need a fixed amount for subscription (No expiry date) OR choose 'flexi' if you need your payer specify their own amount (No expiry date) OR choose 'calculated' if the subscription have multiple option of fixed amount (Have expiry date)

*Expiry date is the last date of the payment. Otherwise, the subscription is keep going until subscribers decide to terminated the subscription.
  • Only 'fixed', 'flexi' OR 'calculated' are accepted
TYPE: STRING
EXAMPLE: fixed
terms Terms or payment frequency of the subscription. For 'Flexi' subscription package, you can set it as empty value if you want your payer decide the payment frequency.
  • Only 'Daily', 'Weekly', 'Monthly' OR 'Yearly' are accepted
TYPE: STRING
EXAMPLE: Monthly
subscription_id Unique ID for your subscription package
  • Accept alphabets and numbers only.
  • Length: Max 18 characters.
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED001
name Name of your subscription
  • Accept alphanumeric.
  • Length: Max 50 characters.
TYPE: STRING
EXAMPLE: Monthly Subscription
price Price of the subscription. This variable is only available for 'fixed' subscription package. Otherwise, please ignore this variable.
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: 105.00
purpose Short description of the subscription
  • Accept alphanumeric.
  • Length: Max 27 characters.
TYPE: STRING
EXAMPLE: Music Subscription 1
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Required Arguments for 'Calculated' Subscription Package (Add Subscriptions)

This is the variables that store in an array called 'repayment_periods' and encode into JSON format.

Field Name Description
repayment_periods: {
  total : 'value'
} 		Repayment period total. (Example: If the value is '2' then the subscription is only for 2 weeks/months/years)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 5
{
  terms : 'value'
} 		Repayment period terms. (Example: If the value is 'Month' then the subscription is only for < repayment period total > x Months)
  • Only 'Week', 'Month' OR 'Year' are accepted
TYPE: STRING
EXAMPLE: Month
{
  amount : 'value'
} 		Repayment period amount. This is not a total amount but an amount for each terms that has specified. (Example: If the value is '20.00' then the subscription is RN20.00 for each < repayment period total >)
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 20.00
TYPE: STRING
EXAMPLE: 20.00

Optional Arguments (Add Subscription)

Field Name Description
max_debit_frequency Maximum number of direct debit transactions allowed with the mandate for the selected frequency. For instance, if "MONTHLY" is given as the value to the 'terms' parameter, the number given will be the maximum number of direct debit transactions per month.
  • Must be more than 0 and less than 99
TYPE: STRING
EXAMPLE: 3

Hashing Guide (Add Subscription)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 1000034
Subscription ID CALC001
Subscription Type calculated
Subscription Name Monthly Subs
Price
*You can set this as empty value
if the subscription type is not a
'fixed' type subscription 		10.00
Terms Monthly
Purpose Music Subscription

Sample code to hash above values:
md5("$api|$merchant_id|$subscription_id|$subscription_type|$name|$price|$terms|$purpose");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

For 'calculated' subcription package "YOURAPIKEY00192|1000034|CALC001|calculated|Monthly Subs||Monthly|Music Subscription" will generate something like a03086c86be8a3ed4097925f06ba43b8
For 'fixed' subcription package "YOURAPIKEY00192|1000034|CALC001|fixed|Monthly Subs|10.00|Monthly|Music Subscription" will generate something like df36fd7bde1461b93d15639c3ecdd9f9

Update subscriptions

Use this API to update your existing subscription plan:

API Endpoint URLs

Required Arguments (Update Subscriptions)

Example request (Update Fixed Package):

    
curl POST {Endpoint URL}\

      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","terms":"Monthly","subscription_id":"FIXED001","price":"105.00","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

      

  
    
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10010&terms=Monthly&subscription_id=FIXED001&price=105.00&purpose=Music Subscription&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example request (Update Flexi Package):

    
curl POST {Endpoint URL}\
      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","terms":"Monthly","subscription_id":"FLEX001","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

      

  
    
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10010&terms=Monthly&subscription_id=FLEX001&purpose=Music Subscription&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example request (Update Calculated Subscription Package):

    
curl POST {Endpoint URL}\
      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","terms":"Monthly","subscription_id":"CALC001","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d","repayment_periods":{{"total":"2","terms":"Month","amount":"105.00"},{"total":"4","terms":"Month","amount":"195.00"}}'\

      

  
    
$data_request = array(
        'merchant_id' => '10010',
        'terms' => 'Monthly',
        'subscription_id' => 'CALC001',
        'purpose' => 'Music Subscription',
        'repayment_periods' =>
         array(
           1 =>
            array(
             'total' => '2',
             'terms' => 'Month',
             'amount' => '105.00',
             ),

           2 =>
            array(
             'total' => '2',
             'terms' => 'Month',
             'amount' => '',
             ),
          ),
        'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
      );

    $fields_string = json_encode($data_request);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                $fields_string);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response (200):

    
{
    "response": "00",
    "msg": "Mandate successfully updated",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}

  
    
{
    "response": "00",
    "msg": "Mandate successfully updated",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscription_id Unique ID from your created Subscription
  • Accept alphabets and numbers only.
  • Length: Max 18 characters.
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments (Update Subscription)

Field Name Description
terms Terms or payment frequency of the subscription. For 'Flexi' subscription package, you can set it as empty value if you want your payer decide the payment frequency.
  • Only 'Daily', 'Weekly', 'Monthly' OR 'Yearly' are accepted
TYPE: STRING
EXAMPLE: Monthly
price Price of the subscription. This variable is only available for 'fixed' subscription package. Otherwise, please ignore this variable.
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: 105.00
purpose Short description of the subscription
  • Accept alphanumeric.
  • Length: Max 27 characters.
TYPE: STRING
EXAMPLE: Music Subscription 1
max_debit_frequency Maximum number of direct debit transactions allowed with the mandate for the selected frequency. For instance, if "MONTHLY" is given as the value to the 'terms' parameter, the number given will be the maximum number of direct debit transactions per month.
  • Must be more than 0 and less than 99
TYPE: STRING
EXAMPLE: 3

Optional Arguments for 'Calculated' Subscription Package

This is the variables that store in an array called 'repayment_periods' and encode into JSON format.

Field Name Description
repayment_periods: {
  total : 'value'
} 		Repayment period total. (Example: If the value is '2' then the subscription is only for 2 weeks/months/years)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 5
{
  terms : 'value'
} 		Repayment period terms. (Example: If the value is 'Month' then the subscription is only for < repayment period total > x Months)
  • Only 'Week', 'Month' OR 'Year' are accepted
TYPE: STRING
EXAMPLE: Month
{
  amount : 'value'
} 		Repayment period amount. This is not a total amount but an amount for each terms that has specified. (Example: If the value is '20.00' then the subscription is RN20.00 for each < repayment period total >)
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 20.00
TYPE: STRING
EXAMPLE: 20.00

Hashing Guide (Update Subscription)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 1000034
Subscription ID CALC001

Sample code to hash above values:
md5("$api|$merchant_id|$subscription_id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

For 'calculated' subcription package "YOURAPIKEY00192|1000034|CALC001" will generate something like a567eaa6fed7d3df0c29542de0518388

Add subscribers

API Endpoint URLs

URL Parameters (Add Subscribers)

Field Name Description
{Subscription ID} Your Unique Subscription ID
  • Accept alphabets and numbers only
  • Length: Max 18 characters
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED01

Required Arguments (Add Subscribers)

Example request (Add New Subscribers for Fixed Package):

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"bank_id":"MB2U0227","hash":"fc85b97551f5a2b8bf28d916f2f8055d","subscriber_details":{{"id_number":"960547015374"},{"id_type":"1"},{"reference_no":"101"},{"email":"john@domain.com"},{"name":"Shahrul Izwan"},{"phone":"0173649558"}},"callbacks":{{"back_end":"https://webina.me/callback"},{"fe_success":"https://webina.me/success"},{"fe_fail":"https://webina.me/fail"}}'\

        

    
      
$data_request = array(
          'merchant_id' => '',
          'subscriber_details' =>
           array(
               'id_number' => '960547015374',
               'id_type' => '1',
               'reference_no' => '101',
               'email' => 'john@domain.com',
               'name' => 'Shahrul Izwan',
               'phone' => '0173649558',
            ),
            'callbacks' =>
             array(
                 'back_end' => 'https://webina.me/callback',
                 'fe_success' => 'https://webina.me/success',
                 'fe_fail' => 'https://webina.me/fail',
              ),

          'bank_id' => 'MB2U0227',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Example request (Add New Subscribers for Flexi Package):

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"mandate_frequency":"Yearly","bank_id":"MB2U0227","amount":"10.00","hash":"fc85b97551f5a2b8bf28d916f2f8055d","subscriber_details":{{"id_number":"960547015374"},{"id_type":"1"},{"reference_no":"101"},{"email":"john@domain.com"},{"name":"Shahrul Izwan"},{"phone":"0173649558"}},"callbacks":{{"back_end":"https://webina.me/callback"},{"fe_success":"https://webina.me/success"},{"fe_fail":"https://webina.me/fail"}}'\

        

    
      
$data_request = array(
          'merchant_id' => '',
          'subscriber_details' =>
           array(
               'id_number' => '960547015374',
               'id_type' => '1',
               'reference_no' => '101',
               'email' => 'john@domain.com',
               'name' => 'Shahrul Izwan',
               'phone' => '0173649558',
            ),
            'callbacks' =>
             array(
                 'back_end' => 'https://webina.me/callback',
                 'fe_success' => 'https://webina.me/success',
                 'fe_fail' => 'https://webina.me/fail',
              ),

          'mandate_frequency' => 'Yearly',
          'amount' => '10.00',
          'bank_id' => 'MB2U0227',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Example request (Add New Subscribers for Calculated Package):

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","mandate_frequency":"Yearly","bank_id":"MB2U0227","hash":"fc85b97551f5a2b8bf28d916f2f8055d","subscriber_details":{{"id_number":"960547015374"},{"id_type":"1"},{"reference_no":"101"},{"email":"john@domain.com"},{"name":"Shahrul Izwan"},{"phone":"0173649558"}},"callbacks":{{"back_end":"https://webina.me/callback"},{"fe_success":"https://webina.me/success"},{"fe_fail":"https://webina.me/fail"}},"repayment_periods":{{"total":"2"},{"terms":"Year"},{"amount":"10.00"}}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'subscriber_details' =>
           array(
               'id_number' => '960547015374',
               'id_type' => '1',
               'reference_no' => '101',
               'email' => 'john@domain.com',
               'name' => 'Shahrul Izwan',
               'phone' => '0173649558',
            ),
            'callbacks' =>
             array(
                 'back_end' => 'https://webina.me/callback',
                 'fe_success' => 'https://webina.me/success',
                 'fe_fail' => 'https://webina.me/fail',
              ),

          'mandate_frequency' => 'Yearly',
          'bank_id' => 'MB2U0227',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',

          'repayment_periods' =>
           array(
               'total' => '2',
               'terms' => 'Year',
               'amount' => '10.00',
            ),

        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Response (200):

      
{
    "response": "00",
    "system_subscriber_id": "80",
    "amount": "10.00",
    "frequency": "Yearly",
    "subscriber_details": {
        "reference_no": "101"
    },
    "callbacks": {
        "fe_fail": "https:\/\/webina.me\/fail"
    },
    "bank_id": "MB2U0227",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "paymentURL": "https:\/\/bit.ly\/SAMPLE01",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}

    
      
{
    "response": "00",
    "system_subscriber_id": "80",
    "amount": "10.00",
    "frequency": "Yearly",
    "subscriber_details": {
        "reference_no": "101"
    },
    "callbacks": {
        "fe_fail": "https:\/\/webina.me\/fail"
    },
    "bank_id": "MB2U0227",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "paymentURL": "https:\/\/bit.ly\/SAMPLE01",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscriber_details: {id_number:value} Payer ID Number (Ex: IC Number)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 950711251499
subscriber_details: {id_type:value} ID Number Type
  • Accept only either '1', '2', '3' or '4'
  • 1 - New IC Number
  • 2 - Old IC Number
  • 3 - Passport Number
  • 4 - Business Registration
  • 5 - Others
TYPE: INTEGER
EXAMPLE: 1
subscriber_details: {name:value} Subscribers full name
  • Accept alphabets and empty space only
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
subscriber_details: {reference_no:value} Your reference no
  • Accept only number with no empty spaces. Maximum 10 characters
TYPE: INTEGER
EXAMPLE: 101
mandate_frequency If the subscription package is flexi, this variable is mandatory
  • Only 'Daily', 'Weekly', 'Monthly' OR 'Yearly' are accepted
TYPE: STRING
EXAMPLE: Monthly
bank_id Subscriber selected bank
  • Please proceed with Get Bank List API to retrieve your bank code
TYPE: STRING
EXAMPLE: MB2U0227
amount This variable is mandatory for Flexi Subscription
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: MB2U0227
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Required Arguments for 'Calculated' Subscription Package (Add Subscribers)

Field Name Description
repayment_periods: {total:value} Repayment period total. (Example: If the value is '2' then the subscription is only for 2 weeks/months/years)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 5
repayment_periods: {terms:value} Repayment period terms. (Example: If the value is 'Month' then the subscription is only for < repayment period total > x Months)
  • Only 'Week', 'Month' OR 'Year' are accepted
TYPE: STRING
EXAMPLE: Month
repayment_periods: {amount:value} Repayment period amount. This is not a total amount but an amount for each terms that has specified. (Example: If the value is '20.00' then the subscription is RN20.00 for each < repayment period total >)
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 20.00
TYPE: STRING
EXAMPLE: 20.00

Optional Arguments (Add Subscribers)

Field Name Description
payment_method Payment method of the emandate.
  • Only accept either 'b2c' or 'b2b'. By default this value will be 'b2c'
TYPE: STRING
EXAMPLE: b2c
subscriber_details: {email:value} Subscriber email address
  • Accept only valid email address
TYPE: STRING
EXAMPLE: JOHN@DOMAIN.COM
subscriber_details: {phone:value} Subscriber phone number
  • Accept only numbers
TYPE: STRING
EXAMPLE: 0173649226
callbacks: {back_end:value} Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • The default callback URL value set during Add Subscription API will be ignored if this field is specified
TYPE: STRING
EXAMPLE: https://www.webina.me/callback
callbacks: {fe_success:value} Return URL for your front-end successful transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • The default callback URL value set during Add Subscription API will be ignored if this field is specified
TYPE: STRING
EXAMPLE: https://www.webina.me/success
callbacks: {fe_fail:value} Return URL for your front-end failed transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • The default callback URL value set during Add Subscription API will be ignored if this field is specified
TYPE: STRING
EXAMPLE: https://www.webina.me/failed

Hashing Guide (Add Subscription)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 1000034
Amount 10.00
Subscriber ID Number 960547015374
Subscriber Email john@domain.com
Subscriber Reference Number 101
Callback URL https://www.webina.me/callback
Bank ID MB2U0227

Sample code to hash above values:
md5("$api|$merchant_id|$amount|$subscriber_id_no|$subscriber_email|$subscriber_ref_no|$callback_be|$bank_id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|1000034|10.00|960547015374|john@domain.com|101|https://www.webina.me/callback|MB2U0227" will generate something like 6df2c4af1400bb8a0fc81e1ad00d3c0c

Get subscribers

View all available subscribers from the specific subscription package

API Endpoint URLs

URL Parameters (Add Subscribers)

Field Name Description
{Subscription ID} Your Unique Subscription ID
  • Accept alphabets and numbers only
  • Length: Max 18 characters
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED01

Required Arguments (Get Subscribers)

Example request (Get Subscribers):

        
curl POST {Endpoint URL}\
              -d merchant_id: 10010\
              -d page: 1\
              -d no_of_record_per_page: 100\
              -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
              

        
      
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                    "merchant_id=10010&page=1&no_of_record_per_page=100&hash=fc85b97551f5a2b8bf28d916f2f8055d");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $server_output = curl_exec($ch);

        curl_close ($ch)

Response (200):

          
{
    "response": "00",
    "total_page_available": "1",
    "0": {
        "modified": "2021-03-16 12:23:09"
    }
}

        
          
{
    "response": "00",
    "total_page_available": "1",
    "0": {
        "modified": "2021-03-16 12:23:09"
    }
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments (Get Subscribers)

Field Name Description
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2
no_of_record_per_page No of record per pages. By default it will display 100 records per pages.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 50

Hashing Guide (Get Subscribers)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Subscription ID FIXED01

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|10010|FIXED01" will generate something like 354615fe013e6d5a2393270fe24546db

Get Subscriber Details

Get subscribers details by referring to your Subscriber Reference Number

API Endpoint URLs

URL Parameters (Get Subscriber Details)

Field Name Description
{Subscriber Reference No} Your Unique Subscriber Reference No
  • Accept only number
  • Length: Max 12 characters
  • No empty spaces
TYPE: INTEGER
EXAMPLE: 101

Required Arguments (Get Subscribers Details)

Example request (Get Subscriber Details):

            
curl POST {Endpoint URL}\
                  -d merchant_id: 10010\
                  -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                  

            
          
            
$ch = curl_init();
            curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10010&hash=fc85b97551f5a2b8bf28d916f2f8055d");

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $server_output = curl_exec($ch);

            curl_close ($ch)

Response (200):

              
{
    "response": "00",
    "subscriber_ref_no": "101",
    "name": "Shahrul Izwan",
    "id_number": "950711251499",
    "phone": "0173649558",
    "email": "john@domain.com",
    "subscription_id": "FIXED01",
    "active_date": "2021-03-16",
    "subscription_name": "Monthly Subscription",
    "amount": "101.00",
    "subscription_purpose": "Music Subscription",
    "fpx_reference_no": "C10010R101A5",
    "subscription_status": "active",
    "created": "2021-03-16 12:22:45",
    "modified": "2021-03-16 12:23:09"
}

            
              
{
    "response": "00",
    "subscriber_ref_no": "101",
    "name": "Shahrul Izwan",
    "id_number": "950711251499",
    "phone": "0173649558",
    "email": "john@domain.com",
    "subscription_id": "FIXED01",
    "active_date": "2021-03-16",
    "subscription_name": "Monthly Subscription",
    "amount": "101.00",
    "subscription_purpose": "Music Subscription",
    "fpx_reference_no": "C10010R101A5",
    "subscription_status": "active",
    "created": "2021-03-16 12:22:45",
    "modified": "2021-03-16 12:23:09"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide (Get Subscriber Details)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Subscribers Reference No 101

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|10010|101" will generate something like 9fdf8fa3241f509f05250dc3a9879a92

Get Subscription

Get all subscription package

API Endpoint URLs

Required Arguments (Get Subscriptions)

Example request:

              
                
curl POST {Endpoint URL}\
                -d merchant_id: 10001\
                -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                
 
              
            
              
                                
$ch = curl_init();
              curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
              curl_setopt($ch, CURLOPT_POST, 1);
              curl_setopt($ch, CURLOPT_POSTFIELDS,
                          "merchant_id=10001&hash=fc85b97551f5a2b8bf28d916f2f8055d");

              curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

              $server_output = curl_exec($ch);

              curl_close ($ch)

Example response (200):

    
[
    {
        "response": 00,
        "mandates": 
          {
            "subscription_id": "BASIC0001",
            "subscription_type": "Fixed",
            "name": "Basic Membership",
            "price": "10.00",
            "terms": "Monthly",
            "purpose": "Membership Registration",
            "max_debit_frequency": "2",
            "created": "2020-07-27 00:08:50"
          },
          {
            "subscription_id": "BASIC0002",
            "subscription_type": "Calculated",
            "name": "Basic Membership",
            "price": "Calculated",
            "terms": "Weekly",
            "purpose": "Membership Registration",
            "max_debit_frequency": "2",
            "created": "2020-07-27 00:08:50",
            "repayment_periods": 
              {
                "total": "1",
                "terms": "Month",
                "amount": "10.00",
                "expiry_date": "260522",
              },
              {
                "total": "2",
                "terms": "Month",
                "amount": "20.00",
                "expiry_date": "260622",
              },
              {
                "total": "2",
                "terms": "Week",
                "amount": "30.00",
                "expiry_date": "100522",
              }
          }
    }
]


  
    
[
    {
        "response": 00,
        "mandates": 
          {
            "subscription_id": "BASIC0001",
            "subscription_type": "Fixed",
            "name": "Basic Membership",
            "price": "10.00",
            "terms": "Monthly",
            "purpose": "Membership Registration",
            "max_debit_frequency": "2",
            "created": "2020-07-27 00:08:50"
          },
          {
            "subscription_id": "BASIC0002",
            "subscription_type": "Calculated",
            "name": "Basic Membership",
            "price": "Calculated",
            "terms": "Weekly",
            "purpose": "Membership Registration",
            "max_debit_frequency": "2",
            "created": "2020-07-27 00:08:50",
            "repayment_periods": 
              {
                "total": "1",
                "terms": "Month",
                "amount": "10.00",
                "expiry_date": "260522",
              },
              {
                "total": "2",
                "terms": "Month",
                "amount": "20.00",
                "expiry_date": "260622",
              },
              {
                "total": "2",
                "terms": "Week",
                "amount": "30.00",
                "expiry_date": "100522",
              }
          }
    }
]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments (Get Subscriptions)

Field Name Description
page List of the mandates will be display by referring to the page number. Maximum list per pages is 100 mandates.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 2
offset List of mandates display per pages. Must be below 100 mandates.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 50

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 10001
API YOURAPIKEY00192

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10001 will generate something like f77099c4467380801bc45481419ecab0

Get Subscription Details

Get subscription package details by referring to your Subscription ID

API Endpoint URLs

URL Parameters (Get Subscription Details)

Field Name Description
{Subscription ID} Your Unique Subscription ID
  • Accept alphabets and numbers only
  • Length: Max 18 characters
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED01

Required Arguments (Get Subscription Details)

Example request (Get Subscription Details):

                
curl POST {Endpoint URL}\
                      -d merchant_id: 10010\
                      -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                      

                
              
                
$ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                            "merchant_id=10010&hash=fc85b97551f5a2b8bf28d916f2f8055d");

                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                $server_output = curl_exec($ch);

                curl_close ($ch)

Response (200):

                
{
    "response": "00",
    "subscription_id": "CALCULATED01",
    "subscription_type": "Calculated",
    "name": "Monthly Subscription",
    "price": "Calculated",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "created": "2021-03-15 11:34:45",
    "repayment_periods": {
        "1": {
            "amount": "25.00"
        }
    }
}

              
                
{
    "response": "00",
    "subscription_id": "CALCULATED01",
    "subscription_type": "Calculated",
    "name": "Monthly Subscription",
    "price": "Calculated",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "created": "2021-03-15 11:34:45",
    "repayment_periods": {
        "1": {
            "amount": "25.00"
        }
    }
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide (Get Subscription Details)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Subscription ID CALCULATED01

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|10010|CALCULATED01" will generate something like 2f7822692f2163fd641c390167966cee

Modify Active Subscriber

Modify details of the existing and active subscriber. This API will return URL for subscriber to proceed to the bank portal for verification.

API Endpoint URLs

URL Parameters (Modify Subscriber)

Field Name Description
{Subscriber Reference No} Your Unique Subscriber Reference No
  • Accept only number
  • Length: Max 12 characters
  • No empty spaces
TYPE: INTEGER
EXAMPLE: 101

Required Arguments (Modify Active Subscriber)

Example request (Modify Active Subscriber):

                
curl POST {Endpoint URL}\
              -H 'Content-Type: application/json'\
              -d '{"merchant_id":"10010","terms":"Yearly","price":"10.20","last_date_payment":"2021-10-16","hash":"fc85b97551f5a2b8bf28d916f2f8055d","subscriber_details":{{"phone":"0173649226"},{"email":"johnv2@domain.com"}}'\
              

                
              
                
$data_request = array(
                    'merchant_id' => '10010',
                    'terms' => 'Yearly',
                    'price' => '10.20',
                    'subscriber_details' =>
                     array(
                         'email' => 'johnv2@domain.com',
                         'phone' => '0173649226',
                      ),

                    'last_date_payment' => '2021-10-16',
                    'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                  );

                $fields_string = json_encode($data_request);

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                            $fields_string);

                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                $server_output = curl_exec($ch);

                curl_close ($ch)

Response (200):

                
"https://www.qlicknpay.com/merchant/mandate/update?U0FNUExFMTIzNDU="

              
                
"https://www.qlicknpay.com/merchant/mandate/update?U0FNUExFMTIzNDU="
Field Name Description
merchant_id Your merchant ID
  • Accept only number
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments (Modify Active Subscriber)

Field Name Description
terms Terms or payment frequency of the subscription
  • Only 'Daily', 'Weekly', 'Monthly' OR 'Yearly' are accepted
TYPE: STRING
EXAMPLE: Monthly
price Price of the subscription
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: 105.00
last_date_payment Date of the last day of the subscription
  • Date format yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2021-10-16
subscriber_details: {phone:value} Subscriber phone number
  • Accept only numbers
TYPE: STRING
EXAMPLE: 0173649226
subscriber_details: {email:value} Subscriber email address
  • Accept only valid email address
TYPE: STRING
EXAMPLE: JOHN@DOMAIN.COM

Hashing Guide (Modify Active Subscriber)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Subscriber Reference No 101

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|10010|101" will generate something like 9fdf8fa3241f509f05250dc3a9879a92

Terminate Active Subscriber

Terminate active subcriber. This API will return URL for subscriber to proceed to the bank portal for verification.

API Endpoint URLs

URL Parameters (Terminate Subscribers)

Field Name Description
{Subscriber Reference No} Your Unique Subscriber Reference No
  • Accept only number
  • Length: Max 12 characters
  • No empty spaces
TYPE: INTEGER
EXAMPLE: 101

Required Arguments (Modify Active Subscriber)

Example request (Modify Active Subscriber):

                    
curl POST {Endpoint URL}\
                  -H 'Content-Type: application/json'\
                  -d '{"merchant_id":"10010","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\
                  

                    
                  
                    
$ch = curl_init();
                    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                    curl_setopt($ch, CURLOPT_POST, 1);
                    curl_setopt($ch, CURLOPT_POSTFIELDS,
                                "merchant_id=10010&hash=fc85b97551f5a2b8bf28d916f2f8055d");

                    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                    $server_output = curl_exec($ch);

                    curl_close ($ch)

Response (200):

                    
"https://www.qlicknpay.com/merchant/mandate/terminate?U0FNUExFMTIzNDU="

                  
                    
"https://www.qlicknpay.com/merchant/mandate/terminate?U0FNUExFMTIzNDU="
Field Name Description
merchant_id Your merchant ID
  • Accept only number
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide (Modify Active Subscriber)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Subscriber Reference No 101

Sample code to hash above values:
md5("$api|$merchant_id|$id");

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:

YOURAPIKEY00192|10010|101" will generate something like 9fdf8fa3241f509f05250dc3a9879a92

Callback Respond (New Subscriber / Direct Debit Approval)

How to receive the callback response?

The response to your payment request will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after you received new subscriber.

You will received two callbacks from the same reference number.
1 - First callback is a direct debit status by your subscriber
2 - Second callback is a direct debit status approval by bank

Once your direct debit is approved from both subscriber and by bank, you are allowed to proceed with the direct debit payment

For your record, the different from the first callback and second callback is a transaction message status parameter. If direct debit is approved from your subscriber, the value of the parameter is "Transaction Approved". If the approval is from bank, the value is "Direct Debit Approved".

Sample response:

      
{
    "others_trx_id": "2207201541280903",
    "reference_no": "12345672",
    "invoice_no": "C10001R12345672U6",
    "txn_status": "00",
    "msg": "Transaction Approved",
    "pay_method": "others",
    "trx_txt": "emandate",
    "subscription_id": "FIXED001",
    "subscription_status": "new",
    "hash": "4956f3ec1c1d0dc7ba527e04354855e7"
}

    
      
{
    "others_trx_id": "2207201541280903",
    "reference_no": "12345672",
    "invoice_no": "C10001R12345672U6",
    "txn_status": "00",
    "msg": "Transaction Approved",
    "pay_method": "others",
    "trx_txt": "emandate",
    "subscription_id": "FIXED001",
    "subscription_status": "new",
    "hash": "4956f3ec1c1d0dc7ba527e04354855e7"
}
Parameter Description
others_trx_id Transaction ID return from the bank
TYPE: STRING
reference_no Subscriber Reference No.
TYPE: STRING
invoice_no Transaction Invoice ID.
TYPE: STRING
txn_status Transaction status code
TYPE: STRING
msg Transaction status message
TYPE: STRING
pay_method Transaction payment method. For emandate verification, it will set as 'others'.
TYPE: STRING
trx_txt Payment method description. For emandate verification, it will set as 'emandate'.
TYPE: STRING
subscription_id Subscription ID
TYPE: STRING
subscription_status Subscription request status. The value for the parameter can be 'new', 'maintenance' or 'terminated'
TYPE: STRING
hash Secure hash string to validate the response sent to your side.
TYPE: STRING

Sample verification hash for callback respond (New Subscriber)

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

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

An 'OK' message need to display from your callback endpoint as a valid respond received. Betterpay will send the callback data at most 3 times every 10 minutes if Betterpay doesn't received an 'OK' message.
Example in PHP programming language: echo "OK";

Introduction

Create and manage one off payments, subscriptions and instalments with simple API requests. To start your recurring collection, use the following APIs to submit your request to the bank. Below is a sample flow of successful subscriptions for your reference.

Add Collection API

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d batch_id: B99123\
          -d collection_date: 30-01-2023\
          -d fpx_reference_no: C34R123456T160311,C34R123456T127394,C34R123456T129103,C34R123456T110048\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&batch_id=B99123&collection_date=30-01-2023&
                        fpx_reference_no=C34R123456T160311,C34R123456T127394,C34R123456T129103,
                        C34R123456T110048&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response (If Optional variable 'response_format' equal to '1' or empty):

    
 {
    "response": "00",
    "status": "00",
    "batch_id": "B99123",
    "collection_date": "30-01-2023",
    "fpx_reference_no": "C34R123456T160311,C34R123456T127394,C34R123456T129103,C34R123456T110048",
    "created": "2023-30-11 15:40:00",
} 

  
    
 {
    "response": "00",
    "status": "00",
    "batch_id": "B99123",
    "collection_date": "30-01-2023",
    "fpx_reference_no": "C34R123456T160311,C34R123456T127394,C34R123456T129103,C34R123456T110048",
    "created": "2023-30-11 15:40:00",
}

Example response (If Optional variable 'response_format' equal to '2'):

    
 {
    "response": "00",
    "status": "00",
    "batch_id": "B99123",
    "collection_date": "30-01-2023",
    "data": {
        "0": {
            "fpx_reference_no": "C34R123456T160311",
            "amount": "50.00"
            },
        "1": {
            "fpx_reference_no": "C34R123456T127394",
            "amount": "25.00"
            },
        "2": {
            "fpx_reference_no": "C34R123456T1291031",
            "amount": "150.50"
            },
        "3": {
            "fpx_reference_no": "C34R123456T110048",
            "amount": "80.90"
            },
          }
    "created": "2023-30-11 15:40:00",
} 

  
    
 {
    "response": "00",
    "status": "00",
    "batch_id": "B99123",
    "collection_date": "30-01-2023",
    "data": {
        "0": {
            "fpx_reference_no": "C34R123456T160311",
            "amount": "50.00"
            },
        "1": {
            "fpx_reference_no": "C34R123456T127394",
            "amount": "25.00"
            },
        "2": {
            "fpx_reference_no": "C34R123456T1291031",
            "amount": "150.50"
            },
        "3": {
            "fpx_reference_no": "C34R123456T110048",
            "amount": "80.90"
            },
          }
    "created": "2023-30-11 15:40:00",
}

Response (400):

    
{
  "response":"99",
  "msg":"Batch ID is already exist",
}

  
    
{
  "response":"99",
  "msg":"Batch ID is already exist",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
batch_id Your unique batch ID
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:B99123
collection_date Date for subscribers bank account to be debited.

Today's day Allowed Collection Date
Monday to Friday
(Before 03.31PM)		 Any date allowed
(Not less than current date)
Monday to Thursday
(After 03.30PM)		 Date must be on next day or more
Friday
(After 03.30PM)		 Date must be on next Monday or more
Saturday and Sunday Date must be on next Monday or more
Public Holiday
(Federal Territory, Malaysia)		 Collection must be not on Public Holiday

  • Accept only numbers and '-' sign
  • Date format must be dd-mm-yyy
TYPE: STRING
EXAMPLE: 30-01-2023
fpx_reference_no Once you receive new subscribers from your created subscription package, we will send the FPX Reference No to your callback URL. You can also retrieve this FPX Reference No from your Qlicknpay Merchant Dashboard. Login > Recurring > Subscribers List

You can debit multiple subscriber bank accounts using one API request.

If your Optional Field Name 'max_amount' is empty or set value with '1':

List all your FPX Reference No and seperate it by using comma (,). The total amount will be the maximum amount of the mandate. Refer sample below.

TYPE: STRING
EXAMPLE:C34R123456T160311,C34R123456T127394,C34R123456T129103,
C34R123456T110048
If your Optional Field Name 'max_amount' value is '0':

List all your FPX Reference No and total amount for each subscriber. Seperate with comma (,) between FPX Reference No and total amount. Add semicolon (;) for seperation between your subscriber data. The total amount must be more than RM1.50 and less than RM100,000.00 (Depend on the submitted mandate). Refer sample below.

TYPE: STRING
EXAMPLE:C34R123456T160311,150.00;C34R123456T127394,90.00;
C34R123456T129103,110.50;
  • Maximum is 200 subscribers per batch.
  • Accept alphabets and numbers.
  • Length: Max 30 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
max_amount Submit with the different total amount for each subscriber. If this value is empty, every subscriber will charge with a maximum amount of the submitted mandate.

Set value with '1' or empty (Default value):
Maximum amount of the mandate will be charge.

Set value with '0': Amount can be change but must be less than maximum amount of mandate
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 1
response_format Format of the response data. Subscribers data can be display either in an array format or in single string format. Refer our sample response. In default, the response will be display in single string format.

Set value with '1' or empty (Default value):
Single string format. Example: "fpx_reference_no": "C34R123456T160311,50.00;C34R123456T127394,25.10;
C34R123456T1291031,150.50;C34R123456T110048,80.90;"

Set value with '2': In array format. Example:
"data": {
"0": {
    "fpx_reference_no": "C34R123456T160311",
    "amount": "50.00"
    },
"1": {
    "fpx_reference_no": "C34R123456T127394",
    "amount": "25.00"
    },
"2": {
    "fpx_reference_no": "C34R123456T1291031",
    "amount": "150.50"
     },
"3": {
    "fpx_reference_no": "C34R123456T110048",
    "amount": "80.90"
    },
  }
  • Accept only numbers
TYPE: STRING
EXAMPLE: 1

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192
Batch ID B99123
Collection Date 30-01-2023
FPX Reference Number C34R123456T160311,C34R123456T127394,C34R123456T129103C34R123456T110048

Format: API Key + | + Merchant ID + | + Batch ID + | + Collection Date + | + FPX Reference Number

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id."|".$collection_date."|".$fpx_reference_no);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115|B99123|30-01-2023|C34R123456T160311,C34R123456T127394,C34R123456T129103C34R123456T110048 will generate something like bad19c1c2cea083394d0fea62a8b8d8b

Cancel Collection by Batch

Use this API to cancel your submitted batch request. You may only cancel if the bank has not processed your batch request.

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d batch_id: B99123\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&batch_id=B99123&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response:

    
 {
    "response": "00",
    "merchant_id": "10115",
    "batch_id": "B99123",
    "status": "00",
    "msg": "Successfully cancelled",
} 

  
    
 {
    "response": "00",
    "merchant_id": "10115",
    "batch_id": "B99123",
    "status": "00",
    "msg": "Successfully cancelled",
}

Response (400):

    
{
  "response":"99",
  "msg":"Unable to update the data. Please try again",
}

  
    
{
  "response":"99",
  "msg":"Unable to update the data. Please try again",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
batch_id Your unique batch ID
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:B99123
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192
Batch ID B99123

Format: API Key + | + Merchant ID + | + Batch ID

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115|B99123 will generate something like 474896ca7b9887e3237467b01d507a7d

Cancel Single Collection

Cancelling only single submission

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d batch_id: B99123\
          -d fpx_reference_no: C34R123456T160311\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&batch_id=B99123&fpx_reference_no=C34R123456T160311&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response:

    
 {
    "response": "00",
    "merchant_id": "10115",
    "batch_id": "B99123",
    "fpx_reference_no": "C34R123456T160311",
    "status": "00",
    "msg": "Successfully cancelled",
} 

  
    
 {
    "response": "00",
    "merchant_id": "10115",
    "batch_id": "B99123",
    "fpx_reference_no": "C34R123456T160311",
    "status": "00",
    "msg": "Successfully cancelled",
}

Response (400):

    
{
  "response":"99",
  "msg":"Unable to update the data. Please try again",
}

  
    
{
  "response":"99",
  "msg":"Unable to update the data. Please try again",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
batch_id Your unique batch ID
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:B99123
fpx_reference_no Your submitted FPX Rereference No
  • Accept alphabets, numbers and some special characters.
  • Length: Max 30 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:C34R123456T160311
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192
Batch ID B99123
FPX Reference No C34R123456T160311

Format: API Key + | + Merchant ID + | + Batch ID + | + FPX Reference No

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id."|".$fpx_reference_no);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115|B99123|C34R123456T160311 will generate something like a03d04627af327d90974223d60dbee77

Get All Submitted Batch ID

Get all Batch ID data that has been submitted

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response:

    

      {
          "total_page_available": 1,
      },
      {
          "batch_id": "B99123",
          "date_created": "2022-01-27 12:42:51",
      },
      {
          "batch_id": "B99124",
          "date_created": "2022-01-28 15:12:00",
      },
      {
          "batch_id": "B99178",
          "date_created": "2022-01-29 13:11:23",
      }
    

  
    

      {
          "total_page_available": 1,
      },
      {
          "batch_id": "B99123",
          "date_created": "2022-01-27 12:42:51",
      },
      {
          "batch_id": "B99124",
          "date_created": "2022-01-28 15:12:00",
      },
      {
          "batch_id": "B99178",
          "date_created": "2022-01-29 13:11:23",
      }

Response (400):

    
{
  "response":"99",
  "msg":"Verification fail",
}

  
    
{
  "response":"99",
  "msg":"Verification fail",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192

Format: API Key + | + Merchant ID

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115 will generate something like fa7c2d85468af7b3a0c2280df3147a19

Get Collection By Batch ID

Get collection data that has been submitted

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d batch_id: B99123\
          -d status: 2\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&batch_id=B99123&status=2&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response:

    

      {
          "batch_id": "B99123",
          "fpx_reference_no": "C34R123456T160311",
          "collection_date": "30-01-2023",
          "date_created": "2022-01-27 12:42:51",
          "status": "CANCELLED BY CUSTOMER",
          "callback_url_be": "https://webina.me/callback",
          "permission_to_cancel": "NOT ALLOWED",
      },
      {
        "batch_id": "B99123",
        "fpx_reference_no": "C34R123456T127394",
        "collection_date": "30-01-2023",
        "date_created": "2022-01-27 12:42:51",
        "status": "PENDING",
        "callback_url_be": "https://webina.me/callback",
        "permission_to_cancel": "ALLOWED",
      },
      {
        "batch_id": "B99123",
        "fpx_reference_no": "C34R123456T129103",
        "collection_date": "30-01-2023",
        "date_created": "2022-01-27 12:42:51",
        "status": "PENDING",
        "callback_url_be": "https://webina.me/callback",
        "permission_to_cancel": "NOT ALLOWED",
      }
    

  
    

      {
          "batch_id": "B99123",
          "fpx_reference_no": "C34R123456T160311",
          "collection_date": "30-01-2023",
          "date_created": "2022-01-27 12:42:51",
          "status": "CANCELLED BY CUSTOMER",
          "callback_url_be": "https://webina.me/callback",
          "permission_to_cancel": "NOT ALLOWED",
      },
      {
        "batch_id": "B99123",
        "fpx_reference_no": "C34R123456T127394",
        "collection_date": "30-01-2023",
        "date_created": "2022-01-27 12:42:51",
        "status": "PENDING",
        "callback_url_be": "https://webina.me/callback",
        "permission_to_cancel": "ALLOWED",
      },
      {
        "batch_id": "B99123",
        "fpx_reference_no": "C34R123456T129103",
        "collection_date": "30-01-2023",
        "date_created": "2022-01-27 12:42:51",
        "status": "PENDING",
        "callback_url_be": "https://webina.me/callback",
        "permission_to_cancel": "NOT ALLOWED",
      }

Response (400):

    
{
  "response":"99",
  "msg":"Authentication error. Check your hash and try again.",
}

  
    
{
  "response":"99",
  "msg":"Authentication error. Check your hash and try again.",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
batch_id Your unique batch ID
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:B99123
status Filter by status of the subscriber.
  • 0 - All failed subscriber
  • 1 - All successful subscriber
  • 2 - All subscriber
TYPE: STRING
EXAMPLE:2
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

List of Status

This section will explain how to secure request. This will be used to generate the hash field in your request.

Status
PENDING
SUCCESSFUL
INSUFFICIENT FUNDS
ACCOUNT CLOSED
INVALID BUYER ACCOUNT
WITHDRAWAL FREQ EXCEEDED
AUTHORIZATION REVOKED
WITHDRAWAL LIMIT EXCEEDED
NOT AUTHORIZED
INVALID BUYER BANK
TRANSACTION NOT PERMITTED
INVALID AMOUNT
INVALID SELLER ID
INVALID BUYER NAME/ID
INVALID RESPONSE
INVALID SERIAL NUMBER
NO REASON TO DECLINE
PENDING DEBIT RETRY
PENDING BUYER BK RESPONSE
BUYER BANK NOT RESPONDED
CANCELLED BY BANK
CANCELLED BY CUSTOMER

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192
Batch ID B99123
Status 2

Format: API Key + | + Merchant ID + | + Batch ID + | + Status

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id."|".$status);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115|B99123|2 will generate something like afad1630afa9e351c9cc404349b05bd9

Get Collection Details

Get collection data (in details) that has been submitted

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d batch_id: B99123\
          -d fpx_reference_no: C34R123456T160311\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
        

    
  
    
        
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                        "merchant_id=10115&batch_id=B99123&fpx_reference_no=C34R123456T160311&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $server_output = curl_exec($ch);
        curl_close ($ch)

Example response:

    

      {
          "response": "00",
          "batch_id": "B99123",
          "mandate_id": "MANDATE01",
          "applicant_id": "950717027961",
          "applicant_name": "John",
          "applicant_acc_no": "8603706111",
          "applicant_bank_id": "MB2U0227",
          "fpx_reference_no": "C34R123456T160311",
          "amount": "51.00",
          "collection_date": "30-01-2023",
          "date_created": "2022-01-27 12:42:51",
          "status": "CANCELLED BY CUSTOMER",
          "permission_to_cancel": "NOT ALLOWED"
      }
    

  
    

      {
          "response": "00",
          "batch_id": "B99123",
          "mandate_id": "MANDATE01",
          "applicant_id": "950717027961",
          "applicant_name": "John",
          "applicant_acc_no": "8603706111",
          "applicant_bank_id": "MB2U0227",
          "fpx_reference_no": "C34R123456T160311",
          "amount": "51.00",
          "collection_date": "30-01-2023",
          "date_created": "2022-01-27 12:42:51",
          "status": "CANCELLED BY CUSTOMER",
          "permission_to_cancel": "NOT ALLOWED"
      }

Response (400):

    
{
  "response":"99",
  "msg":"Authentication error. Check your hash and try again.",
}

  
    
{
  "response":"99",
  "msg":"Authentication error. Check your hash and try again.",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10115
batch_id Your unique batch ID
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:B99123
fpx_reference_no Your submitted FPX Rereference No
  • Accept alphabets, numbers and some special characters.
  • Length: Max 30 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:C34R123456T160311
hash The secure hash string to validate the request. Refer our Hashing Guides Tab below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant ID 10115
API YOURAPIKEY00192
Batch ID B99123
FPX Reference No C34R123456T160311

Format: API Key + | + Merchant ID + | + Batch ID + | + FPX Reference No

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id."|".$fpx_reference_no);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10115|B99123|C34R123456T160311 will generate something like a03d04627af327d90974223d60dbee77

Callback Respond (Add Collection)

How to receive the callback response?

The response to your payment request will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your subscribers have been approved from the bank for subscription.

Sample response:

      
{
    "batch_id": "BATCH0000001",
    "data": {
        "1": {
            "fpx_reference_no": "C5R123122131311B1"
        }
    },
    "hash": "9a271b5fcd99245a3447755d9cc029c3"
}

    
      
{
    "batch_id": "BATCH0000001",
    "data": {
        "1": {
            "fpx_reference_no": "C5R123122131311B1"
        }
    },
    "hash": "9a271b5fcd99245a3447755d9cc029c3"
}
Parameter Description
batch_id Unique Batch ID.
TYPE: STRING
data: status Status code of the transaction. Below is the details of the status code:

00 - Successful Payment
99 - Unsuccessful Payment

TYPE: STRING
data: msg Message from the bank.
TYPE: STRING
data: fpx_reference_no Subscriber FPX Reference No.
TYPE: STRING
hash Secure hash string to validate the response sent to your side.
TYPE: STRING

Sample verification hash for callback respond

For hash verification, you need to make a string from the callback data. Combine all data from 'data' parameters into one string. Below is the format

Data String: {FPX Reference No #1},{Status Message #1},{FPX Reference No #2},{Status Message #2}...
Example: C5R213131231231C1,SUCCESSFUL,C5R123122131311B1,CANCELLED BY CUSTOMER

Full Hash String: {API Key}|{Merchant ID}|{Batch ID}|{Data String from the above}
Example: APIKEY123456|10122|BATCH0000001|C5R213131231231C1,SUCCESSFUL,C5R123122131311B1,CANCELLED BY CUSTOMER

Use MD5 encryption method to encrypt the hash string. Below is an example for hash verification by using PHP code:
md5($api."|".$merchant_id."|".$batch_id."|".$fpx_reference_no);

For example, if the details received are as above, the hash string to be generated is constructed as follows:
APIKEY123456|10122|BATCH0000001|C5R213131231231C1,SUCCESSFUL,C5R123122131311B1,CANCELLED BY CUSTOMER will generate something like 9a271b5fcd99245a3447755d9cc029c3

An 'OK' message need to display from your callback endpoint as a valid respond received. Betterpay will send the callback data at most 3 times every 10 minutes if Betterpay doesn't received an 'OK' message.
Example in PHP programming language: echo "OK";

Refund API

This API is available for merchants using their OWN FPX SELLER ID.
This feature allow you to refund a payment made by your buyer. Funds will be refunded to the original payer's bank account. You do not need to know the buyer's bank account number to make the refund.

  1. Follow the instruction for requirement on Refund API request.
  2. Make sure you have a valid QlicknPay Reference No or your Invoice No from the transaction that has been made by payer.
  3. You can make a bulk refund in one API request (max 10 transactions per request). All success transaction is only valid for refund as long the transaction not more than 5 days after the transaction is made
  4. After the request, you will receive indirect message data including the status for the request. Successful request will return 1S as a status. Please refer here for description of the status code.
  5. After the request has been submmited, it will take a few minutes for your bank to verify the request. You will receive an email (optional) after the verification is successful and a callback data with 1S as a status of the request
  6. For Production: Please proceed to your bank portal to approve or decline the refund request.
  7. For Sandbox: Please proceed to your QlicknPay Sandbox Merchant Portal and proceed to Refund List (Bank Simulation) page under the Transaction Report section to approve or decline the request.
  8. Once the request has been approved or declined, an email will be sent to the merchant (optional) including the callback data.

Below is a transaction flow for API Refund Request.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information from the API Management page.

Kindly ensure the payment request you send to either of the mentioned endpoints comply to the following format using POST method. You can set fields with OPTIONAL tag to NULL or exclude it entirely if it is not required.

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d merchant_bank_id: BIMB0340\
          -d merchant_acc_number: 123330010011999\
          -d merchant_maker_name: SHAHRUL\
          -d organization_id: 950517109988\
          -d refund_list: 10115-064714-201920-AVs,101.50;10115-05164-201921-AKk,15.50;\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
          

    
  
    
                          
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                    "merchant_id=10115&merchant_bank_id=BIMB0340&merchant_acc_number=123330010011999&
                      merchant_maker_name=SHAHRUL&organization_id=950517109988&refund_list=10115-064714-201920-AVs,101.50;10115-05164-201921-AKk,15.50&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $server_output = curl_exec($ch);

        curl_close ($ch)

Example response (FPX):

    
 {
    "response": "00",
    "msg": "Request is successful submitted. We will inform you once the refund is ready",
    "ref_no": "10115-20201512-REFUND-AsQ",
    "merchant_id": "10115",
    "merchant_bank_id": "BIMB0340",
    "merchant_maker_name": "QlicknPay",
    "merchant_acc_number": "123330010011999",
    "refund_list": "10115-064714-201920-AVs,101.50;10115-05164-201921-AKk,15.50;",
} 

  
    
 {
    "response": "00",
    "msg": "Request is successful submitted. We will inform you once the refund is ready",
    "ref_no": "10115-20201512-REFUND-AsQ",
    "merchant_id": "10115",
    "merchant_bank_id": "BIMB0340",
    "merchant_maker_name": "QlicknPay",
    "merchant_acc_number": "123330010011999",
    "refund_list": "10115-064714-201920-AVs,101.50;10115-05164-201921-AKk,15.50;",
}

Response (400):

    
{
  "response":"99",
  "msg":"This account is not valid to proceed with refund API",
}

  
    
{
  "response":"99",
  "msg":"This account is not valid to proceed with refund API",
}

Response (401):

  
{
  "response":"99",
  "msg":"Invalid data",
  }

  
  
{
  "response":"99",
  "msg":"Invalid data",
  }

Sample Callback Data: 

  
{
  "type":"refund_api",
  "ref_no":"10115-20201512-REFUND-AsQ",
  "refund_list":"10115-064714-201920-AVs,101.50,00;10115-05164-201921-AKk,15.50,00;",
  "hash":"576c13781e8807c7d689dd1473da9f1d",
  }

  
    
{
    "type":"refund_api",
    "ref_no":"10115-20201512-REFUND-AsQ",
    "refund_list":"10115-064714-201920-AVs,101.50,00;10115-05164-201921-AKk,15.50,00;",
    "hash":"576c13781e8807c7d689dd1473da9f1d",
    }
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10001
merchant_bank_id Your bank ID. Ex: Your registered bank is Bank Islam, the value should be BIMB0340. TYPE: STRING
EXAMPLE:BIMB0340
merchant_acc_number Your bank account number.
  • Accept alphabets and numbers.
TYPE: STRING
EXAMPLE:1213330100119988
merchant_maker_name Your Maker account name. If you doesn't have any maker account, please create a new maker account by login to your bank portal.
  • Accept alphabets and numbers.
TYPE: STRING
EXAMPLE:SHAHRUL
organization_id Your Organization ID. You can retrieve your Organization ID by login to your bank portal.
  • Accept numbers. No (-) characters
TYPE: STRING
EXAMPLE:BVCOMPANY123
refund_list List of transactions that need to be refunded. Must be in a correct format.
  • Format: 'Your QlicknPay Reference No / Seller Order Number / Transaction Invoice No', 'Total Amount need to refund';
  • You can do bulk refund in one request. Please refer example.
  • Maximum 10 refunds in one request.
  • Dont forget to add semicolon (;) for seperation between your refund data.
TYPE: STRING
EXAMPLE:10115-064714-201920-AVs,101.50;10115-05164-201921-AKk,15.50;
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Parameter Description
enable_callback Callback requirement
  • Set the value to '1' if you require a callback data or set it to '0' to disabled it
TYPE: INTEGER
EXAMPLE:1
enable_email Email requirement
  • Set the value to '1' if you require an email everytime the status of refund is updated or set it to '0' to disable it
TYPE: INTEGER
EXAMPLE:1
refund_callback_url Callback URL for the refund API. If this value is NULL, system will refer your Callback URL from the dashboard.
  • To use this variable, please enable your callback by set variable 'enable_callback' into '1'
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:https://webina.me/callback-refund

Refund List Format (Request)

Request: Your Invoice No or QlicknPay Reference No or Seller Order No + comma + total amount to refund + semicolon

Example: INV002810,10.00;

Refund List Format (Callback)

Request: QlicknPay Reference No + comma + total amount to refund + comma + refund status + semicolon

Example: 10115-064714-201920-AVs,101.50,1S;

Hashing Guides (Request)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Please use MD5 message-digest algorithm to hash the data

Field Name Example Value
merchant id 10034
API YOURAPIKEY00192
Merchant Bank ID BIMB0340
Merchant Bank Account Number 121122310011999
Merchant Maker Name SHAHRUL
Organization ID BVCOMPANY123
Refund List 064714,1.50;
Callback Status 1
Email Status 1
Refund Callback URL https://www.webina.me/callback-refund

Sample code to hash above values:
md5($merchant_id."|".$api."|".$merchant_bank_id."|".$merchant_acc_number."|".$merchant_maker_name."|".$organization_id."|".$refund_list."|".$enable_callback."|".$enable_email."|".$refund_callback_url);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
10034|YOURAPIKEY00192|BIMB0340|121122310011999|SHAHRUL|BVCOMPANY123|064714,1.50;|1|1|https://www.webina.me/callback-refund will generate something like e75eb4c46839156d7824539b548039b8

Hashing Guides (Callback)

This section will explain how to secure received your callback data. This will be used to generate the hash field.

Please use MD5 message-digest algorithm to hash the data

Field Name Variable Name Example Value
API - YOURAPIKEY00192
Type type refund_api
Reference No ref_no 10034-121SDC-REFUND-Axa
Refund List refund_list 10034-064714-201920-AVs,12.00,1S;10115-05164-201921-AKk,16.00,1S;

Sample code to hash above values:
md5($API.'refund_api'.$fpx_sellerOrderNo.$return_order_list

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|refund_api|10034-121SDC-REFUND-Axa|10034-064714-201920-AVs,12.00,1S;10115-05164-201921-AKk,16.00,1S; will generate something like 5772f93dad547629ebfad11df79b816c

Get Transactions

You can retrieve all transactions records by calling this API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d date_from: 2020-01-02\
          -d date_to: 2020-04-19\
          -d status: 1\
          -d page: 2\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&date_from=2020-01-02&date_to=2020-04-19&status=1&page=2&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (200):

    
[
    {
        "total_page_available": 12,
    },
    {
        "invoice": "INV0001",
        "prod_id": "",
        "total_amount": "1023.20",
        "buyer_name": "John",
        "buyer_email": "john@email.com",
        "phone": "01712345678",
        "address": "Jlan PJU 6/19 Kota Damansara",
        "city": "Petaling Jaya",
        "state": "Selangor",
        "postcode": "47810",
        "comment": "Comment from customer",
        "status": "Success",
        "pay_method": "fpx",
        "qlicknpay_ref_no": "10001-INV0001-035336-K4b",
        "time": "2021-01-18 23:53:36",
    },
    {
      "invoice": "INV0002",
      "prod_id": "",
      "total_amount": "980.10",
      "buyer_name": "Max",
      "buyer_email": "max@email.com",
      "phone": "01712345678",
      "address": "Jlan PJU 6/19 Kota Damansara",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "postcode": "47810",
      "comment": "Comment from customer",
      "status": "Cancel Transaction",
      "pay_method": "Credit/Debit Card",
      "qlicknpay_ref_no": "10001-INV0002-073511-Aaw",
      "time": "2021-01-17 17:22:11",
    },
    {
      "invoice": "INV0003",
      "prod_id": "",
      "total_amount": "1520.15",
      "buyer_name": "Mark",
      "buyer_email": "mark@email.com",
      "phone": "01712345678",
      "address": "Jlan PJU 6/19 Kota Damansara",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "postcode": "47810",
      "comment": "Comment from customer",
      "status": "Buyer Session Timeout At Account Selection Page",
      "pay_method": "fpx",
      "qlicknpay_ref_no": "10001-INV0003-075678-dwk",
      "time": "2021-01-15 18:27:17",
    }
]


  
    
[
    {
        "total_page_available": 12,
    },
    {
        "invoice": "INV0001",
        "prod_id": "",
        "total_amount": "1023.20",
        "buyer_name": "John",
        "buyer_email": "john@email.com",
        "phone": "01712345678",
        "address": "Jlan PJU 6/19 Kota Damansara",
        "city": "Petaling Jaya",
        "state": "Selangor",
        "postcode": "47810",
        "comment": "Comment from customer",
        "status": "Success",
        "pay_method": "fpx",
        "qlicknpay_ref_no": "10001-INV0001-035336-K4b",
        "time": "2021-01-18 23:53:36",
    },
    {
      "invoice": "INV0002",
      "prod_id": "",
      "total_amount": "980.10",
      "buyer_name": "Max",
      "buyer_email": "max@email.com",
      "phone": "01712345678",
      "address": "Jlan PJU 6/19 Kota Damansara",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "postcode": "47810",
      "comment": "Comment from customer",
      "status": "Cancel Transaction",
      "pay_method": "Credit/Debit Card",
      "qlicknpay_ref_no": "10001-INV0002-073511-Aaw",
      "time": "2021-01-17 17:22:11",
    },
    {
      "invoice": "INV0003",
      "prod_id": "",
      "total_amount": "1520.15",
      "buyer_name": "Mark",
      "buyer_email": "mark@email.com",
      "phone": "01712345678",
      "address": "Jlan PJU 6/19 Kota Damansara",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "postcode": "47810",
      "comment": "Comment from customer",
      "status": "Buyer Session Timeout At Account Selection Page",
      "pay_method": "fpx",
      "qlicknpay_ref_no": "10001-INV0003-075678-dwk",
      "time": "2021-01-15 18:27:17",
    }
]

Example response (400):

    
{
  "response": "97",
  "msg": "Invalid date_from format."
}


  
    
{
  "response": "97",
  "msg": "Invalid date_from format."
}

Example response (401):

    
{
  "response": "99",
  "msg": "Verification fail"
}


  
    
{
  "response": "99",
  "msg": "Verification fail"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the transactions.
  • Accept only numbers
  • 0 - All failed transactions, 1 - All success transactions, 2 - Both failed and success transactions
TYPE: INTEGER
EXAMPLE: 1
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034 will generate something like 609d3d1b0c3b93c22a17ed74092a6c31

Get Transactions

This feature enables the merchant to retrieve their transaction details. Some transactions you have to initiate might have the same invoice number. Calling this API by using your invoice number will return all available transactions.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d invoice: INV0123\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&invoice=INV0123&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (200):

    
[
    {
        "response": 00,
        "merchant_id": 10001,
        "invoice": INV0123,
        "buyer": 
          {
            "qlicknpay_ref_no": "10001-INV0123-035336-K4b",
            "total_amount": "1023.20",
            "buyer_name": "John",
            "buyer_email": "john@email.com",
            "phone": "01712345678",
            "address": "Jlan PJU 6/19 Kota Damansara",
            "city": "Petaling Jaya",
            "state": "Selangor",
            "postcode": "47810",
            "comment": "Comment from customer",
            "status": "Success",
            "pay_method": "Fpx",
            "time": "2021-01-18 23:53:36",
          },
          {
            "qlicknpay_ref_no": "10001-INV0123-52166-Ab2",
            "total_amount": "259.20",
            "buyer_name": "Carl",
            "buyer_email": "carl@email.com",
            "phone": "017123423323",
            "address": "Jlan PJU 6/66 Kota Damansara",
            "city": "Ampang",
            "state": "Kuala Lumpur",
            "postcode": "68000",
            "comment": "Comment from customer",
            "status": "Transaction Failed",
            "pay_method": "BNPL",
            "time": "2021-01-15 11:22:16",
          }
    }
]


  
    
[
    {
        "response": 00,
        "merchant_id": 10001,
        "invoice": INV0123,
        "buyer": 
          {
            "qlicknpay_ref_no": "10001-INV0123-035336-K4b",
            "total_amount": "1023.20",
            "buyer_name": "John",
            "buyer_email": "john@email.com",
            "phone": "01712345678",
            "address": "Jlan PJU 6/19 Kota Damansara",
            "city": "Petaling Jaya",
            "state": "Selangor",
            "postcode": "47810",
            "comment": "Comment from customer",
            "status": "Success",
            "pay_method": "Fpx",
            "time": "2021-01-18 23:53:36",
          },
          {
            "qlicknpay_ref_no": "10001-INV0123-52166-Ab2",
            "total_amount": "259.20",
            "buyer_name": "Carl",
            "buyer_email": "carl@email.com",
            "phone": "017123423323",
            "address": "Jlan PJU 6/66 Kota Damansara",
            "city": "Ampang",
            "state": "Kuala Lumpur",
            "postcode": "68000",
            "comment": "Comment from customer",
            "status": "Transaction Failed",
            "pay_method": "BNPL",
            "time": "2021-01-15 11:22:16",
          }
    }
]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV0001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 10001
API YOURAPIKEY00192
Invoice id INV0001

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10001|INV0001 will generate something like f77099c4467380801bc45481419ecab0

Get Refund Status

In the unlikely event that the payment network does not automatically notify the merchant regarding customer's payment status, use this API to manually query the refund requested. This feature enables the merchant to retrieve their refund status by sending a request direct to the bank or payment provider network.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page and your invoice no at Transaction Reports

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d ref_no: 10011-FS789-REFUND-Mt\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&invoice=10011-FS789-REFUND-Mt&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (FPX):

    
 {
    "response": "00",
    "status": "00",
    "msg": "Transaction Approved",
    "ref_no": "10011-FS789S-REFUND-Mt",
    "refund_list": "INV064714,1.5,00",
    "ref_transaction_id": "2106260256290607",
} 

  
    
 {
    "response": "00",
    "status": "00",
    "msg": "Transaction Approved",
    "ref_no": "10011-FS789S-REFUND-Mt",
    "refund_list": "INV064714,1.5,00",
    "ref_transaction_id": "2106260256290607",
}

Response (400):

    
{
  "response":"99",
  "msg":"This account is not valid to proceed with refund API",
}

  
    
{
  "response":"99",
  "msg":"This account is not valid to proceed with refund API",
}

Response (401):

    
{
  "response":"99",
  "msg":"Invalid data",
}

  
    
{
  "response":"99",
  "msg":"Invalid data",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
ref_no Your invoice number
  • Accept only numbers and alphabets
  • Value is pre-defined by system or merchant
  • Please use the system generated reference number retrievable during the Refund API is called
TYPE: STRING
EXAMPLE: 10011-FS789-20181009-Mt
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 10011
API YOURAPIKEY00192
Reference No 10011-FS789-20181009-Mt

Sample code to hash above values:
md5($merchant_id."|".$api."|".$ref_no);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
10011|YOURAPIKEY00192|10011-FS789-20181009-Mt will generate something like 90ed0b91a5599fead9636c174c7b1081

Get Bank List

This API return list of bank codes for online banking. You must use the bank codes returned by this API in order to use the Direct Payment API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: 10115\
          -d type: b2c\
          -d hash: f67c2bcbfcfa30fccb36f72dca22a817\
          
 
  
    
                          
$ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                    "merchant_id=10115&type=b2c&hash=f67c2bcbfcfa30fccb36f72dca22a817");

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $server_output = curl_exec($ch);

        curl_close ($ch)

Example response:

    

[
  {
      "bank_id": "ABB0233",
      "bank_name": "Affin Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/affin.png",
      "status": "Online"
  },
  {
      "bank_id": "ABMB0212",
      "bank_name": "Alliance Bank (Personal)",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/alliance.png",
      "status": "Online"
  },
  {
      "bank_id": "AMBB0209",
      "bank_name": "AmBank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/ambank.png",
      "status": "Online"
  },
  {
      "bank_id": "BIMB0340",
      "bank_name": "Bank Islam",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankislam.png",
      "status": "Online"
  },
  {
      "bank_id": "BKRM0602",
      "bank_name": "Bank Rakyat",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankrakyat.png",
      "status": "Online"
  },
  {
      "bank_id": "BMMB0341",
      "bank_name": "Bank Muamalat",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankmuamalat.png",
      "status": "Online"
  },
  {
      "bank_id": "BSN0601",
      "bank_name": "BSN",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bsn.png",
      "status": "Online"
  },
  {
      "bank_id": "BCBB0235",
      "bank_name": "CIMB Clicks",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/cimb.png",
      "status": "Online"
  },
  {
      "bank_id": "HLB0224",
      "bank_name": "Hong Leong Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/hongleong.png",
      "status": "Online"
  },
  {
      "bank_id": "HSBC0223",
      "bank_name": "HSBC Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/hsbc.png",
      "status": "Online"
  },
  {
      "bank_id": "KFH0346",
      "bank_name": "KFH",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/kfh.png",
      "status": "Online"
  },
  {
      "bank_id": "MB2U0227",
      "bank_name": "Maybank2U",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/maybank.png",
      "status": "Online"
  },
  {
      "bank_id": "MBB0228",
      "bank_name": "Maybank2E",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/maybank.png",
      "status": "Online"
  },
  {
      "bank_id": "OCBC0229",
      "bank_name": "OCBC Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/ocbc.png",
      "status": "Online"
  },
  {
      "bank_id": "PBB0233",
      "bank_name": "Public Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/public.png",
      "status": "Online"
  },
  {
      "bank_id": "RHB0218",
      "bank_name": "RHB Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/rhb.png",
      "status": "Online"
  },
  {
      "bank_id": "SCB0216",
      "bank_name": "Standard Chartered",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/standard.png",
      "status": "Online"
  },
  {
      "bank_id": "UOB0226",
      "bank_name": "UOB Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/uob.png",
      "status": "Online"
  }
]                   

    

  
    

[
  {
      "bank_id": "ABB0233",
      "bank_name": "Affin Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/affin.png",
      "status": "Online"
  },
  {
      "bank_id": "ABMB0212",
      "bank_name": "Alliance Bank (Personal)",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/alliance.png",
      "status": "Online"
  },
  {
      "bank_id": "AMBB0209",
      "bank_name": "AmBank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/ambank.png",
      "status": "Online"
  },
  {
      "bank_id": "BIMB0340",
      "bank_name": "Bank Islam",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankislam.png",
      "status": "Online"
  },
  {
      "bank_id": "BKRM0602",
      "bank_name": "Bank Rakyat",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankrakyat.png",
      "status": "Online"
  },
  {
      "bank_id": "BMMB0341",
      "bank_name": "Bank Muamalat",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bankmuamalat.png",
      "status": "Online"
  },
  {
      "bank_id": "BSN0601",
      "bank_name": "BSN",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/bsn.png",
      "status": "Online"
  },
  {
      "bank_id": "BCBB0235",
      "bank_name": "CIMB Clicks",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/cimb.png",
      "status": "Online"
  },
  {
      "bank_id": "HLB0224",
      "bank_name": "Hong Leong Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/hongleong.png",
      "status": "Online"
  },
  {
      "bank_id": "HSBC0223",
      "bank_name": "HSBC Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/hsbc.png",
      "status": "Online"
  },
  {
      "bank_id": "KFH0346",
      "bank_name": "KFH",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/kfh.png",
      "status": "Online"
  },
  {
      "bank_id": "MB2U0227",
      "bank_name": "Maybank2U",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/maybank.png",
      "status": "Online"
  },
  {
      "bank_id": "MBB0228",
      "bank_name": "Maybank2E",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/maybank.png",
      "status": "Online"
  },
  {
      "bank_id": "OCBC0229",
      "bank_name": "OCBC Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/ocbc.png",
      "status": "Online"
  },
  {
      "bank_id": "PBB0233",
      "bank_name": "Public Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/public.png",
      "status": "Online"
  },
  {
      "bank_id": "RHB0218",
      "bank_name": "RHB Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/rhb.png",
      "status": "Online"
  },
  {
      "bank_id": "SCB0216",
      "bank_name": "Standard Chartered",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/standard.png",
      "status": "Online"
  },
  {
      "bank_id": "UOB0226",
      "bank_name": "UOB Bank",
      "image": "https://www.qlicknpay.com/merchant/img/bank-logo/uob.png",
      "status": "Online"
  }
]

Response (400):

    
{
    "response": "98",
    "merchant_id": "No Bank List Selected. Please specify either b2c or b2b."
}

  
    
{
    "response": "98",
    "merchant_id": "No Bank List Selected. Please specify either b2c or b2b."
}

Response (401):

    
{
    "response": "99",
    "merchant_id": "Verification fail"
}

  
    
{
    "response": "99",
    "merchant_id": "Invalid data entered. Please inform the merchant about this error."
}
Field Name Description
merchant_id Your merchant ID
TYPE: NUMBER
EXAMPLE: 10001
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
type Bank List Type. 'b2b' or 'b2c'
  • Accept ONLY alphabets
TYPE: STRING
EXAMPLE: b2c
hash The secure hash string to validate the request.
  • Accept ONLY alphabets
TYPE: STRING
EXAMPLE: f67c2bcbfcfa30fccb36f72dca22a817

Optional Arguments

Field Name Description
currency By default, the list of banks will display all banks that support MYR currency
TYPE: STRING
EXAMPLE: MYR
  • Only 'MYR' and 'SGD' are available
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
API YOURAPIKEY00192
merchant id 1000034
type b2c

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode(type));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034|b2c will generate something like c6e5b4278728becdcb75b2e2f1205a56

Get Payment Status

In the unlikely event that the payment network does not automatically notify the merchant regarding customer's payment status, use this API to manually query the transaction. This feature enables the merchant to retrieve their transaction status by sending a request direct to the bank or payment provider network. You may use this to send an enquiry request to FPX, Mastercard Payment Gateway, Boost E Wallet or PayPal.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key
  • Invoice No

You can retrieve these information at API Management page and your invoice no at Transaction Reports

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d invoice: 10011-FS789-20181009-Mt\
          -d method: 1\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&invoice=10011-FS789-20181009-Mt&method=1&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (FPX):

    
 {
    "response": "00",
    "invoice": "10020-256552-010742-mE",
    "fpx_fpxTxnTime": "13 February 2019 9:07PM",
    "fpx_fpxTxnId": "1902132108200234",
    "fpx_buyerName": "MOHD SHAHRUL IZWAN BIN PU",
    "fpx_txnCurrency": "MYR",
    "fpx_sellerOrderNo": "10020-256552-010742-mE",
    "invoice": "10020-256552-010742-mE",
    "fpx_txnAmount": "1.50",
    "amount": "1.50",
    "fpx_buyerBankBranch": "MAYBANK2U",
    "status_code": "00",
    "status": "Transaction Approved"
} 

  
    
 {
    "response": "00",
    "invoice": "10020-256552-010742-mE",
    "fpx_fpxTxnTime": "13 February 2019 9:07PM",
    "fpx_fpxTxnId": "1902132108200234",
    "fpx_buyerName": "MOHD SHAHRUL IZWAN BIN PU",
    "fpx_txnCurrency": "MYR",
    "fpx_sellerOrderNo": "10020-256552-010742-mE",
    "invoice": "10020-256552-010742-mE",
    "fpx_txnAmount": "1.50",
    "amount": "1.50",
    "fpx_buyerBankBranch": "MAYBANK2U",
    "status_code": "00",
    "status": "Transaction Approved"
}

Example response (Credit Card):

    
 {
  "response": "00",
  "invoice": "10020-256552-010742-mE",
  "time": "2018-12-24T03:11:33Z",
  "payer_first_name": "Shahrul",
  "payer_last_name": "Izwan",
  "mastercardID": "7X3UT2",
  "category_code": "10000026505",
  "transaction_result": "SUCCESS",
  "status": "SUCCESS",
  "status_code": "00",
  "amount": "102.00",
}

  
    
{
  "response": "00",
  "invoice": "10020-256552-010742-mE",
  "time": "2018-12-24T03:11:33Z",
  "payer_first_name": "Shahrul",
  "payer_last_name": "Izwan",
  "mastercardID": "7X3UT2",
  "category_code": "10000026505",
  "transaction_result": "SUCCESS",
  "status": "SUCCESS",
  "status_code": "00",
  "amount": "102.00",
}

Example response (PayPal):

    
 {
  "response":"00",
  "invoice": "10001-ABC291-030337-22",
  "time":"2018-12-24T03:11:33Z",
  "transactionID":"PAYID-LQQE4ZI5JP23373M1681232C",
  "state":"approved",
  "cartID":"6D8321255A183234",
  "status":"VERIFIED",
  "status_code":"00",
  "payer_email":"shah1234@gmail.com",
  "payer_first_name":"John",
  "payer_last_name":"Cena",
  "payer_id":"6DWRXRGBRSHAS",
  "payer_phone":"173649337",
  "amount":"102.00"
}

  
    
{
  "response":"00",
  "invoice": "10001-ABC291-030337-22",
  "time":"2018-12-24T03:11:33Z",
  "transactionID":"PAYID-LQQE4ZI5JP23373M1681232C",
  "state":"approved",
  "cartID":"6D8321255A183234",
  "status":"approved",
  "status_code":"00",
  "payer_email":"shah1234@gmail.com",
  "payer_first_name":"John",
  "payer_last_name":"Cena",
  "payer_id":"6DWRXRGBRSHAS",
  "payer_phone":"173649337",
  "amount":"102.00"
}

Example response (Boost eWallet):

    
{
  "response":"00",
  "invoice": "10001-ABC291-030337-22",
  "transactionType":"payment",
  "transactionTime":"2019-11-29T15:05:54",
  "boostRefNum":"191123343541211",
  "customerLast4DigitMSISDN":"9224",
  "status":"completed",
  "status_code":"00",
  "onlineRefNum":"10001-ABC291-030337-22",
  "amount":"30.50"
}

  
    
{
  "response":"00",
  "invoice": "10001-ABC291-030337-22",
  "transactionType":"payment",
  "transactionTime":"2019-11-29T15:05:54",
  "boostRefNum":"191123343541211",
  "customerLast4DigitMSISDN":"9224",
  "status":"completed",
  "status_code":"00",
  "onlineRefNum":"10001-ABC291-030337-22",
  "amount":"30.50"
}

Example response (2C2P eWallet):

    
{
  "response":"00",
  "invoice": "10001-ABC291-030337-22",
  "transactionType":"payment",
  "transactionTime":"2019-11-29T15:05:54",
  "providerRefNum":"191123343541211",
  "status_code":"00",
  "status":"Transaction Approved",
  "amount":"30.50"
}

  
    
{
      "response":"00",
      "invoice": "10001-ABC291-030337-22",
      "transactionType":"payment",
      "transactionTime":"2019-11-29T15:05:54",
      "providerRefNum":"191123343541211",
      "status_code":"00",
      "status":"Transaction Approved",
      "amount":"30.50"
}

Response (400):

    
{
  "response":"98",
  "msg":"Sorry, we can't requery a failed transaction",
}

  
    
{
  "response":"98",
  "msg":"Sorry, we can't requery a failed transaction",
}

Response (401):

    
{
  "response":"99",
  "msg":"Invalid data",
}

  
    
{
  "response":"99",
  "msg":"Invalid data",
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
invoice Your invoice number
  • Accept only numbers and alphabets
  • Value is pre-defined by system or merchant
  • To get an accurate result, please use the system generated invoice number (Qlicknpay Reference Number) retrievable at Transaction Reports page
    • OR
    you can get the Qlicknpay Reference Number by calling Get Transaction Details API
TYPE: STRING
EXAMPLE: 10011-FS789-20181009-Mt
method Transaction method
  • 1 = Payment using QlicknPay Payment Gateway
  • 2 = Payment using QlicknPay WhatsApp/Email Notification Invoices
TYPE: NUMBER
EXAMPLE: 1
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192
Invoice No FS789
Method 1

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
1000034|YOURAPIKEY00192|1000034-97062134-123619-PXP|1 will generate something like fc85b97551f5a2b8bf28d916f2f8055d

Common Response

The response variables for every payment type is slightly different from one another but some of it is a common variable that has the same variable name. You can refer these variable for your system to update the payment status.

Variable Name Description
invoice Your Invoice Number.
Example : INV00001
status_code Payment Status Code.
Example : 00
status Payment Status Message.
Example : Transaction Approved
amount 25.50

Errors Guides (Response Code)

The API will return error messages if any of the variables sent is invalid.

Error Code Description
00 Success / No error
97 Transaction Pending
99 Invalid invoice number
98 Transaction for the invoice failed
97 Invalid verification / Hashing

Get Settlement

You can retrieve all settlement records (successful transactions) for your account by calling this API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d date_from: 2020-01-02\
          -d date_to: 2020-04-19\
          -d page: 2\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&date_from=2020-01-02&date_to=2020-04-19&page=2&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (200):

    
[
    {
        "method": "FPX",
        "date": "2020-04-13 20:10:39",
        "invoice_no": "122384001",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    },
    {
        "method": "FPX",
        "date": "2020-04-13 20:35:16",
        "invoice_no": "122435184",
        "amount": "22.50",
        "fee": "1.50",
        "due": "21.00"
    },
    {
        "method": "FPX",
        "date": "2020-04-14 11:09:20",
        "invoice_no": "122622048",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    }
]


  
    
[
    {
        "method": "FPX",
        "date": "2020-04-13 20:10:39",
        "invoice_no": "122384001",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    },
    {
        "method": "FPX",
        "date": "2020-04-13 20:35:16",
        "invoice_no": "122435184",
        "amount": "22.50",
        "fee": "1.50",
        "due": "21.00"
    },
    {
        "method": "FPX",
        "date": "2020-04-14 11:09:20",
        "invoice_no": "122622048",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    }
]

Example response (400):

    
{
  "response": "97",
  "msg": "Invalid date_from format."
}


  
    
{
  "response": "97",
  "msg": "Invalid date_from format."
}

Example response (401):

    
{
  "response": "99",
  "msg": "Verification fail"
}


  
    
{
  "response": "99",
  "msg": "Verification fail"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTERGER
EXAMPLE: 2
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV0001

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034 will generate something like 609d3d1b0c3b93c22a17ed74092a6c31

Get Disburse Records

You can retrieve all disbursement records for your account by calling this API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d date_from: 2020-01-02\
          -d date_to: 2020-04-19\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&date_from=2020-01-02&date_to=2020-04-19&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (200):

    
[
    {
        "date_paid": "2020-04-16 00:00:00",
        "reference_no": "1587042694971184",
        "invoice_no": "INV0001",
        "amount_paid": "355.50",
        "payment_to": "12356789"
    },
    {
        "date_paid": "2020-04-17 00:00:00",
        "reference_no": "1587122268975321",
        "invoice_no": "INV0001",
        "amount_paid": "211.80",
        "payment_to": "12356789"
    }
]


  
    
[
    {
        "date_paid": "2020-04-16 00:00:00",
        "reference_no": "1587042694971184",
        "invoice_no": "INV0001",
        "amount_paid": "355.50",
        "payment_to": "562302619468"
    },
    {
        "date_paid": "2020-04-17 00:00:00",
        "reference_no": "1587122268975321",
        "invoice_no": "INV0001",
        "amount_paid": "211.80",
        "payment_to": "12356789"
    }
]

Example response (400):

    
{
  "response": "97",
  "msg": "Invalid date_from format."
}


  
    
{
  "response": "97",
  "msg": "Invalid date_from format."
}

Example response (401):

    
{
  "response": "99",
  "msg": "Verification fail"
}


  
    
{
  "response": "99",
  "msg": "Verification fail"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034 will generate something like 609d3d1b0c3b93c22a17ed74092a6c31

Tokenization

This feature allows you to perform card tokenization from MasterCard Payment Gateway Service(MPGS), and use the token to charge your customer later. This is suitable for subscription or recurring billing use cases.

Tokenization Flow

  1. Create Verification URL for payer.
  2. Redirect payer to Verification URL, Payer performs verification at MPGS thus reducing your PCI Compliance as sensitive card data does not need to be captured at your system or ours
  3. Once verification is done, our system will send an email and callback data to your callback URL with the Token ID
  4. You may use the Token ID to initiate a payment by using the Charge Card API.
  5. For every successful payment (by token), please wait 5 minutes before making a new payment with the same token ID.
  6. Use Delete Card API to remove the available token and use the same Verification URL to change or update the card details.

Create Verification URL

Use this API to create Verification URL for your customer. The URL provided will allow your customer to enter their card details at MPGS for verification purpose. Remember to store the response, as no card details will be stored in QlicknPay's servers.

Below is a Tokenization flow diagram to retrieve the token ID

API Endpoint URLs

Required Arguments

Example request:

     
curl POST {Endpoint URL}\
     -H 'Content-Type: application/json'\
     -d merchant_id: 10010\
     -d reference_id: REFERENCEID01\
     -d callback_url_be: http://www.webina.me/callback\
     -d callback_url_fe_succ: https://webina.me/success\
     -d callback_url_fe_fail: https://webina.me/fail\
     -d skip_receipt: 0\
     -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           

   
     
$data_request = array(
       'merchant_id' => '10010',
       'reference_id' => 'REFERENCEID01',
       'callback_url_be' => 'http://www.webina.me/callback',
       'callback_url_fe_succ' => 'https://webina.me/success',
       'callback_url_fe_fail' => 'https://webina.me/fail',
       'skip_receipt' => '0',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Response (200):

     
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "callback_url_be": "http://www.webina.me/callback",
    "success_url": "https://webina.me/success",
    "fail_url": "https://webina.me/fail",
    "skip_receipt": "0",
    "credit_card_verification_url": "https://www.qlicknpay.com/s?TM25960903008",
    "created": "2021-04-19 12:40:34",
    "modified": "2021-04-19 12:40:34"
}

   
     
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "callback_url_be": "http://www.webina.me/callback",
    "success_url": "https://webina.me/success",
    "fail_url": "https://webina.me/fail",
    "skip_receipt": "0",
    "credit_card_verification_url": "https://www.qlicknpay.com/s?TM25960903008",
    "created": "2021-04-19 12:40:34",
    "modified": "2021-04-19 12:40:34"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
reference_id Your unique reference ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
hash The secure hash string to validate the request. Refer our Hashing Guide Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
amount Amount to charge.
  • By default, if the 'amount' variable is omitted, cardholder will not be charged.
    (If your MPGS merchant profile is configured for 3DS payment, a verification amount of RM1.00 (required by bank) is needed but will not be charged to the cardholder)
  • The default value will be ignored if this field is specified
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: 192.50
invoice Unique reference number of this payment
  • This is an optional variable but it will be mandatory if the 'amount' variable is entered.
  • Accept alphanumeric only.
  • Length: Max 20 characters.
TYPE: STRING
EXAMPLE: INV01
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
callback_url_fe_succ Callback URL for your front-end successful transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/success
callback_url_fe_fail Callback URL for your front-end failed transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/fail
skip_receipt Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
  • Accepts only integer
  • Default value is '0'
TYPE: INTEGER
EXAMPLE: 0
baggage_variable This parameter enables you to send any parameter and its corresponding value to this API, which will then return the same value during the callback process. To do so, enter your list of parameter's name. For example buyer_personal_id|invoice_running_number.
  • Accepts only alphanumeric characters
  • Length for each parameter: Not more than 10 characters
  • Values must be separated by a pipe character (|) with no spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your baggages variable name* Ensure that the value(s) for each variable is synchronized with the total number of variables mentioned above
  • Length: Not more than 100 characters
  • For instance, when the value of the 'baggage_variable' parameter is 'buyer_personal_id|invoice_running_number', the new parameters to be sent should be 'buyer_personal' and 'invoice_running_number.'
    • TYPE: STRING
    EXAMPLE:VALUE1

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
Merchant id 10010
Reference ID REFERENCEID01
Amount 121.50
Invoice INV01

If you are NOT using the 'amount' and 'invoice' variables
Format: API Key + | + Merchant ID + | + Reference ID

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode($reference_id));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|REFERENCEID01 will generate something like 8b125ceb7739fe8260697865e59f481c



If you are using the 'amount' and 'invoice' variables
Format: API Key + | + Merchant ID + | + Reference ID + | + Amount + | + Invoice

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|REFERENCEID01|121.50|INV01 will generate something like b1211e8e3d748c5e9a191c19004c9c14

How to receive the Credit Card Verification response (via callback)?

The response for Credit Card Verification will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your customer successfully completed the card verification.

Field Name Example Value
reference_id Your unique reference ID
  • Alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
txn_status Response code of the status of verification.* Refer Response Code table for description.
  • Alphabets and numbers only.
  • Length: Max 2 characters.
TYPE: STRING
EXAMPLE: 00
msg Message status for verification
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: Verification Approved
token Unique ID for Card's Token
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved
hash Secure hash string to validate the response sent to your callback endpoint. Refer below for more information on how to generate the secure hash string.
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
nameOnCard Name on the card
  • Alphabets only.
TYPE: STRING
EXAMPLE: JOHN SMITH
numberCard Card number
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: 512345xxxxxx0008
schemeCard Card scheme
  • Alphabets only.
TYPE: STRING
EXAMPLE: MASTERCARD
issuerCard Card issuer
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: MAYBANK BERHAD
expiryMonthCard Card expiry (Month)
  • Numbers only.
TYPE: INTEGER
EXAMPLE: 5
expiryYearCard Card expiry (Year)
  • Numbers only.
TYPE: INTEGER
EXAMPLE: 21
fundingMethodCard Card funding method
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: CREDIT
amount Amount of the first payment
  • Numbers only
TYPE: STRING
EXAMPLE: 121.50
invoice Unique invoice number from the first payment
  • Alphabets only.
TYPE: STRING
EXAMPLE: INV01

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
Reference ID REFERENCEID01
Transaction Status Code 00
Transaction Status Message Verification Approved
Token e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved

Format: API Key + Reference ID + Transaction Status Code + Transaction Status Message + Token

Sample code to hash above values: md5($api.$reference_id.$status_code.$status_msg.$token);

For example, if the details received are as above, the hash string to be generated is constructed as follows: YOURAPIKEY00192REFERENCEID0100Verification Approvede3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved will generate something like d1be855ccbb2aaf054e2a818c5ee7b94

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

Charge Card by Using Token

Use this API to charge VISA / MasterCard card with token generated.

Below is a Tokenization flow diagram on how to charge the card by using the token ID provided

API Endpoint URLs

URL Parameters

Field Name Example Value
{Token ID} Token ID that you received from your callback endpoint
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved

Required Arguments

Example request (Charge Card):

         
curl POST {Endpoint URL}\

           -H 'Content-Type: application/json'\
           -d merchant_id: 10010\
           -d invoice: INV01\
           -d amount: 10.50\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                      

       
         
$data_request = array(
           'merchant_id' => '10010',
           'invoice' => 'INV01',
           'amount' => '10.50',
           'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                      );

         $fields_string = json_encode($data_request);

         $ch = curl_init();
         curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
         curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
         curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
         curl_setopt($ch, CURLOPT_POST, 1);
         curl_setopt($ch, CURLOPT_POSTFIELDS,
                     $fields_string);

         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

         $server_output = curl_exec($ch);

         curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
invoice Your unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV01
amount Final amount to be paid by payer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format.
  • Must be more than or equal 1.50.
TYPE: STRING
EXAMPLE: 10.50

Optional Argument

This optinal variable is only available in sandbox enviroment.

sandbox_charge_status Charge simulation status. Set '0' for a sample successful charge card. Otherwise, the charge is return as unsuccessful payment.
  • Accept ONLY numbers
  • Default value is '0'
TYPE: INT
EXAMPLE: 0

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Token ID e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved
Invoice INV01
Amount 10.50

Format:
API Key + | + Merchant ID + | + Token ID + | + Invoice + | + Amount

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved|INV01|10.50 will generate something like ec9f056a575b44ed441a10f977a00257

Respond from Charge Card API

Response (200):

         
{
    "response": "00",
    "txn_status": "00",
    "msg": "Payment Successful",
    "reason": "",
    "error_code": "",
    "invoice": "INV01",
    "amount": "10.50",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "transaction_authorizationCode": "T91898"
}

       
         
{
    "response": "00",
    "txn_status": "00",
    "msg": "Payment Successful",
    "reason": "",
    "error_code": "",
    "invoice": "INV01",
    "amount": "10.50",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "transaction_authorizationCode": "T91898"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
txn_status Status of the transaction
  • 00 - Successful Payment
  • 12 - Failed Payment
TYPE: STRING
EXAMPLE: 00
msg Message status of the transaction

TYPE: STRING
EXAMPLE: Payment Successful
reason Reason of the error. This message received directly from the MPGS. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: Not sufficient funds (INSUFFICIENT_FUNDS)
error_code Error code received from the MPGS. Please refer MPGS Error Code for more explaination of the error. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: 51
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
token Transaction Token ID

TYPE: STRING
EXAMPLE: e3b0c44vcr2e1c1c149afbf4c899
6fb92427ae41esq124334ca4111452b855ved
transaction_authorizationCode Value generated by issuing bank in response to a proposal to transfer funds.

TYPE: STRING
EXAMPLE: T91898

Delete Card

Use this API to delete the card Token. Once the card token is successfully deleted, you can initiate another verification with the same reference number or same URL provided.

API Endpoint URLs

URL Parameters

Field Name Example Value
{Reference ID / Token ID} Your unique reference ID or Token ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters for Reference ID and 64 characters for Token ID.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01

Required Arguments

Example request:

            
curl POST {Endpoint URL}\
            -H 'Content-Type: application/json'\
            -d merchant_id: 10010\
            -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                         

          
            
$data_request = array(
              'merchant_id' => '10010',
              'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                            );

            $fields_string = json_encode($data_request);

            $ch = curl_init();
            curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
            curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
            curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS,
                        $fields_string);

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $server_output = curl_exec($ch);

            curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guide below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Reference ID / Token ID REFERENCEID01

Format: API Key + | + Merchant ID + | + Reference ID

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode($reference_id));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|REFERENCEID01 will generate something like 8b125ceb7739fe8260697865e59f481c

Respond from Delete Card API

Response (200):

            
{
    "response": "00",
    "msg": "Successfully delete the Token",
    "reference_id": "REFERENCEID01"
}

          
            
{
    "response": "00",
    "msg": "Successfully delete the Token",
    "reference_id": "REFERENCEID01"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
msg Message of request status. TYPE: STRING
EXAMPLE: Successfully delete the Token

Get Available Token

Use this API to get all available Token that you have created. Max display per page is 100 rows.

API Endpoint URLs

Required Arguments

Example request:

             
curl POST {Endpoint URL}\
             -H 'Content-Type: application/json'\
             -d merchant_id: 10010\
             -d date_from: 2021-04-14\
             -d date_to: 2021-04-19\
             -d status: 3\
             -d page: 1\
             -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                           

           
             
$data_request = array(
               'merchant_id' => '10010',
               'date_from' => '2021-04-14',
               'date_to' => '2021-04-19',
               'status' => '3',
               'page' => '1',
               'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                              );

             $fields_string = json_encode($data_request);

             $ch = curl_init();
             curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
             curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
             curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
             curl_setopt($ch, CURLOPT_POST, 1);
             curl_setopt($ch, CURLOPT_POSTFIELDS,
                         $fields_string);

             curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

             $server_output = curl_exec($ch);

             curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the data.
  • Accept only numbers
  • 0 - All failed verification, 1 - All success verification, 2 - Both failed and success verification, 3 - Failed, success and delay verification
TYPE: INTEGER
EXAMPLE: 3
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 10010
API YOURAPIKEY00192

Format: API Key + | + Merchant ID

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010 will generate something like 2647dbdcd89734fe9e95f2d6f68bd826

Respond from Get Avaiable Token API

Response (200):

             
[
     {
         "total_page_available": 1,
     },
     {
         "reference_id": "REFID01",
         "verification_status": "Success",
         "token": "547b946bda42d20a35b6bas19231d3n13ud16f3b2fa04ee73e6c6470b779ec314",
         "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tFKiUY",
         "created": "2021-04-19 10:06:50",
         "modified": "2021-04-19 11:10:25",
     },
     {
       "reference_id": "REFID02",
       "verification_status": "Failed",
       "token": "e3b0c44298fc1c149afbfs12301iw9jfb92427ae41e4649b934ca495991b7852b855",
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tAuI7",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     },
     {
       "reference_id": "REFID03",
       "verification_status": "Delay",
       "token": '',
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tkKSH",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     }
 ]
         

           
             
[
     {
         "total_page_available": 1,
     },
     {
         "reference_id": "REFID01",
         "verification_status": "Success",
         "token": "547b946bda42d20a35b6bas19231d3n13ud16f3b2fa04ee73e6c6470b779ec314",
         "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tFKiUY",
         "created": "2021-04-19 10:06:50",
         "modified": "2021-04-19 11:10:25",
     },
     {
       "reference_id": "REFID02",
       "verification_status": "Failed",
       "token": "e3b0c44298fc1c149afbfs12301iw9jfb92427ae41e4649b934ca495991b7852b855",
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tAuI7",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     },
     {
       "reference_id": "REFID03",
       "verification_status": "Delay",
       "token": '',
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tkKSH",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     }
 ]
total_page_available Total page available. (Max display per page is 100 rows)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
verification_status Token verification status

TYPE: STRING
EXAMPLE: Success
token Customer's Token ID.

TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
b2fa04ee73e6c6470b779ec314
credit_card_verification_url Card Verification URL. This URL will ask customers to fill up their Credit Card number.

TYPE: STRING
EXAMPLE: https://www.qlicknpay.com/s?TMzRUT0tFKiUY
created Date of Verification Requested

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40
modified Date of Modified

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Token Details

Use this API to retrieve specific token in more details.

API Endpoint URLs

URL Parameters

Field Name Example Value
{Reference ID} Your unique reference ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01

Required Arguments

Example request (Get Token Details):

              
curl POST {Endpoint URL}\

                -H 'Content-Type: application/json'\
                -d merchant_id: 10010\
                -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                                

            
              
$data_request = array(
                'merchant_id' => '10010',
                'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                );

              $fields_string = json_encode($data_request);

              $ch = curl_init();
              curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
              curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
              curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
              curl_setopt($ch, CURLOPT_POST, 1);
              curl_setopt($ch, CURLOPT_POSTFIELDS,
                          $fields_string);

              curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

              $server_output = curl_exec($ch);

              curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10010
hash The secure hash string to validate the request. Refer our Hashing Guide below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Reference ID REFERENCEID01

Format: API Key + | + Merchant ID + | + Reference ID

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode($reference_id));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|REFERENCEID01 will generate something like 8b125ceb7739fe8260697865e59f481c

Respond from Get Token Details API

Response (200):

              
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "verification_status": "Success",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "callback_url_be": "https:\/\/www.webina.me\/callback",
    "callback_url_fe_succ": "https:\/\/www.webina.me\/success",
    "callback_url_fe_fail": "https:\/\/www.webina.me\/failed",
    "skip_receipt": false,
    "credit_card_verification_url": "https:\/\/www.qlicknpay.com\/s?TMzRUT0tAuI7",
    "credit_card_details": {
        "nameOnCard": "PAYER NAME HERE",
        "numberCard": "512345xxxxxx0008",
        "schemeCard": "MASTERCARD",
        "issuerCard": "MAYBANK BERHAD",
        "expiryMonthCard": "5",
        "expiryYearCard": "24",
        "fundingMethodCard": "CREDIT"
    },
    "created": "2021-04-19 13:15:40",
    "modified": "2021-04-19 14:44:10"
}

            
              
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "verification_status": "Success",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "callback_url_be": "https:\/\/www.webina.me\/callback",
    "callback_url_fe_succ": "https:\/\/www.webina.me\/success",
    "callback_url_fe_fail": "https:\/\/www.webina.me\/failed",
    "skip_receipt": false,
    "credit_card_verification_url": "https:\/\/www.qlicknpay.com\/s?TMzRUT0tAuI7",
    "credit_card_details": {
        "nameOnCard": "PAYER NAME HERE",
        "numberCard": "512345xxxxxx0008",
        "schemeCard": "MASTERCARD",
        "issuerCard": "MAYBANK BERHAD",
        "expiryMonthCard": "5",
        "expiryYearCard": "24",
        "fundingMethodCard": "CREDIT"
    },
    "created": "2021-04-19 13:15:40",
    "modified": "2021-04-19 14:44:10"
}
response Respond from the API. (This is not status of the verification)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
verification_status Token verification status

TYPE: STRING
EXAMPLE: Success
token Customer's Token ID.

TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
b2fa04ee73e6c6470b779ec314
callback_url_be Back-end Callback URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
callback_url_fe_succ Successful Verification Return URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
callback_url_fe_fail Failed Verification Return URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
skip_receipt Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
  • Accepts only integer
  • Default value is '0'
TYPE: INTEGER
EXAMPLE: 0
credit_card_verification_url Card Verification URL. This URL will ask customers to fill up their Credit Card number.

TYPE: STRING
EXAMPLE: https://www.qlicknpay.com/s?TMzRUT0tFKiUY
credit_card_details Details of the customer's card
  • nameOnCard - Card Holder Name
  • numberCard - Card Number
  • schemeCard - Card Type
  • issuerCard - Type of Bank Card
  • expiryMonthCard - Expiry data (Month)
  • expiryYearCard - Expiry data (Year)
  • fundingMethodCard - Funding method type
TYPE: JSON
EXAMPLE: *Please refer our sample respond*
created Date of Verification Requested

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40
modified Date of Modified

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Transactions

Use this API to get all available transaction that was charged using tokens. Max display per page is 100 rows.

API Endpoint URLs

Required Arguments

Example request:

               
curl POST {Endpoint URL}\
               -H 'Content-Type: application/json'\
               -d merchant_id: 10010\
               -d date_from: 2021-04-14\
               -d date_to: 2021-04-19\
               -d status: 3\
               -d page: 1\
               -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                               

             
               
$data_request = array(
                 'merchant_id' => '10010',
                 'date_from' => '2021-04-14',
                 'date_to' => '2021-04-19',
                 'status' => '3',
                 'page' => '1',
                 'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                  );

               $fields_string = json_encode($data_request);

               $ch = curl_init();
               curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
               curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
               curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
               curl_setopt($ch, CURLOPT_POST, 1);
               curl_setopt($ch, CURLOPT_POSTFIELDS,
                           $fields_string);

               curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

               $server_output = curl_exec($ch);

               curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the data.
  • Accept only numbers
  • 0 - All failed transactions, 1 - All success transactions, 2 - Both failed and success transactions, 3 - Failed, success and pending transactions
TYPE: INTEGER
EXAMPLE: 3
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 10010
API YOURAPIKEY00192

Format: API Key + | + Merchant ID

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010 will generate something like 2647dbdcd89734fe9e95f2d6f68bd826

Respond from Get Transactions API

Response (200):

               
[
  {
     "total_page_available": 1,
  },
  {
     "reference_id": "REFID01",
     "invoice": "INV01",
     "amount": "12.50",
     "txn_status": "00",
     "status": "Payment Successful",
     "time": "2021-04-19 10:06:50",
  }
]
           

             
               
[
  {
     "total_page_available": 1,
  },
  {
     "reference_id": "REFID01",
     "invoice": "INV01",
     "amount": "12.50",
     "txn_status": "00",
     "status": "Payment Successful",
     "time": "2021-04-19 10:06:50",
  }
]
total_page_available Total page available. (Max display per page is 100 rows)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
txn_status Status code for the payment
  • 00 - Successful Payment
  • 12 - Failed Payment
TYPE: STRING
EXAMPLE: 00.
status Message status for verification

TYPE: STRING
EXAMPLE: Payment Successful.
time Date of Transaction

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Transaction Details

Use this API to retrieve specific transactions in more details.

API Endpoint URLs

URL Parameters

Field Name Example Value
{Invoice} Your unique Invoice ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV01

Required Arguments

Example request (Get Transaction Details):

                
curl POST {Endpoint URL}\

                  -H 'Content-Type: application/json'\
                  -d merchant_id: 10010\
                  -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                                    

              
                
$data_request = array(
                  'merchant_id' => '10010',
                  'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                    );

                $fields_string = json_encode($data_request);

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
                curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                            $fields_string);

                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                $server_output = curl_exec($ch);

                curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10010
hash The secure hash string to validate the request. Refer our Hashing Guide below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
merchant id 10010
Invoice ID INV01

Format: API Key + | + Merchant ID + | + Invoice ID

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|INV01 will generate something like c42f4a37aa482c5f2f736a9e864470d7

Respond from Get Transactions API

Response (200):

                
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "invoice": "INV01",
    "amount": "12.50",
    "credit_card_details": {
        "nameOnCard": "PAYER NAME OF CARD HERE",
        "numberCard": "512345xxxxxx0008",
        "schemeCard": "MASTERCARD",
        "issuerCard": "MAYBANK BERHAD",
        "expiryMonthCard": "5",
        "expiryYearCard": "24",
        "fundingMethodCard": "CREDIT"
    },
    "authorization_code": "764746",
    "status": "Payment Successful",
    "time": "2021-04-19 13:15:40"
}

              
                
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "invoice": "INV01",
    "amount": "12.50",
    "credit_card_details": {
        "nameOnCard": "PAYER NAME OF CARD HERE",
        "numberCard": "512345xxxxxx0008",
        "schemeCard": "MASTERCARD",
        "issuerCard": "MAYBANK BERHAD",
        "expiryMonthCard": "5",
        "expiryYearCard": "24",
        "fundingMethodCard": "CREDIT"
    },
    "authorization_code": "764746",
    "status": "Payment Successful",
    "time": "2021-04-19 13:15:40"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
txn_status Status of the transaction
  • 00 - Successful Payment
  • 12 - Failed Payment
  • 09 - Pending Payment
TYPE: STRING
EXAMPLE: 00
status Message status for transaction

TYPE: STRING
EXAMPLE: Payment Successful.
reason Reason of the error. This message received directly from the MPGS. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: Not sufficient funds (INSUFFICIENT_FUNDS)
error_code Error code received from the MPGS. Please refer MPGS Error Code for more explaination of the error. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: 51
credit_card_details Details of the customer's card
  • nameOnCard - Card Holder Name
  • numberCard - Card Number
  • schemeCard - Card Type
  • issuerCard - Type of Bank Card
  • expiryMonthCard - Expiry data (Month)
  • expiryYearCard - Expiry data (Year)
  • fundingMethodCard - Funding method type
TYPE: JSON
EXAMPLE: *Please refer our sample respond*
authorization_code Value generated by issuing bank in response to a proposal to transfer funds.

TYPE: STRING
EXAMPLE: T91898
time Date of Transaction

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

MPGS Error Code

Below is a MPGS error code and description received from the MPGS after payment was made.

Click here to view the error code:

Batch Charge Card

Use this API to charge multiple VISA / MasterCard card in batch mode.

Below is a Tokenization flow diagram on how to charge multiple cards by using the token ID provided

API Endpoint URLs

Required Arguments

Example request (Batch Charge Card):

     
curl POST {Endpoint URL}\

       -H 'Content-Type: application/json'\
       -d merchant_id: 10010\
       -d token_list: 0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00;
caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00;
9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3dad5cc0e0d26f650ffd,INV03,31.00;\
       -d batch_id: BATCH01\
       -d callback_url_be: https://www.webina.me/callback\
       -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
              

   
     
$data_request = array(
       'merchant_id' => '10010',
       'token_list' => '0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00;
caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00;
9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3dad5cc0e0d26f650ffd,INV03,31.00;',
       'batch_id' => 'BATCH01',
       'callback_url_be' => 'https://www.webina.me/callback',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
token_list Your list of the generated token.
  • Must be less than 500 list of tokens.
  • Below is a sample format of the string with a list of tokens

*Click on the image for a larger resolution

Sample format for each detail:


Sample format for multiple payments:

  • Invoice No must be alphanumerics and less than 20 characters.
  • Amount must be more than RM1.50

TYPE: STRING
EXAMPLE: 0c671df1ad7419bea32204f0989e4522703045632ff
e52eb98ab69c7891dd9cb,INV01,41.00;caeb58f63f75b7f802
6b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02
,11.00;9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3
dad5cc0e0d26f650ffd,INV03,31.00;
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
callback_url_be Back-end Callback URL. Your payment status will be sent to your callback endpoint. Refer here on how to receive the payment status (via callback).
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
hash The secure hash string to validate the request. Refer our Hashing Guides below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
Merchant id 10010
Batch ID BATCH01
Token List 0c671df1ad7419bea32204f0989e4522703045632ff
e52eb98ab69c7891dd9cb,INV01,41.00;caeb58f63f75b7f802
6b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02
,11.00;9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3
dad5cc0e0d26f650ffd,INV03,31.00;

Format: API Key + | + Merchant ID + | + Batch ID + | + Token List

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode($reference_id)."|".urldecode($token_list));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|BATCH01|0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00; caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00;9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3dad5cc0e0d26f650ffd,INV03,31.00; will generate something like c75cdc5ef198927636529bdff310dfc5

How to receive the payment status (via callback)?

The payment status will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your request has been verified by MPGS.

Field Name Example Value
batch_id Your unique Batch ID
  • Alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: BATCH01
token_list Your list of the generated token including payment status and error codes (if any)
  • Below is a sample format of the string with a updated list of tokens

*Click on the image for a larger resolution

Sample format for UNSUCCESSFUL payment:


Sample format for SUCCESSFUL payment:


Sample format for multiple payments:

  • Refer here for the description of your error code.
TYPE: STRING
hash Secure hash string to validate the response sent to your callback endpoint. Refer below for more information on how to generate the secure hash string.
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide (Callback)

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
Merchant id 10010
Batch ID BATCH01
Token List 0c671df1ad7419bea32204f0989e4522703045632ff
e52eb98ab69c7891dd9cb,INV01,41.00,12,51;caeb58f63f75b7f802
6b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02
,11.00,00,;9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3
dad5cc0e0d26f650ffd,INV03,31.00,12,51;

Format: API Key + Merchant ID + Batch ID + Token List

Sample code to hash above values: md5($api.$merchant_id.$batch_id.$token_list);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|BATCH01|0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00,12,51; caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00,00,;9b6c94a3c89bd6f039503eece4d84646dbfe a08411aa3dad5cc0e0d26f650ffd,INV03,31.00,12,51; will generate something like f2cefd3a7994a686269e76867523221b

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

Cancel Charge Card by Batch

Use this API to cancel the payment that has been submitted by batch. You are only allowed to cancel payment request that is less than 10 minutes from the batch submission.

API Endpoint URLs

Required Arguments

Example request:

     
curl POST {Endpoint URL}\
     -H 'Content-Type: application/json'\
     -d merchant_id: 10010\
     -d batch_id: BATCH01\
     -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           

   
     
$data_request = array(
       'merchant_id' => '10010',
       'batch_id' => 'BATCH01',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
hash The secure hash string to validate the request. Refer our Hashing Guide below for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guide

This section will explain how to secure request. This will be used to generate the hash field in your request from merchant's site.

Field Name Example Value
API YOURAPIKEY00192
Merchant ID 10010
Batch ID BATCH01

Format: API Key + | + Merchant ID + | + Batch ID

Sample code to hash above values:
md5($API."|".urldecode($merchant_id)."|".urldecode($batch_id));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|10010|BATCH01 will generate something like 8cc52c86ca94910beea377a425f5015e

Get Batch

Retrieve all submitted batches of data.

API Endpoint URLs

Required Arguments

Example request:

     
                          
curl POST {Endpoint URL}\
           -d merchant_id: 10001\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           
 
   
     
                       
$ch = curl_init();
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 "merchant_id=10001&hash=fc85b97551f5a2b8bf28d916f2f8055d");

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Example response (200):

     
[
     {
         "total_page_available": 1,
     },
     {
         "batch_id": "BATCH03",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "12",
         "status": "Payment Unsuccessful",
         "time": "2022-01-26 16:11:38",
     },
     {
         "batch_id": "BATCH02",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "00",
         "status": "Payment Successful",
         "time": "2022-01-25 15:15:00",
     },
     {
         "batch_id": "BATCH01",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "09",
         "status": "Payment Pending",
         "time": "2022-01-25 14:13:02",
     },
     {
         "batch_id": "BATCH00",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "01",
         "status": "Payment Partially Successful",
         "time": "2022-01-24 05:17:04",
     }

 ]
 

   
     
[
     {
         "total_page_available": 1,
     },
     {
         "batch_id": "BATCH03",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "12",
         "status": "Payment Unsuccessful",
         "time": "2022-01-26 16:11:38",
     },
     {
         "batch_id": "BATCH02",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "00",
         "status": "Payment Successful",
         "time": "2022-01-25 15:15:00",
     },
     {
         "batch_id": "BATCH01",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "09",
         "status": "Payment Pending",
         "time": "2022-01-25 14:13:02",
     },
     {
         "batch_id": "BATCH00",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "01",
         "status": "Payment Partially Successful",
         "time": "2022-01-24 05:17:04",
     }
 ]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the transactions.
  • 0 - All failed batches
  • 1 - All successful batches
  • 2 - Both failed and successful batches
  • 3 - Failed,successful,pending batches
  • 4 - All partially successful batches *means batch payment is partially successful and not all payment wihtin batch was failed.
TYPE: INTEGER
EXAMPLE: 1
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
merchant id 1000034
API YOURAPIKEY00192

Format: API Key + | + Merchant ID

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

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034 will generate something like 609d3d1b0c3b93c22a17ed74092a6c31

Get Batch Details

Retrieve selected batch in details

API Endpoint URLs

Required Arguments

Example request:

     
                          
curl POST {Endpoint URL}\
           -d merchant_id: 10001\
           -d batch_id: BATCH01\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           
 
   
     
                       
$ch = curl_init();
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 "merchant_id=10001&batch_id=BATCH01&hash=fc85b97551f5a2b8bf28d916f2f8055d");

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Example response (200):

     
[
         "response": "00",
         "batch_id": "BATCH01",
         "token_list": "5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV56,31.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV782,11.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV923,41.00,00,;5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV709,21.00,00,;1417a502d6851600403bc383592255632e577a159484dc0fce59ee67f1d26bb7,INV504,11.00,00,;5dd36cd067ce6bfbe8563554019127b5a26a25400f80b9f44ff816b912ad2a43,INV548,32.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV767,31.00,00,;c31c989bdbb08fb5b94636f9279d745dd72ba1d00768c1cede6646aecdc824c3,INV162,12.00,00,;",
         "txn_status": "00",
         "status": "Payment Successful",
         "callback_url_be": "https://www.webina.me/test/",
         "time": "2022-01-21 15:36:40",
 ]
 

   
     
[
       "response": "00",
       "batch_id": "BATCH01",
       "token_list": "5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV56,31.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV782,11.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV923,41.00,00,;5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV709,21.00,00,;1417a502d6851600403bc383592255632e577a159484dc0fce59ee67f1d26bb7,INV504,11.00,00,;5dd36cd067ce6bfbe8563554019127b5a26a25400f80b9f44ff816b912ad2a43,INV548,32.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV767,31.00,00,;c31c989bdbb08fb5b94636f9279d745dd72ba1d00768c1cede6646aecdc824c3,INV162,12.00,00,;",
       "txn_status": "00",
       "status": "Payment Successful",
       "callback_url_be": "https://www.webina.me/test/",
       "time": "2022-01-21 15:36:40",
 ]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
hash The secure hash string to validate the request. Refer our Hashing Guides Tab for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Hashing Guides

This section will explain how to secure request. This will be used to generate the hash field in your request.

Field Name Example Value
Merchant id 1000034
API YOURAPIKEY00192
Batch ID BATCH01

Format: API Key + | + Merchant ID + | + Batch ID

Sample code to hash above values:
md5($api."|".$merchant_id."|".$batch_id);

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
YOURAPIKEY00192|1000034|BATCH01 will generate something like 6b1b8d5549e4f347ff6255241ecfeb70

OpenCart

Kindly ensure your OpenCart version is compatible before proceeding to download and install QlicknPay's plugin.

 
Click the URL below to view supported version of OpenCart before using our QlicknPay's plugin.
https://www.opencart.com/?QlicknPay

Download OpenCart Plugins

Once you have ensure your OpenCart version is compatible with QlicknPay, click here and click on the "Download" button to download the plugin.

Begin Installation

  1. Login into your OpenCart Admin Panel using your OpenCart login credentials.
  2. Proceed to "Extension Installer" setting.
  3. Click on the upload button and choose the .zip folder from the downloaded file.
  4. Wait until the installation process finishes before clicking on the "Continue" button to proceed.

Configuring Your QlicknPay Plugin

NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. In the OpenCart Admin Panel, go to the Extension List page and choose "Payment" as the extension type selection option.
  2. Search for QlicknPay extension and click on the "Edit" button.
  3. Fill in all the required fields accordingly and save the changes.

Start Selling

Once you have configured your QlicknPay Plugin, kindly perform at least one test transaction before you start selling.

Prestashop

Kindly ensure your PrestaShop version is compatible before proceeding to download and install QlicknPay's plugin. Below are the supported version of PrestaShop to use QlicknPay's plugin.

 
  • 1.4
  • 1.6
  • 1.7
  • Any version after the listed versions

Download Prestashop Plugins

  1. Version 1.4
  2. Version 1.6
  3. Version 1.7 and above

Begin Installation

After your download has finished, follow these steps to start installing the plugin.

  • Login into your PrestaShop Admin Panel using your PrestaShop login credentials.
  • Go to "Modules" page and click on the "Upload Module" button.
  • Upload the downloaded .zip file and wait until the process finishes.

Configuring Your QlicknPay Plugin

Once the installation process has finished, follow these steps to begin configuring your QlicknPay Plugin.
NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. In the PrestaShop Admin Panel, go to the Module and click on the "Configure" button next to the QlicknPay Module List.
  2. Fill in all the required fields accordingly and save the changes.

Start Selling

Once you have configured your QlicknPay Plugin, kindly perform at least one test transaction before you start selling.

WooCommerce

QlicknPay's Plugin for WooCommerce is supported by both older and newer versions of WooCommerce.

Download WooCommerce Plugin

Download the QlicknPay's Plugin for WooCommerce by clicking here.

Begin Installation

  1. Login into your WooCommerce Admin Panel using your WooCommerce login credentials.
  2. Go to the "Add Plugin" page by clicking on Plugins > Add New on the left side menu.
  3. Click on the "Upload Plugin" button and choose the downloaded .zip file.
  4. Click on "Install Now" then activate the plugin by clicking on "Activate Plugin" once the installation process finishes.

Configuring Your QlicknPay Plugin

NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. In the WooCommerce Admin Panel, click on "Settings".
  2. Fill in all the required fields accordingly, enable the plugin by clicking on the "Enable/Disable" checkbox and save the changes.

Start Selling

Once you have configured your QlicknPay Plugin, kindly perform at least one test transaction before you start selling.

Ecwid

Follow these steps to start installing the plugin.

  1. Login into your ECWID Admin Panel using your ECWID login credentials.
  2. Go to "Payment" page by clicking on Payment menu.
  3. Go to "Add New Payment Method" section, click on the "Choose Payment Processor" button and choose QlicknPay (displayed as PayDirect FPX in the dropdown list).
  4. Once you have chosen QlicknPay (PayDirect FPX) in the list, ECWID will automatically redirect you to QlicknPay (PayDirect FPX) Control Panel page.

Configuring Your QlicknPay Plugin

NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. Fill in all the required fields accordingly.
  2. Choose your account type (Production) in the "Advanced Settings" section.
  3. Once you have filled in all fields and choose your account type, refresh the page for the changes to take place.

Start Selling

Once you have configured your QlicknPay Plugin, kindly perform at least one test transaction before you start selling.

Drupal

QlicknPay's Plugin for Drupal is only compatible for Drupal 8 provided that Drupal Commerce is also installed in your server.

Download Drupal Plugin

Download the QlicknPay's Plugin for Drupal by clicking here.

Begin Installation

After your download has finished, install the plugin into your system and proceed to configure the plugin.

Configuring Your QlicknPay Plugin

NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. Login into your Drupal Admin Panel using your Drupal login credentials.
  2. Click on "Commerce" tab to proceed with configuring the plugin.
  3. Next, click on the "Configuration" tab.
  4. Click on "Payment Gateways" configuration.
  5. Click on "Add payment gateway" button to add and enable QlicknPay as your payment gateway.
  6. Fill in all the required fields accordingly, enable the plugin by clicking on the "Enable" checkbox in the Status Option and save the changes.

Easystore

Follow these steps to start installing the payment gateway.

NOTE: You will need your Betterpay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. Login into your Easystore Admin Panel.
  2. Go to "Settings" page by clicking on Settings on the left side menu.
  3. Go to "Payments" section.
  4. Click on "Add payment method" button and choose "Betterpay".
  5. Fill all requirement information and click save.
  6. Your payment gateway is now available in your checkout pages.

Start Selling

Once you have configured your Betterpay Plugin, kindly perform at least one test transaction before you start selling.

For sandbox account, please follow these instructions

  1. At checkout pages, you need to manually enter parameters ?testing=true at the end of Storefront checkout url.
  2. Example:
    https://yourstore.easy.co/sf/checkout/9b6a59bf-f971-4b4b-b3c4-f0b485db89a7?testing=true
  3. Proceed to the URL.
  4. Fill all payment details and proceed to the payment as usual.

Magento

Extract Magento Extension.

Kindly please download our Magento Extension here: Betterpay.zip

1. Extract Magento Extension

  • Assuming we have installed magento, please extract the Betterpay extension zip in the app/code.
  • Then open the terminal where you installed magento and run the following command:
    -php bin/magento indexer:reindex
    -php bin/magento setup:upgrade
    -php bin/magento setup:static-content:deploy -f
    -php bin/magento cache:flush


2. Setting Currency

  • Please set currency to MYR or IDR, please go to menu.
  • Store/Configuration/Currency Setup/Currency Option
  • Then save the configuration.


3. Betterpay Configuration

  • Login to your admin panel, then please click menu stores => configuration.

  • Click “Sales” menu.

  • Then click “Payment Methods”.

  • In the other payment method, please select Betterpay Settings then enter the configuration you need such as “merchant_id” and “api_key”.
    Login and click here to retrieve your Merchant ID and API Key.
  • After everything is in order, please save the configuration, and Betterpay Payment is ready to use.

PayPal

How to get your PayPal Client ID and PayPal Secret Key.

Login into your Developer PayPal Account. Go to https://developer.paypal.com/ and log into main page.

Go to your Dashboard Page

After successfully login into your account, find the drop down menu at your top right corner. Click on Dashboard.

Create a REST API apps

On REST API apps section, click on Create App button.

Create your App. You can choose your own App Name and SandBox developer account.

Get your Client ID and Secret Key

PayPal system will give you an ID for API integration. Use those Client ID and Secret ID to enable PayPal payment

Use your 'Sandbox' ID for Demo account (https://www.demo.qlicknpay.com/) and 'Live' ID for live production account (https://www.qlicknpay.com/)

Third Party Platform Guides

Merchant will be able to synchronize their products on Lazada/Shopee and QlicknPay using our Lazada/Shopee API. Each sold / updated / deleted product will be reflected in both Lazada/Shopee and QlicknPay.

Lazada

You will need your Lazada App Key and App Secret in order to use this feature.

Please follow the following steps to get your Lazada App Key and App Secret.

  1. Login into your Developer Lazada Account by going to https://uac.lazada.com/. If you do not have an account, please register the account embed with your Lazada Seller ID.
  2. Create your own app by going to App Console > Create. Choose Seller-In-House App and create. Fill in your app name, description and logo image according to your prefences.
  3. IMPORTANT! Specify your callback URL with the following URL: Please login to view the URL
  4. Get your App Key and App Secret at your APP overview page.

Shopee

Kindly get the following Shopee credentials ready in order to start using this feature.

  • Partner ID
  • Private Key
  • Shop ID

  1. Login into your into your Shopee Open Platform account by going to https://open.shopee.com/login. If you do not have an account, please register for one.
  2. Create your own app by going to Console > Create an App. Fill in App Name as QlicknPay and the other details according to your preferences.
  3. Wait until Shopee approved your APP registration. Once your APP has been approved by Shopee, you can retrieve your Partner ID and Private Key at Overview Console page
  4. Link your console into your Shopee Seller account by logging in into your Shopee account at https://seller.shopee.com.my/account/signin and go to My Account page. Edit your Partner Platform and enter your Partner ID and Partner Key (Private Key).
  5. Retrieve your Shop ID by going back to your Shopee Open Platform > Shop List. Enter your Partner ID, Private Key and Shop ID here.

BNPL

How to enable your Buy Now Pay Later (BNPL) payment method.

Login to your account. Go to https://www.QlicknPay.com/merchant/v-login and log into main page.

Go to API Management

After successfully login into your account, On the left sidebar, click on ‘API Management’. Refer picture below.

Find BNPL Section

Scroll down the page until you see the ‘Buy Now Pay Later Payment (BNPL)’ section. Click on the checkbox provided.

Enter your BNPL Merchant ID and BNPL API Key. Then, click ‘Update BNPL’

BNPL is now available

Your BNPL payment method is now available on your checkout pages.

2C2P eWallet

How to enable your 2C2P eWallet payment method.

Log in to your 2C2P Client Dashboard (Given by the 2C2P Support Team Link: https://client.2c2p.com/2.0/Login)

Go to OPTIONS

At the top of the pages, click on OPTIONS's button.

Copy your Merchant ID and Merchant Keys (Secret Key)

Scroll down a bit and you will see your Merchant ID at MERCHANT INFORMATION section. For Secret Key, scroll down a bit more until you see MERCHANT KEYS (SECRET KEYS). Current Merchant Authentication Key is your Secret Key. Copy both information.

Go to API Management Settings

Login into your Betterpay Merchant Dashboard (Login here). On the left sidebar, click on 'API Management'. You will redirect into 'API Management' pages.

Paste 2C2P Merchant ID and 2C2P Secret Key

Scroll down until you see 2C2P eWallet / Credit Card / Global Card > Tick on the checkbox beside the '2C2P eWallet (Disable)' text > Paste your 2C2P Merchant ID and 2C2P Secret Key.

Choose your type of eWallet

Scroll down a bit and tick on the eWallet / Global Card > Choose your eWallet (Depend on what you have registered with 2C2P) > Click on 'Update 2C2P eWallet'.

Your eWallet Payment is now available

Do a sample payment and eWallet payment options will be display in your checkout page.

 

Standard Payment Gateway

This feature will redirect your payer to QlicknPay checkout page. You payer can then select the different payment options provided.

*This API does not return any respond. Please use this API endpoint to send your customer directly to our checkout page including with the others data by using POST method.

API Endpoint URLs

Requirement to Use the API

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

  • Merchant ID
  • API Key

You can retrieve this information at API Management page.

How to send a Payment Request?

Kindly ensure the payment request you send to either of the above mentioned endpoints comply to the following format using POST method. You can set fields with OPTIONAL tag to NULL or exclude it entirely if it is not required.

Required Arguments

Example request:

      
Please select PHP to view the sample code

    





<?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 = 'R1005'; // Your Merchant ID. You can obtain your Merchant ID in your Merchant Admin Portal and click on API Management.
$api = 'APIKEY100001'; // Your API Key. You can obtain your API Key in your Merchant Admin Portal and click on API Management.
$api_endpoint = '{{API Endpoint URL}}'; // Your API Key. You can obtain your API Key in your Merchant Admin Portal and click on API Management.


#If the form data has been submitted.
if(@$_POST != NULL)
{
    $data_request = array();
    #Sort all of your send parameter (parameter's name) into alphabets order (except 'hash' parameter)
    foreach($_POST as $key => $value)
    {
        $data_request[$key] = $value;
    }
    #Use 'ksort' feature to sort the array in alphabets order.
    ksort($data_request);
    $hash_string = "";
    #Convert all the data that has been sort into a single string and remove all spaces.
    foreach($data_request as $key => $value)
    {
      $hash_string .= $value;
    }
    $hash_string = str_replace(' ', '', $hash_string);
    #Encrypt the string of the data by using HMAC encryption method by using your API Key.
    $data_request['hash'] = hash_hmac('sha256', $hash_string, $api);
}
else
{
    #Below is a sample required data need to send to the given API endpoint. You can add another Optional Parameters (if needed).
    $form = array(
        #Your Merchant ID. You can obtain your Merchant ID in your Merchant Admin Portal and click on API Management.
        "Merchant ID" =>
            array(
                "name" => "merchant_id",
                "type" => "text",
                "default" => $merchant_id,
            ),
        "Invoice No" =>
        #Your Unique invoice number.
            array(
                "name" => "invoice",
                "type" => "text",
                "default" => "INV".rand(10000,99999),
            ),
        "Amount" =>
        #Final amount to be paid
            array(
                "name" => "amount",
                "type" => "text",
                "default" => "1.50",
            ),
        "Payment Desc" =>
        #Purpose of payment
            array(
                "name" => "payment_desc",
                "type" => "text",
                "default" => "Sample payment from Shahrul",
            ),
        "Currency" =>
        #Currency of payment
            array(
                "name" => "currency",
                "type" => "text",
                "default" => "MYR",
            ),
}
?>

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <!-- Bootstrap for a better design -->
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
  <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js"></script>
</head>
<body>
<?php
# Sending all data to the API endpoint by using POST method
if(@$_POST != NULL)
{
    ?>

    <form method='POST' action='<?= $api_endpoint ?>' id='form_request'>
        <?php
        foreach($data_request as $key => $value)
        {
            ?>
            <input type='text' value='<?= $value ?>' name='<?= $key ?>'>
            <?php
        }
        ?>
    </form>
    <script>
        <?php
        # Auto submit form. You can remove this line to view the data (if needed) before send to the API endpoint.
        ?>
        document.getElementById('form_request').submit();
    </script>
    <?php
}
else
{
# List all form data before submit to the API. You can input your own data here.
    ?>

    <div class="container">
        <h2>BPLITE (Standard Payment)</h2>
        <form action="" method="POST">
            <?php
            
            foreach($form as $key => $value)
            {
                ?>
            
                <div class="form-group">
                    <label for="email"><?= $key ?>:</label>
                    <input type="<?= $value['type'] ?>" class="form-control" name="<?= $value['name'] ?>" value="<?= $value['default'] ?>">
                </div>
            
                <?php
            }
            
            ?>

            <button type="submit" class="btn btn-default">Submit</button>
        </form>
    </div>
    <?php
}
?>

</body> 
</html>

Response (200):

      
# Directly to Payment Gateway.

    
      
# Directly to Payment Gateway.

Response (400):

      
# Invalid format data entered

    
      
# Invalid format data entered

Response (401):

      
# Invalid Merchant ID or API Key

    
      
# Invalid Merchant ID or API Key
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
amount Final amount to be paid by buyer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE:250
payment_desc Purpose of payment
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
  • Length: Max 1000 characters.
TYPE: STRING
EXAMPLE:PARKING FEE
currency Currency of payment
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
  • 'THB' is for Thailand Currency
  • 'PHP' is for Philippines Currency
TYPE: STRING
EXAMPLE:MYR
buyer_name Buyer's name
  • Accept only alphabets
TYPE: STRING
EXAMPLE:JOHN
buyer_email Buyer's email. Buyer will receive payment notification at this address if specified
  • Accept only valid email address
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
phone Buyer's phone number
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
hash The secure hash string to validate the payment request sent to our Payment Gateway. Refer here on how to generate your hash verification.
  • Accept only alphabets
TYPE: STRING

Optional Arguments

Parameter Description
add_line_1 Buyer's address line 1
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
add_line_2 Buyer's address line 2
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
postcode Buyer's postcode
  • Accept only digits
TYPE: INTEGER
EXAMPLE:47810
city Buyer's city location
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:PETALING JAYA
comment Buyer's additional comments / notes on the purchase
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
callback_url_fe_succ 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
callback_url_fe_fail 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_FAILURE
baggage_variable If you required a variable that provide the same value after transaction has been made, use this baggage form. You can have more than one variable.
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your bagages variable name* Your value(s) of each variable(s). Must be synchonize with the total number of variable above
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VALUE1

API Errors Guide

The API will return error messages if any of the variables sent is invalid.

Error Messages Issue
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 (B2C) and more than RM1.50. Amount must be more than or equal to RM 1.50 and less than RM 30,000 (B2C).
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 the merchant about this error. Invalid API. Your API key must be less than 14 characters.
Invalid data entered. Validation errors / Hashing variables do not match the data entered.
Invalid URL variable specified. Please inform the merchant about this error. Your callback_url_be host name is not the same host name as Callback URL specified in your API Management setting. To solve this problem, do these steps:
    1. Set to null the value of callback_url_be variable OR
    2. Specify the same host name for both callback_url_be and in your API Management setting.
    Example: callback_url_be:
    www.hostname.com/callbackv1
    API Management setting:
    www.hostname.com/sub/sub2/callbackv2
Invalid name of baggages. Please inform to the merchant about this error. Invalid baggages name. Baggages name cannot same as other variables(required/optional fields) name.
Example: 'merchant_id'
Your Invoice number is too long. Invoice number must be less than or equal to 14 characters. Please inform to the merchant about this error. Your invoice 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.
Example: '-'
Invalid invoice or duplicated invoice entered. Please inform to the merchant about this error. Invoice number must be unique for each transaction initiated.
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 is not specified in the API Management setting.

 

Direct Payment Gateway

Use this feature if you would like to bypass QlicknPay checkout page, and direct payers straight from your system to the selected payment gateway (FPX) seamlessly. This is useful for developers who want to customize the full payment experience on their own website or mobile app and direct the payers to their Internet Banking login page.

API Endpoint URLs

Requirement to Use the API

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

  • Merchant ID
  • API Key

You can retrieve this information at API Management page.

How to send a Payment Request?

Kindly ensure the payment request you send to either of the above mentioned endpoints comply to the following format using POST method. You can set fields with OPTIONAL tag to NULL or exclude it entirely if it is not required.

Required Arguments

Example request:

      
curl POST {Endpoint URL}\
        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"R1017","invoice":"INV01","amount":"2.00","payment_desc":"Sample payment description","currency":"MYR","buyer_name":"John","buyer_email":"john@email.com","phone":"601731233321","add_line_1":"Address line 1","add_line_2":"Address line 2","postcode":"41000","city":"Petaling Jaya","comment":"Sample comment from payer","callback_url_be":"https://domain.com/callback","callback_url_fe_succ":"https://domain.com/return/success","callback_url_fe_fail":"https://domain.com/return/fail","bank_code":"creditAN","respond":"1","skip_receipt":"0","hostedCard":"true","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$data_request = array(
                    'merchant_id' => 'R1017',
                        'invoice' => 'INV01',
                        'amount' => '2.00',
                        'payment_desc' => 'Sample payment description',
                        'currency' => 'MYR',
                        'buyer_name' => 'John',
                        'buyer_email' => 'john@email.com',
                        'phone' => '601731233321',
                        'add_line_1' => 'Address line 1',
                        'add_line_2' => 'Address line 2',
                        'postcode' => '41000',
                        'city' => 'Petaling Jaya',
                        'comment' => 'Sample comment from payer',
                        'callback_url_be' => 'https://domain.com/callback',
                        'callback_url_fe_succ' => 'https://domain.com/return/success',
                        'callback_url_fe_fail' => 'https://domain.com/return/fail',
                        'bank_code' => 'creditAN',
                        'respond' => '1',
                        'skip_receipt' => '0',
                        'hostedCard' => 'true',
                        'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                    );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)

Response (200):

    
{
    "response": "00",
    "merchant_id": "R1017",
    "invoice": "INV01",
    "amount": "2.00",
    "payment_desc": "Sample payment description",
    "buyer_name": "John",
    "buyer_email": "john@email.com",
    "phone": "601731233321",
    "add_line_1": "Address line 1",
    "add_line_2": "Address line 2",
    "postcode": "41000",
    "city": "Petaling Jaya",
    "comment": "Sample comment from payer",
    "payment_url": "https://www.demo.betterpay.me/s?dR1017-INV01-111748-dXc",
} 


    
      
{
    "response": "00",
    "merchant_id": "R1017",
    "invoice": "INV01",
    "amount": "2.00",
    "payment_desc": "Sample payment description",
    "buyer_name": "John",
    "buyer_email": "john@email.com",
    "phone": "601731233321",
    "add_line_1": "Address line 1",
    "add_line_2": "Address line 2",
    "postcode": "41000",
    "city": "Petaling Jaya",
    "comment": "Sample comment from payer",
    "payment_url": "https://www.demo.betterpay.me/s?dR1017-INV01-111748-dXc",
}
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error.
TYPE: INTEGER
EXAMPLE: 10001
invoice Unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 14 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE:INV0001
amount Final amount to be paid by buyer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE:250
payment_desc Purpose of payment
  • Accept ONLY alphabets and numbers
  • Exclamation mark (!) is not accepted
  • Length: Max 1000 characters.
TYPE: STRING
EXAMPLE:PARKING FEE
currency Currency of payment
  • 'MYR' is for Malaysia Currency
  • 'SGD' is for Singapore Currency
  • 'IDR' is for Indonesia Currency
  • 'THB' is for Thailand Currency
  • 'PHP' is for Philippines Currency
TYPE: STRING
EXAMPLE:MYR
buyer_name Buyer's name
  • Accept only alphabets
TYPE: STRING
EXAMPLE:JOHN
buyer_email Buyer's email. Buyer will receive payment notification at this address if specified
  • Accept only valid email address
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
phone Buyer's phone number
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
bank_code Payment channel code / Bank code. You can retrieve bank code by calling Get Payment Channels API.
  • Accept only digits and (+) symbol
TYPE: STRING
EXAMPLE:+60171234567
hash The secure hash string to validate the payment request sent to our Payment Gateway. Refer here on how to generate your hash verification.
  • Accept only alphabets
TYPE: STRING

Compulsory Arguments (For Credit/Debit Card and BNPL payment channel)

Parameter Description
hostedCard Set this value to 'true'. Allowing customer to enter credit card details at payment provider's system.
  • Accept only 'true' as a parameter's value
TYPE: STRING
EXAMPLE: true

Optional Arguments

Parameter Description
respond Enable or disable response data from the API. By default, an API will directly send the payer once the API is called (By using the Form POST method).

Set this value into '1' will return the response data from the API in JSON format including the URL variable called 'payment_url'. This 'payment_url' will send directly the payer to the payment portal.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 1
add_line_1 Buyer's address line 1
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
add_line_2 Buyer's address line 2
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
postcode Buyer's postcode
  • Accept only digits
TYPE: INTEGER
EXAMPLE:47810
city Buyer's city location
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:PETALING JAYA
comment Buyer's additional comments / notes on the purchase
  • Accept only alphanumerics characters
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • Default value of this field is the URL specified API Management page
  • The default value will be ignored if this field is specified
  • Send through HTTPS header. For port customization endpoint, please contact our support.
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
callback_url_fe_succ 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
callback_url_fe_fail 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
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_FAILURE
baggage_variable If you required a variable that provide the same value after transaction has been made, use this baggage form. You can have more than one variable.
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VARIABLE1|VARIABLE2
*Each of your bagages variable name* Your value(s) of each variable(s). Must be synchonize with the total number of variable above
  • Accepts only alphanumeric characters
  • Length: Not more than 5000 characters
  • Must be separated with a pipe character (|) without spaces in between.
TYPE: STRING
EXAMPLE:VALUE1

Collection Payment Link API

This API allow you to create a single Payment Link and do a multiple collection.

API Endpoint URLs

Required Arguments

Example request:

        
            
curl POST {Endpoint URL}\
            -d merchant_id: R1001\
            -d purpose: Annual Payment\
            -d amount: 1.50\
            -d delivery_option: 0\
            -d amount_option: Fixed\
            -d due_date: 2024-04-20\
            -d usage: 1\
            -d max_collection: 100.00\
            -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
            
 
        
    
        
            
 $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&purpose=Annual Payment&amount=1.50
                                &delivery_option=0&amount_option=Fixed&due_date=2024-04-20                                &usage=1&max_collection=100.00&hash=fc85b97551f5a2b8bf28d916f2f8055d");
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                $server_output = curl_exec($ch);
                curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
purpose Description of the payment link. Must be a unique
  • Accept only numbers, alphabets and spaces
  • Not more than 200 characters
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
amount_option Type of amount for payment link. Only accept a fixed or flexi amount
  • The value is "Fixed" or "Unfixed" only
  • Fixed. Customer unable to change the payment link amount
  • Unfixed. Customer able to enter their own amount.
TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed"
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
  • Must be more than RM1.50
TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields.
  • Accept ONLY numbers
  • The value is either 0 or 1
  • 0 - Disable delivery form
  • 1 - Enable delivery form
TYPE: INTERGER
EXAMPLE: 0
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
due_date Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE
EXAMPLE: 2024-04-20
usage Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments.
  • The payment link will automatically disable once the maximum total is reached
  • Only accept interger
TYPE: INTERGER
EXAMPLE: 44
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50.
  • The payment link will automatically disable once the maximum amount collection is reached
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
  • Must be more than RM1.50
TYPE: STRING
EXAMPLE: 1500.55

Respond data

The response data after calling the API

Example response:

        
            

                 
                    "data": {
                    "response":"00",
                    "payment_link_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                    "purpose":"Donation for kids",
                    "amount_option": "Fixed",
                    "amount":100,
                    "delivery_option":1,
                    "merchant_id":"R1233"
                    "due_date":"2023-08-02",
                    "usage":8,
                    "max_collection":"6,779"
                    "hash":"fc85b97551f5a2b8bf28d916f2f8055d"
                    } 
                
            

        
    
        
            

                 
                "data": {
                    "response":"00",
                    "payment_link_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                    "purpose":"Donation for kids",
                    "amount_option": "Fixed",
                    "amount":100,
                    "delivery_option":1,
                    "merchant_id":"R1233"
                    "due_date":"2023-08-02",
                    "usage":8,
                    "max_collection":"6,779"
                    "hash":"fc85b97551f5a2b8bf28d916f2f8055d"
                    }
Parameter Description
response
Response code of the status of created Payment Link.
00 - Successfull
99 - Unsuccessfull
TYPE: INTERGER
payment_link_url
Response Unique Url of the created Payment Link.
TYPE: INTERGER
purpose
Description of the payment link. Must be a unique
TYPE: INTERGER
amount_option
Type of amount for payment link. Only accept a fixed or flexi amount.
TYPE: STRING
merchant_id
Your merchant ID
TYPE: STRING
due_date
Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE
usage
Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments. TYPE: INTERGER
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50. TYPE: STRING

Delete Collection Payment Link API

This API allows you to Delete collection of Payment Links.

API Endpoint URLs

Example request:

    
                         
curl POST {Endpoint URL}\
          -d id: 7\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "id=7&merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $server_output = curl_exec($ch);
    curl_close ($ch)
Field Name Description
Id Your Payment link ID. You can get your Payment Link ID by calling List Collection Payment Link API
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: 1
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

    
 "data": {
    "id": "13",
    "merchant_id": "R1001",
    "response": "00",
    "msg": "Success Deleted",
} 

  
    
 "data": {
    "id": "13",
    "merchant_id": "R1001",
    "response": "00",
    "msg": "Success Deleted",
}
Parameter Description
Id
 Your Payment Link ID.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
response Response code of the status of deleted Payment Link.
00 - Successfull
99 - Unsuccessfull
TYPE: STRING
msg Status message of the payemnet link depend on the response code from response.
TYPE: STRING

List Collection Payment Link API

This API allows you to access a list collection of Payment Links.

API Endpoint URLs

Example request:

    
          
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
        
            

            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS,
            "merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d");
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            $server_output = curl_exec($ch);
            curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

        
            


{
    "respon":"00",
    "merchant_id":"R1233",
    "data": [
                {
                "id":17,
                "inv_number":"INV0004",
                "amount_option":"Fixed",
                "amount":3131,
                "delivery_option":0,
                "status":"Active",
                "payment_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                "logo_url":null,
                "qr_url": URL,
                "created_at":"2023-07-28T02:28:17.000000Z",
                "updated_at":"2023-07-28T02:28:17.000000Z",
                "deleted_at":null
                },
            ]
} 

            

        
  
    
        

             
{
    "respon":"00",
    "merchant_id":"R1233",
    "data": [
                {
                "id":17,
                "inv_number":"INV0004",
                "amount_option":"Fixed",
                "amount":3131,
                "delivery_option":0,
                "status":"Active",
                "payment_url":"http://127.0.0.1:8000/payment-link/s/R1233-INV0004",
                "logo_url":null,
                "qr_url": URL,
                "created_at":"2023-07-28T02:28:17.000000Z",
                "updated_at":"2023-07-28T02:28:17.000000Z",
                "deleted_at":null
                },
            ]
}
Parameter Description
merchant_id Your Merchant ID.
TYPE: STRING
Id
 Your Payment Link ID.
TYPE: STRING
inv_number Unique invoice number.
TYPE: STRING
purpose Description of the payment link.
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
amount_option Type of amount option for payment link.
TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed"
TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields.
TYPE: INTERGER
EXAMPLE: 0
logo_url The URL for payment is generated by the system.
TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
qr_url The URL for payment is generated by the system.
TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
usage
Total maximum successful payment are allowed. For example, if this parameter set as '50', means the successful payment accept must be not more than 50 payments. TYPE: INTERGER
max_collection Total maximum amount collection are allowed. For example, if this parameter set as '1000.50', means the total collection for the payment link must be less than RM1,000.50. TYPE: STRING
due_date
Expiry date of the Payment Link.
  • Format is YYYY-MM-DD
TYPE: DATE

Report Collection Payment Link API

This API allows you to access a list collection of Payment Links.

API Endpoint URLs

Example request:

    
          
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          -d date_from: 2023-06-01\
          -d date_to: 2023-07-27\ 
          -d purpose: donation for kids\
          -d status: null\
          -d pay_method: null\
          
 
  
        
            

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d
                                &date=2023-06-01&date_to=2023-07-27
                                &purpose=donation for kids");
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                $server_output = curl_exec($ch);
                curl_close ($ch)
Field Name Description
response Response code of the status of list collection Payment Link. Refer here for description of the payment Link status.
TYPE: STRING
merchant_id Your merchant ID
TYPE: STRING
EXAMPLE: R1001
date_from By default the date will be the date of first transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
date_to By default the date will be the date of last batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
status By default the status will display all the status of the transactions.
TYPE: STRING
EXAMPLE: succes
purpose Description of the payment link. Must be a unique
  • Accept only numbers, alphabets and spaces
  • Not more than 200 characters
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket

Respond data

The response data after calling the API

Example response:

    
 
{
    "response": "00",
    "merchant_id": "R1233",
    "date_from": "2023-07-01",
    "date_to": "2023-08-01",
    "purpose": null,
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "data": [
        {
            "transaction_id": null,
            "total_amount": null,
            "invoice": null,
            "buyer_name": null,
            "buyer_email": null,
            "phone": null,
            "address": null,
            "city": null,
            "state": null,
            "postcode": null,
            "comment": null,
            "status": null,
            "pay_method": null,
            "callback_be": null,
            "currency": null,
            "created_at": "2023-07-10T08:01:03.000000Z"
        }
],
}



  
    
 
    {
    "response": "00",
    "merchant_id": "R1233",
    "date_from": "2023-07-01",
    "date_to": "2023-08-01",
    "purpose": null,
    "data": [
        {
            "transaction_id": null,
            "total_amount": null,
            "invoice": null,
            "buyer_name": null,
            "buyer_email": null,
            "phone": null,
            "address": null,
            "city": null,
            "state": null,
            "postcode": null,
            "comment": null,
            "status": null,
            "pay_method": null,
            "callback_be": null,
            "currency": null,
            "created_at": "2023-07-10T08:01:03.000000Z"
        }
],
}
Parameter Description
response Response code of the status of list collection Payment Link. Refer here for description of the payment Link status.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
Id
 Your Payment Link ID.
TYPE: STRING
date_from By default the date will be the date of first batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
date_to By default the date will be the date of last batch data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd

TYPE: DATE
EXAMPLE: 2024-04-20
purpose Description of the payment link. TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
transaction_id Unique transaction ID generate by Betterpay.
TYPE: INTERGER
amount_option Type of amount option for payment link. TYPE: STRING
EXAMPLE: Fixed
amount Fixed amount for the payment link. This is a conditional parameter and only required if the value of parameter 'amount_option' is "Fixed" TYPE: STRING
EXAMPLE: 100.55
delivery_option Allow checkout page to display the delivery form as mandatory fields. TYPE: INTERGER
EXAMPLE: 0
buyer_name Description of the payment link. TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
phone Buyer's phone number TYPE: STRING
EXAMPLE: 017-86331311
address Buyer's address
TYPE: STRING
EXAMPLE: LOT 12, Taman Jaya
city Buyer's city
TYPE: STRING
EXAMPLE: kOTA BHARU
state Buyer's state
TYPE: STRING
EXAMPLE: KELANTAN
postcode Buyer's postcode
TYPE: INTERGER
EXAMPLE: 160000
comment Buyer's additional comments / notes on the purchase TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
status By default the status will display all the status of the transactions.
TYPE: STRING
EXAMPLE: OMMENT HERE FOR MERCHANT REFERENCE
callback_be Description of callback TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
currency Currency of payment
TYPE: STRING
EXAMPLE: MYR
created_at Date of the transaction being make TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
logo_url The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
qr_url The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
created_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
updated_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004
deleted_at The URL for payment is generated by the system. TYPE: STRING
EXAMPLE: http://127.0.0.1:8000/payment-link/s/R1233-INV0004

How to receive the Payment Request response (via callback)?

The response to your payment request will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your payer complete or cancel a transaction.

Sample response:

      
{
    "bp_lite_trx_id": "1808241535340347",
    "merchant_id": "R10001",
    "invoice_no": "INV10154632",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "192.00",
    "pay_method": "online_banking",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

    
      
{
    "bp_lite_trx_id": "1808241535340347",
    "merchant_id": "R10001",
    "invoice_no": "INV10154632",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "192.00",
    "pay_method": "online_banking",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}
Parameter Description
bp_lite_trx_id
 Unique transaction ID. You can use this Transaction ID to track the transaction in QlicknPay's portal.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
invoice_no Unique invoice number.
TYPE: STRING
txn_status Response code of the status of payment. Refer here for description of the transaction status.
TYPE: STRING
msg Status message of the payment depend on the response code from txn_status.
TYPE: STRING
txn_amount Final amount paid by buyer.
TYPE: STRING
pay_method Payment method chosen by buyer. Eg: online_banking/card/ewallet/bnpl
TYPE: STRING
hash Secure hash string to validate the response sent to your side by our Payment Gateway. Refer here on how to generate your hash verification.
TYPE: STRING

When Receiving Payment Response

Field Name Example Value
bp_lite_trx_id 1808241535340347
merchant_id R10005
invoice_no INV1001
txn_status 00
msg success
txn_amount 1.50
pay_method online_banking
hash dc8e364d222d6025cbc505674b701asdw

Use Hashing Guide method (refer here) on how to generate your hash value.

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





Get Payment Channels

This API return list of payment channels. You must use the payment channel returned by this API in order to use the Direct Payment API.

API Endpoint URLs

Required Arguments

Example request:

    
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

    
 "data": {
      {
        "status": 1,
        "type": "BNPL",
        "value": "IOUPay-PW",
        "display_name": "IOUPay",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/ioupay_120.gif",
        "currencies": 
          {
                "MYR"
          }
      },
      {
        "status": 1,
        "type": "CC",
        "value": "CREDIT",
        "display_name": "Visa/Mastercard (Local)",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/visa-master.gif",
        "currencies": 
          {
                "MYR"
          }
      },
      {
        "status": 1,
        "type": "IB",
        "value": "FPX_ABB",
        "display_name": "Affin Bank (FPX)",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/FPX_ABB_120.gif",
        "currencies": 
          {
                "MYR"
          }
      },
} 

...


  
    
 "data": {
      {
        "status": 1,
        "type": "BNPL",
        "value": "IOUPay-PW",
        "display_name": "IOUPay",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/ioupay_120.gif",
        "currencies": 
          {
                "MYR"
          }
      },
      {
        "status": 1,
        "type": "CC",
        "value": "CREDIT",
        "display_name": "Visa/Mastercard (Local)",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/visa-master.gif",
        "currencies": 
          {
                "MYR"
          }
      },
      {
        "status": 1,
        "type": "IB",
        "value": "FPX_ABB",
        "display_name": "Affin Bank (FPX)",
        "logo_url": "https://d2x73ruoixi2ei.cloudfront.net/images/logos/channels/120/FPX_ABB_120.gif",
        "currencies": 
          {
                "MYR"
          }
      },
} 

...
Parameter Description
status Current status of the payment channel.
0 - Offline
1 - Online
TYPE: INTEGEER
type Type of the payment channel.
IB - Online Banking
CC - Credit Card
EW - eWallet
BNPL - Buy Now Pay Later
TYPE: STRING
value Payment channel code / Bank Code
TYPE: STRING
display_name Name of the payment channel
TYPE: STRING
logo_url Image of the payment channel
TYPE: STRING
currencies Supported currencies for each payment channel
TYPE: STRING

Get Payment Status

In the unlikely event that the payment network does not automatically notify the merchant regarding customer's payment status, use this API to manually query the transaction. This feature enables the merchant to retrieve their transaction status by sending a request direct to the bank or payment provider network. You may use this to send an enquiry request the payment status.

API Endpoint URLs

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: R1001\
          -d invoice: INV94238\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=R1001&invoice=INV94238&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
invoice Your invoice number
  • Accept only numbers and alphabets
TYPE: STRING
EXAMPLE: INV94238
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

    
 "data": {
    "bp_lite_trx_id": "1162404219",
    "merchant_id": "R1001",
    "invoice_no": "INV94238",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "200.00",
    "pay_method": "online_banking"
} 

  
    
 "data": {
    "bp_lite_trx_id": "1162404219",
    "merchant_id": "R1001",
    "invoice_no": "INV94238",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "200.00",
    "pay_method": "online_banking"
}
Parameter Description
bp_lite_trx_id
 Unique transaction ID. You can use this Transaction ID to track the transaction in QlicknPay's portal.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
invoice_no Unique invoice number.
TYPE: STRING
txn_status Response code of the status of payment. Refer here for description of the transaction status.
TYPE: STRING
msg Status message of the payment depend on the response code from txn_status.
TYPE: STRING
txn_amount Final amount paid by buyer.
TYPE: STRING
pay_method Payment method chosen by buyer. Eg: online_banking/card/ewallet/bnpl
TYPE: STRING

Recurring Payment - Credit/Debit Card

Recurring payments are automated payments that are carried out periodically (monthly), of those consumption charges of goods or services such as memberships, subscriptions, policies or receipts with fixed value; that were previously authorized by the customer.

Recurring payments happen in the background. Authorization or Enrollment is done one via E-Mandate. The customer goes through the payment steps only once, for the first payment that will be charged RM1.00.

In the following sections we explain the following APIs.

  • Create subscription package
  • Adding new subscribers by referring to available subscriptions
  • Modify subscribers agreement or terminate subscription
  • View your current subscription package and subscribers

You must create/add subscription package before you can add subscribers

Add subscriptions

QlicknPay allows flexibility for merchants to create subscription models for their business. We provide 3 different subscription types:

Fixed : Merchants that charges the same amount every billing period - e.g Gym Membership
Flexi : Allow subscribers to determine bill amount - e.g. Donation
Calculated : Merchants that offer Tiering amount according to expiry date - e.g. Hire Purchase

API Endpoint URLs

Required Arguments (Add Subscriptions)

Example request (Add New Fixed Subscription Package):

    
curl POST {Endpoint URL}\
      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","subscription_type":"fixed","subscription_id":"CALC001","name":"Monthly Subs","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d","repayment_periods":{{"totalMonth":"2","amount":"105.00"}}'\

      

  
    
$data_request = array(
        'merchant_id' => '10010',
        'subscription_type' => 'fixed',
        'subscription_id' => 'CALC001',
        'name' => 'Monthly Subs',
        'purpose' => 'Music Subscription',
        'repayment_periods' =>
            array(
              'totalMonth' => '2',
              'amount' => '105.00',
              ),
        'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
      );

    $fields_string = json_encode($data_request);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                $fields_string);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response for Fixed subsciption (200):

    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "fixed",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "amount": "105.00"
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

  
    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "fixed",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "amount": "105.00"
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

Example request (Add New Flexi Subscription Package):

    
curl POST {Endpoint URL}\
      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","subscription_type":"flexi","subscription_id":"CALC002","name":"Monthly Subs","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d","repayment_periods":{{"totalMonth":"","amount":"105.00"}}'\

      

  
    
$data_request = array(
        'merchant_id' => '10010',
        'subscription_type' => 'flexi',
        'subscription_id' => 'CALC002',
        'name' => 'Monthly Subs',
        'purpose' => 'Music Subscription',
        'repayment_periods' =>
            array(
              'totalMonth' => '',
              'amount' => '105.00',
              ),
        'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
      );

    $fields_string = json_encode($data_request);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                $fields_string);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response for Flexi subscription (200):

    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC002",
    "subscription_type": "flexi",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "amount": "105.00"
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

  
    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC002",
    "subscription_type": "flexi",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "amount": "105.00"
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

Example request (Add New Flexi Subscription Package):

    
curl POST {Endpoint URL}\
      -H 'Content-Type: application/json'\
      -d '{"merchant_id":"10010","subscription_type":"calculated","subscription_id":"CALC003","name":"Monthly Subs","purpose":"Music Subscription","hash":"fc85b97551f5a2b8bf28d916f2f8055d","repayment_periods":{{"totalMonth":"3","amount":"105.00"},{"totalMonth":"5","amount":"70.00"}}'\

      

  
    
$data_request = array(
        'merchant_id' => '10010',
        'subscription_type' => 'calculated',
        'subscription_id' => 'CALC003',
        'name' => 'Monthly Subs',
        'purpose' => 'Music Subscription',
        'repayment_periods' =>
            array ( 
              1 => 
              array(
                'totalMonth' => '3',
                'amount' => '105.00',
                ),
              2 => 
              array(
                'totalMonth' => '5',
                'amount' => '70.00',
                ),
              )
        'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
      );

    $fields_string = json_encode($data_request);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                $fields_string);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Response for Flexi subscription (200):

    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "flexi",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "1": {
            "total": "3",
            "terms": "Month",
            "amount": "105.00"
        },
        "2": {
            "total": "5",
            "terms": "Month",
            "amount": "70.00"
        }
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}

  
    
{
    "system_subscription_id": "80",
    "subscription_id": "CALC001",
    "subscription_type": "flexi",
    "name": "Monthly Subs",
    "terms": "Monthly",
    "purpose": "Music Subscription",
    "repayment_periods": {
        "1": {
            "total": "3",
            "terms": "Month",
            "amount": "105.00"
        },
        "2": {
            "total": "5",
            "terms": "Month",
            "amount": "70.00"
        }
    },
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscription_type Your type of subscription package. Use 'fixed' if your need a fixed amount for subscription OR choose 'flexi' if you need your payer specify their own amount OR choose 'calculated' if the subscription have multiple option of fixed amount

*Expiry date is the last date of the payment. Otherwise, the subscription is keep going until subscribers decide to terminated the subscription.
  • Only 'fixed', 'flexi' OR 'calculated' are accepted
TYPE: STRING
EXAMPLE: fixed
subscription_id Unique ID for your subscription package
  • Accept alphabets and numbers only.
  • Length: Max 18 characters.
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED001
name Name of your subscription
  • Accept alphanumeric.
  • Length: Max 50 characters.
TYPE: STRING
EXAMPLE: Monthly Subscription
purpose Short description of the subscription
  • Accept alphanumeric.
  • Length: Max 27 characters.
TYPE: STRING
EXAMPLE: Music Subscription 1
repayment_periods: {
  totalMonth : 'value'
} 		Total month of subscription. (Example: If the value is '2' then the subscription is only for 2 months)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 5
{
  amount : 'value'
} 		Repayment period amount. This is not a total amount but an amount for each terms that has specified. (Example: If the value is '20.00' then the subscription is RM20.00 for each month)
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 20.00
TYPE: STRING
EXAMPLE: 20.00
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Parameter Description
system_subscription_id
 Unique transaction ID generate by Betterpay.
TYPE: STRING
subscription_id Unique ID for your subscription package.
TYPE: STRING
subscription_type Your type of subscription package.
TYPE: STRING
name Name of your subscription.
TYPE: STRING
terms Subscription frequency.
TYPE: STRING
purpose Short description of the subscription.
TYPE: STRING
repayment_periods :
{ total } 		Total month of subscription
TYPE: STRING
repayment_periods :
{ terms } 		Subscription frequency.
TYPE: STRING
repayment_periods :
{ amount } 		Repayment period amount per month
TYPE: STRING
created Date and time of the subscription created
TYPE: STRING
modified Date and time of the subscription modified
TYPE: STRING
paymentURL URL for subscriber to verify their credit card. If you provide this URL to your subscribers, you can skip 'Add Subscriber' API (Optional).
TYPE: STRING

Add subscriber

API Endpoint URLs

Required Arguments (Add Subscribers)

Example request (Add New Subscribers for Fixed Package):

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_id":"TESTID123","hash":"fc85b97551f5a2b8bf28d916f2f8055d","subscriber_details":{{"id_number":"960547015374"},{"id_type":"1"},{"reference_no":"101"},{"email":"john@domain.com"},{"name":"Shahrul Izwan"},{"phone":"0173649558"},"repayment_periods":{[{"totalMonth":"2"},{"amount":"2.00"}]}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'subscriber_details' =>
           array(
               'id_number' => '960547015374',
               'id_type' => '1',
               'reference_no' => '101',
               'email' => 'john@domain.com',
               'name' => 'Shahrul Izwan',
               'phone' => '0173649558',
            ),
          'subscription_id' => 'TESTID123',
          'repayment_periods' =>
           array(
               0 => 
               array(
                'totalMonth' => "2",
                'amount' => "2.00",
               ),
            ),
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscriber_details: {id_number:value} Payer ID Number (Ex: IC Number)
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 950711251499
subscriber_details: {id_type:value} ID Number Type
  • Accept only either '1', '2', '3' or '4'
  • 1 - New IC Number
  • 2 - Old IC Number
  • 3 - Passport Number
  • 4 - Business Registration
  • 5 - Others
TYPE: INTEGER
EXAMPLE: 1
subscriber_details: {name:value} Subscribers full name
  • Accept alphabets and empty space only
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
subscriber_details: {reference_no:value} Your reference no
  • Accept only number with no empty spaces. Maximum 12 characters
TYPE: INTEGER
EXAMPLE: 101
subscriber_details: {name:email} Subscriber's email
  • Must be valid email address
TYPE: STRING
EXAMPLE: john@domain.com
subscriber_details: {name:value} Subscriber's full name
  • Accept alphabets and empty space only
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
subscriber_details: {phone:value} Subscriber's phone number
TYPE: STRING
EXAMPLE: 60123456789
subscription_id Your subscription ID. Must created your subscription package to retrieved your subscription ID
  • Alphanumerics
TYPE: STRING
EXAMPLE: TESTID123
repayment_periods: [{totalMonth:value}] Total amount of month need to subscribe. Must be same as subscription that you have created.
TYPE: STRING
EXAMPLE: 2
repayment_periods: [{amount:value}] Total amount per month. Must be same as subscription that you have created.
TYPE: STRING
EXAMPLE: 100.50
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

Response (200):

      
{
    "response": "00",
    "system_subscriber_id": "80",
    "subscription_id": "TESTID123",
    "subscriber_details": {
        "reference_no": "101"
    },
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentUrl": "https://www.demo.betterpay.me/merchant/api/recurring/v1/bplite/enroll?C2221RS4177"
}

    
      
{
    "response": "00",
    "system_subscriber_id": "80",
    "subscription_id": "TESTID123",
    "subscriber_details": {
        "reference_no": "101"
    },
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
    "created": "2021-03-26 12:40:34",
    "modified": "2021-03-26 12:40:34",
    "paymentUrl": "https://www.demo.betterpay.me/merchant/api/recurring/v1/bplite/enroll?C2221RS4177"
}
Parameter Description
response
 Response status of the request. '00' means the API request is successful. Otherwise, the API request is failed.
TYPE: STRING
system_subscriber_id
 System generated subscriber ID. Use this ID to retrieve subscriber details by using Get Subscriber Details API.
TYPE: STRING
subscriber_details: {name}
 Name of subscriber
TYPE: STRING
subscriber_details: {id_type}
 Type of ID Number
TYPE: STRING
subscriber_details: {id_number}
 Subscriber's ID Number
TYPE: STRING
subscriber_details: {phone}
 Subscriber's Phone Number
TYPE: STRING
subscriber_details: {email}
 Subscriber's Email Address
TYPE: STRING
subscriber_details: {reference_no}
 Subscriber's Reference Number
TYPE: STRING
hash
 Your previous hash verification
TYPE: STRING
created
 Date and time of the subscription created
TYPE: STRING
modified
 Date and time of the subscription modified
TYPE: STRING
paymentUrl
 Payment URL for subscriber to verify their credit card.
TYPE: STRING

Callback Response (New Subscriber)

For every new subscriber registered, you will received callback data sent to your Callback Endpoint. Follow these steps on how to specify your callback endpoint:

  • Login to your Betterpay Dashboard
  • Under Recuring at your left sidebar, click on Settings
  • Click on Callback URL tab
  • Enter your Callback URL and click on Save button

Respond data

The response data your will received for each subscriber that succesful verify their credit card.

Example response:

    
{
    "bp_lite_trx_id": "2208081819000000",
    "merchant_id": "R1001",
    "invoice_no": "INV94238",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "1.00",
    "pay_method": "card",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
} 

  
    
{
    "bp_lite_trx_id": "2208081819000000",
    "merchant_id": "R1001",
    "invoice_no": "INV94238",
    "txn_status": "00",
    "msg": "success",
    "txn_amount": "1.00",
    "pay_method": "card",
    "hash": "fc85b97551f5a2b8bf28d916f2f8055d",
}
Parameter Description
bp_lite_trx_id
 Unique transaction ID. You can use this Transaction ID to track the transaction in QlicknPay's portal.
TYPE: STRING
merchant_id Your Merchant ID.
TYPE: STRING
invoice_no Unique invoice number.
TYPE: STRING
txn_status Response code of the status of payment. Refer here for description of the transaction status.
TYPE: STRING
msg Status message of the payment depend on the response code from txn_status.
TYPE: STRING
txn_amount Final amount paid by buyer. For Recurring, the card verification will cost them RM1.00.
TYPE: STRING
pay_method Payment method chosen by buyer.
TYPE: STRING
hash Secure hash string to validate the response sent to your side by our Payment Gateway. Refer here on how to generate your hash verification.
TYPE: STRING

Get All Subscriptions

You can retrieve all registered subscription package data by calling this API.

API Endpoint URLs

Required Arguments

Example request:

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","page":"1","offset":"10","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'page' => '1',
          'offset' => '10',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
page Page of the response data. By default the page is set to number 1.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 2
offset Maximum subscription display for each pages
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 20

Respond data

The response data after calling the API

Example response (200):

    
[
    {
        "total_page_available": 12,
    },
    {
        "response": 00,
    },
    data
    {
      [
        {
          "system_subscription_id": "1626",
          "subscription_id": "CALC001",
          "subscription_type": "fixed",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "2",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
        },

        {
          "system_subscription_id": "1627",
          "subscription_id": "CALC002",
          "subscription_type": "flexi",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
        },

        {
          "system_subscription_id": "1628",
          "subscription_id": "CALC003",
          "subscription_type": "calculated",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
            [
              {
                "total": "3",
                "amount": "105.00",
              },
              {
                "total": "5",
                "amount": "70.00",
              },
            ]
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
        },

      ]
        
    }
    
]


  
    
[
    {
        "total_page_available": 12,
    },
    {
        "response": 00,
    },
    data
    {
      [
        {
          "system_subscription_id": "1626",
          "subscription_id": "CALC001",
          "subscription_type": "fixed",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "2",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
        },

        {
          "system_subscription_id": "1627",
          "subscription_id": "CALC002",
          "subscription_type": "flexi",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
        },

        {
          "system_subscription_id": "1628",
          "subscription_id": "CALC003",
          "subscription_type": "calculated",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
            [
              {
                "total": "3",
                "amount": "105.00",
              },
              {
                "total": "5",
                "amount": "70.00",
              },
            ]
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTy2k",
        },

      ]
        
    }
    
]
Parameter Description
total_page_available
 Total page available for merchant to view
TYPE: STRING
response
 Response status of the request. '00' means the API request is successful. Otherwise, the API request is failed.
TYPE: STRING
data *
 All of the subscription data
TYPE: STRING

Get Single Subscription Data

Get single subscription data

API Endpoint URLs

Required Arguments

Example request:

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_id":"CALC001","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'subscription_id' => 'CALC001',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
subscription_id Unique ID for your subscription package
  • Accept alphabets and numbers only.
  • Length: Max 18 characters.
  • No empty spaces
TYPE: STRING
EXAMPLE: FIXED001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

    
        {
          "system_subscription_id": "1626",
          "subscription_id": "CALC001",
          "subscription_type": "fixed",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "2",
                "terms": "Month",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
        }

  
    
        {
          "system_subscription_id": "1626",
          "subscription_id": "CALC001",
          "subscription_type": "fixed",
          "name": "Monthly Subs",
          "terms": "Monthly",
          "purpose": "Music Subscription",
          "repayment_periods": 
              {
                "total": "2",
                "terms": "Month",
                "amount": "105.00",
              },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
          "paymentURL": "https://www.demo.betterpay.me/merchant/mandate_bplite?em1neTyvk",
        }
Parameter Description
system_subscription_id
 Unique transaction ID generate by Betterpay.
TYPE: STRING
subscription_id Unique ID for your subscription package.
TYPE: STRING
subscription_type Your type of subscription package.
TYPE: STRING
name Name of your subscription.
TYPE: STRING
terms Subscription frequency.
TYPE: STRING
purpose Short description of the subscription.
TYPE: STRING
repayment_periods :
{ total } 		Total month of subscription
TYPE: STRING
repayment_periods :
{ terms } 		Subscription frequency.
TYPE: STRING
repayment_periods :
{ amount } 		Repayment period amount per month
TYPE: STRING
created Date and time of the subscription created
TYPE: STRING
modified Date and time of the subscription modified
TYPE: STRING
paymentURL URL for subscriber to verify their credit card. If you provide this URL to your subscribers, you can skip 'Add Subscriber' API (Optional).
TYPE: STRING

Get All Subscribers

You can retrieve all successful subscribers data by calling this API.

API Endpoint URLs

Required Arguments

Example request:

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","subscription_id":"CALC001","page":"1","offset":"10","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'subscription_id' => 'CALC001',
          'page' => '1',
          'offset' => '10',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: STRING
EXAMPLE: R1001
subscription_id Your Subscription ID
  • Alphanumerics
TYPE: STRING
EXAMPLE: R1001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
page Page of the response data. By default the page is set to number 1.
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 2
offset Maximum subscription display for each pages
  • Accept only numbers
TYPE: INTEGER
EXAMPLE: 20

Respond data

The response data after calling the API

Example response (200):

    
[
    {
        "total_page_available": 12,
    },
    {
        "response": 00,
    },
    data
    {
      [
        {
            "system_subscriber_id": "80",
            "subscription_id": "CALC001",
            "subscriber_details": {
                "name": "Shahrul Izwan",
                "id_type": "1",
                "id_number": "960547015374",
                "phone": "0173649558",
                "email": "john@domain.com",
                "reference_no": "101"
            },
            "created": "2021-03-26 12:40:34",
            "modified": "2021-03-26 12:40:34",
        },
        {
            "system_subscriber_id": "81",
            "subscription_id": "CALC001",
            "subscriber_details": {
                "name": "Farid Akmal",
                "id_type": "1",
                "id_number": "950808015781",
                "phone": "0173649558",
                "email": "farid@domain.com",
                "reference_no": "102"
            },
            "created": "2021-03-26 12:40:34",
            "modified": "2021-03-26 12:40:34",
        },
      ]
        
    }
    
]


  
    
[
    {
        "total_page_available": 12,
    },
    {
        "response": 00,
    },
    data
    {
      [
        {
            "system_subscriber_id": "80",
            "subscription_id": "CALC001",
            "subscriber_details": {
                "name": "Shahrul Izwan",
                "id_type": "1",
                "id_number": "960547015374",
                "phone": "0173649558",
                "email": "john@domain.com",
                "reference_no": "101"
            },
            "created": "2021-03-26 12:40:34",
            "modified": "2021-03-26 12:40:34",
        },
        {
            "system_subscriber_id": "81",
            "subscription_id": "CALC001",
            "subscriber_details": {
                "name": "Farid Akmal",
                "id_type": "1",
                "id_number": "950808015781",
                "phone": "0173649558",
                "email": "farid@domain.com",
                "reference_no": "102"
            },
            "created": "2021-03-26 12:40:34",
            "modified": "2021-03-26 12:40:34",
        },
      ]
        
    }
    
]
Parameter Description
total_page_available
 Total page available for merchant to view
TYPE: STRING
response
 Response status of the request. '00' means the API request is successful. Otherwise, the API request is failed.
TYPE: STRING
data *
 All of the subscribers data
TYPE: STRING

Get Single Subscriber Data

Get single subscriber data

API Endpoint URLs

Required Arguments

Example request:

      
curl POST {Endpoint URL}\

        -H 'Content-Type: application/json'\
        -d '{"merchant_id":"10010","system_subscriber_id":"80","hash":"fc85b97551f5a2b8bf28d916f2f8055d"}'\

        

    
      
$data_request = array(
          'merchant_id' => '10010',
          'system_subscriber_id' => '80',
          'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
        );

      $fields_string = json_encode($data_request);

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
      curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
      curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,
                  $fields_string);

      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $server_output = curl_exec($ch);

      curl_close ($ch)
Parameter Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
system_subscriber_id Unique ID for your subscription package
  • Accept numbers only.
TYPE: STRING
EXAMPLE: 81
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond data

The response data after calling the API

Example response:

    
        {
          "system_subscriber_id": "80",
          "subscription_id": "TESTID123",
          "subscriber_details": {
              "name": "Shahrul Izwan",
              "id_type": "1",
              "id_number": "960547015374",
              "phone": "0173649558",
              "email": "john@domain.com",
              "reference_no": "101"
          },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
      }

  
    
        {
          "system_subscriber_id": "80",
          "subscription_id": "TESTID123",
          "subscriber_details": {
              "name": "Shahrul Izwan",
              "id_type": "1",
              "id_number": "960547015374",
              "phone": "0173649558",
              "email": "john@domain.com",
              "reference_no": "101"
          },
          "created": "2021-03-26 12:40:34",
          "modified": "2021-03-26 12:40:34",
      }
Parameter Description
system_subscriber_id
 System generated subscriber ID. Use this ID to retrieve subscriber details by using Get Subscriber Details API.
TYPE: STRING
subscription_id
 Submitted subscription ID
TYPE: STRING
subscriber_details: {name}
 Name of subscriber
TYPE: STRING
subscriber_details: {id_type}
 Type of ID Number
TYPE: STRING
subscriber_details: {id_number}
 Subscriber's ID Number
TYPE: STRING
subscriber_details: {phone}
 Subscriber's Phone Number
TYPE: STRING
subscriber_details: {email}
 Subscriber's Email Address
TYPE: STRING
subscriber_details: {reference_no}
 Subscriber's Reference Number
TYPE: STRING
created
 Date and time of the subscription created
TYPE: STRING
modified
 Date and time of the subscription modified
TYPE: STRING

Tokenization

This feature allows you to perform card tokenization, and use the token to charge your customer later. This is suitable for subscription or recurring billing use cases.

Tokenization Flow

  1. Create Verification URL for payer.
  2. Redirect payer to Verification URL, Payer performs verification at our checkout pages thus reducing your PCI Compliance as sensitive card data does not need to be captured at your system or ours
  3. Once verification is done, our system will send an email and callback data to your callback URL with the Token ID
  4. You may use the Token ID to initiate a payment by using the Charge Card API.
  5. For every successful payment (by token), please wait 5 minutes before making a new payment with the same token ID.
  6. Use Delete Card API to remove the available token and use the same Verification URL to change or update the card details.

Create Verification URL

Use this API to create Verification URL for your customer. The URL provided will allow your customer to enter their card details for verification purpose. Remember to store the response, as no card details will be stored in QlicknPay's servers.

Below is a Tokenization flow diagram to retrieve the token ID

API Endpoint URLs

Required Arguments

Example request:

     
curl POST {Endpoint URL}\
     -H 'Content-Type: application/json'\
     -d merchant_id: 10010\
     -d reference_id: REFERENCEID01\
     -d callback_url_be: http://www.webina.me/callback\
     -d callback_url_fe_succ: https://webina.me/success\
     -d callback_url_fe_fail: https://webina.me/fail\
     -d skip_receipt: 0\
     -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           

   
     
$data_request = array(
       'merchant_id' => '10010',
       'reference_id' => 'REFERENCEID01',
       'callback_url_be' => 'http://www.webina.me/callback',
       'callback_url_fe_succ' => 'https://webina.me/success',
       'callback_url_fe_fail' => 'https://webina.me/fail',
       'skip_receipt' => '0',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Response (200):

     
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "callback_url_be": "http://www.webina.me/callback",
    "success_url": "https://webina.me/success",
    "fail_url": "https://webina.me/fail",
    "skip_receipt": "0",
    "credit_card_verification_url": "https://www.qlicknpay.com/s?TM39433712887",
    "created": "2021-04-19 12:40:34",
    "modified": "2021-04-19 12:40:34"
}

   
     
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "callback_url_be": "http://www.webina.me/callback",
    "success_url": "https://webina.me/success",
    "fail_url": "https://webina.me/fail",
    "skip_receipt": "0",
    "credit_card_verification_url": "https://www.qlicknpay.com/s?TM39433712887",
    "created": "2021-04-19 12:40:34",
    "modified": "2021-04-19 12:40:34"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
reference_id Your unique reference ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
amount Amount to charge.
  • By default, if the 'amount' variable is omitted, cardholder will not be charged.
  • The default value will be ignored if this field is specified
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format, eg: 192.00
TYPE: STRING
EXAMPLE: 192.50
invoice Unique reference number of this payment
  • This is an optional variable but it will be mandatory if the 'amount' variable is entered.
  • Accept alphanumeric only.
  • Length: Max 20 characters.
TYPE: STRING
EXAMPLE: INV01
callback_url_be Callback URL for your back-end process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
callback_url_fe_succ Callback URL for your front-end successful transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/success
callback_url_fe_fail Callback URL for your front-end failed transaction process
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/fail
skip_receipt Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
  • Accepts only integer
  • Default value is '0'
TYPE: INTEGER
EXAMPLE: 0

How to receive the Credit Card Verification response (via callback)?

The response for Credit Card Verification will be sent back to your specified back-end URL in the following format using POST method. You will receive this response after your customer successfully completed the card verification.

Field Name Example Value
reference_id Your unique reference ID
  • Alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
txn_status Response code of the status of verification.* Refer Response Code table for description.
  • Alphabets and numbers only.
  • Length: Max 2 characters.
TYPE: STRING
EXAMPLE: 00
msg Message status for verification
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: Verification Approved
token Unique ID for Card's Token
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
schemeCard Card scheme
  • Alphabets only.
TYPE: STRING
EXAMPLE: MASTERCARD
fundingMethodCard Card funding method
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: CREDIT
amount Amount of the first payment
  • Numbers only
TYPE: STRING
EXAMPLE: 121.50
invoice Unique invoice number from the first payment
  • Alphabets only.
TYPE: STRING
EXAMPLE: INV01

Charge Card by Using Token

Use this API to charge VISA / MasterCard card with token generated.

Below is a Tokenization flow diagram on how to charge the card by using the token ID provided

API Endpoint URLs

URL Parameters

Required Arguments

Example request (Charge Card):

         
curl POST {Endpoint URL}\

           -H 'Content-Type: application/json'\
           -d merchant_id: 10010\
           -d token: 1474809955578058\
           -d invoice: INV01\
           -d amount: 10.50\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                      

       
         
$data_request = array(
           'merchant_id' => '10010',
           'token' => '1474809955578058',
           'invoice' => 'INV01',
           'amount' => '10.50',
           'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                      );

         $fields_string = json_encode($data_request);

         $ch = curl_init();
         curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
         curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
         curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
         curl_setopt($ch, CURLOPT_POST, 1);
         curl_setopt($ch, CURLOPT_POSTFIELDS,
                     $fields_string);

         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

         $server_output = curl_exec($ch);

         curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
token Token ID that you received from your callback endpoint
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: 1474809955578058
invoice Your unique invoice number
  • Accept alphabets, numbers and some special characters.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV01
amount Final amount to be paid by payer
  • Accept ONLY numbers
  • Must be in 2 decimal places (d.p) format.
  • Must be more than or equal 1.50.
TYPE: STRING
EXAMPLE: 10.50

Optional Argument

This optinal variable is only available in sandbox enviroment.

sandbox_charge_status Charge simulation status. Set '0' for a sample successful charge card. Otherwise, the charge is return as unsuccessful payment.
  • Accept ONLY numbers
  • Default value is '0'
TYPE: INT
EXAMPLE: 0

Respond from Charge Card API

Response (200):

         
{
    "response": "00",
    "txn_status": "00",
    "msg": "Payment Successful",
    "reason": "",
    "error_code": "",
    "invoice": "INV01",
    "amount": "10.50",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "transaction_authorizationCode": "T91898"
}

       
         
{
    "response": "00",
    "txn_status": "00",
    "msg": "Payment Successful",
    "reason": "",
    "error_code": "",
    "invoice": "INV01",
    "amount": "10.50",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "transaction_authorizationCode": "T91898"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
txn_status Status of the transaction
  • 00 - Successful Payment
  • 12 - Failed Payment
TYPE: STRING
EXAMPLE: 00
msg Message status of the transaction

TYPE: STRING
EXAMPLE: Payment Successful
reason Reason of the error. This message received directly from the MPGS. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: Not sufficient funds (INSUFFICIENT_FUNDS)
error_code Error code received from the MPGS. Please refer MPGS Error Code for more explaination of the error. If payment is successful, this variable is empty.

TYPE: STRING
EXAMPLE: 51
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
token Transaction Token ID

TYPE: STRING
EXAMPLE: e3b0c44vcr2e1c1c149afbf4c899
6fb92427ae41esq124334ca4111452b855ved

Delete Card

Use this API to delete the card Token. Once the card token is successfully deleted, you can initiate another verification with the same reference number or same URL provided.

API Endpoint URLs

URL Parameters

Required Arguments

Example request:

            
curl POST {Endpoint URL}\
            -H 'Content-Type: application/json'\
            -d merchant_id: 10010\
            -d token: 1474809955578058\
            -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                         

          
            
$data_request = array(
              'merchant_id' => '10010',
              'token' => '1474809955578058',
              'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                            );

            $fields_string = json_encode($data_request);

            $ch = curl_init();
            curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
            curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
            curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS,
                        $fields_string);

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $server_output = curl_exec($ch);

            curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
token Your unique reference ID or Token ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters for Reference ID and 64 characters for Token ID.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond from Delete Card API

Response (200):

            
{
    "response": "00",
    "msg": "Successfully delete the Token",
    "reference_id": "REFERENCEID01"
}

          
            
{
    "response": "00",
    "msg": "Successfully delete the Token",
    "reference_id": "REFERENCEID01"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
msg Message of request status. TYPE: STRING
EXAMPLE: Successfully delete the Token

Get Available Token

Use this API to get all available Token that you have created. Max display per page is 100 rows.

API Endpoint URLs

Required Arguments

Example request:

             
curl POST {Endpoint URL}\
             -H 'Content-Type: application/json'\
             -d merchant_id: 10010\
             -d date_from: 2021-04-14\
             -d date_to: 2021-04-19\
             -d status: 3\
             -d page: 1\
             -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                           

           
             
$data_request = array(
               'merchant_id' => '10010',
               'date_from' => '2021-04-14',
               'date_to' => '2021-04-19',
               'status' => '3',
               'page' => '1',
               'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                              );

             $fields_string = json_encode($data_request);

             $ch = curl_init();
             curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
             curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
             curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
             curl_setopt($ch, CURLOPT_POST, 1);
             curl_setopt($ch, CURLOPT_POSTFIELDS,
                         $fields_string);

             curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

             $server_output = curl_exec($ch);

             curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the data.
  • Accept only numbers
  • 0 - All failed verification, 1 - All success verification, 2 - Both failed and success verification, 3 - Failed, success and delay verification
TYPE: INTEGER
EXAMPLE: 3
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Respond from Get Avaiable Token API

Response (200):

             
[
     {
         "total_page_available": 1,
     },
     {
         "reference_id": "REFID01",
         "verification_status": "Success",
         "token": "547b946bda42d20a35b6bas19231d3n13ud16f3b2fa04ee73e6c6470b779ec314",
         "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tFKiUY",
         "created": "2021-04-19 10:06:50",
         "modified": "2021-04-19 11:10:25",
     },
     {
       "reference_id": "REFID02",
       "verification_status": "Failed",
       "token": "e3b0c44298fc1c149afbfs12301iw9jfb92427ae41e4649b934ca495991b7852b855",
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tAuI7",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     },
     {
       "reference_id": "REFID03",
       "verification_status": "Delay",
       "token": '',
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tkKSH",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     }
 ]
         

           
             
[
     {
         "total_page_available": 1,
     },
     {
         "reference_id": "REFID01",
         "verification_status": "Success",
         "token": "547b946bda42d20a35b6bas19231d3n13ud16f3b2fa04ee73e6c6470b779ec314",
         "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tFKiUY",
         "created": "2021-04-19 10:06:50",
         "modified": "2021-04-19 11:10:25",
     },
     {
       "reference_id": "REFID02",
       "verification_status": "Failed",
       "token": "e3b0c44298fc1c149afbfs12301iw9jfb92427ae41e4649b934ca495991b7852b855",
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tAuI7",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     },
     {
       "reference_id": "REFID03",
       "verification_status": "Delay",
       "token": '',
       "credit_card_verification_url": "https://www.qlicknpay.com/s?TMzRUT0tkKSH",
       "created": "2021-04-19 13:15:40",
       "modified": "2021-04-19 14:44:10",
     }
 ]
total_page_available Total page available. (Max display per page is 100 rows)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
verification_status Token verification status

TYPE: STRING
EXAMPLE: Success
token Customer's Token ID.

TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
b2fa04ee73e6c6470b779ec314
credit_card_verification_url Card Verification URL. This URL will ask customers to fill up their Credit Card number.

TYPE: STRING
EXAMPLE: https://www.qlicknpay.com/s?TMzRUT0tFKiUY
created Date of Verification Requested

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40
modified Date of Modified

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Token Details

Use this API to retrieve specific token in more details.

API Endpoint URLs

URL Parameters

Required Arguments

Example request (Get Token Details):

              
curl POST {Endpoint URL}\

                -H 'Content-Type: application/json'\
                -d merchant_id: 10010\
                -d reference_id: REFERENCEID01\
                -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                                

            
              
$data_request = array(
                'merchant_id' => '10010',
                'reference_id' => 'REFERENCEID01',
                'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                );

              $fields_string = json_encode($data_request);

              $ch = curl_init();
              curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
              curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
              curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
              curl_setopt($ch, CURLOPT_POST, 1);
              curl_setopt($ch, CURLOPT_POSTFIELDS,
                          $fields_string);

              curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

              $server_output = curl_exec($ch);

              curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10010
reference_id Your unique reference ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: REFERENCEID01
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond from Get Token Details API

Response (200):

              
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "verification_status": "Success",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "callback_url_be": "https:\/\/www.webina.me\/callback",
    "callback_url_fe_succ": "https:\/\/www.webina.me\/success",
    "callback_url_fe_fail": "https:\/\/www.webina.me\/failed",
    "skip_receipt": false,
    "credit_card_verification_url": "https:\/\/www.qlicknpay.com\/s?TMzRUT0tAuI7",
    "credit_card_details": {
        "schemeCard": "MASTERCARD",
        "fundingMethodCard": "CREDIT"
    },
    "created": "2021-04-19 13:15:40",
    "modified": "2021-04-19 14:44:10"
}

            
              
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "verification_status": "Success",
    "token": "e3b0c44vcr2e1c1c149afbf4c8996fb92427ae41esq124334ca4111452b855ved",
    "callback_url_be": "https:\/\/www.webina.me\/callback",
    "callback_url_fe_succ": "https:\/\/www.webina.me\/success",
    "callback_url_fe_fail": "https:\/\/www.webina.me\/failed",
    "skip_receipt": false,
    "credit_card_verification_url": "https:\/\/www.qlicknpay.com\/s?TMzRUT0tAuI7",
    "credit_card_details": {
        "schemeCard": "MASTERCARD",
        "fundingMethodCard": "CREDIT"
    },
    "created": "2021-04-19 13:15:40",
    "modified": "2021-04-19 14:44:10"
}
response Respond from the API. (This is not status of the verification)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
verification_status Token verification status

TYPE: STRING
EXAMPLE: Success
token Customer's Token ID.

TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
b2fa04ee73e6c6470b779ec314
callback_url_be Back-end Callback URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
callback_url_fe_succ Successful Verification Return URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
callback_url_fe_fail Failed Verification Return URL

TYPE: STRING
EXAMPLE: https://www.webina.me/callback
skip_receipt Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
  • Accepts only integer
  • Default value is '0'
TYPE: INTEGER
EXAMPLE: 0
credit_card_verification_url Card Verification URL. This URL will ask customers to fill up their Credit Card number.

TYPE: STRING
EXAMPLE: https://www.qlicknpay.com/s?TMzRUT0tFKiUY
credit_card_details Details of the customer's card
  • schemeCard - Card Type
  • fundingMethodCard - Funding method type
TYPE: JSON
EXAMPLE: *Please refer our sample respond*
created Date of Verification Requested

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40
modified Date of Modified

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Transactions

Use this API to get all available transaction that was charged using tokens. Max display per page is 100 rows.

API Endpoint URLs

Required Arguments

Example request:

               
curl POST {Endpoint URL}\
               -H 'Content-Type: application/json'\
               -d merchant_id: 10010\
               -d date_from: 2021-04-14\
               -d date_to: 2021-04-19\
               -d status: 3\
               -d page: 1\
               -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                               

             
               
$data_request = array(
                 'merchant_id' => '10010',
                 'date_from' => '2021-04-14',
                 'date_to' => '2021-04-19',
                 'status' => '3',
                 'page' => '1',
                 'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                  );

               $fields_string = json_encode($data_request);

               $ch = curl_init();
               curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
               curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
               curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
               curl_setopt($ch, CURLOPT_POST, 1);
               curl_setopt($ch, CURLOPT_POSTFIELDS,
                           $fields_string);

               curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

               $server_output = curl_exec($ch);

               curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the data.
  • Accept only numbers
  • 0 - All failed transactions, 1 - All success transactions, 2 - Both failed and success transactions, 3 - Failed, success and pending transactions
TYPE: INTEGER
EXAMPLE: 3
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Respond from Get Transactions API

Response (200):

               
[
  {
     "total_page_available": 1,
  },
  {
     "reference_id": "REFID01",
     "invoice": "INV01",
     "amount": "12.50",
     "txn_status": "00",
     "status": "Payment Successful",
     "time": "2021-04-19 10:06:50",
  }
]
           

             
               
[
  {
     "total_page_available": 1,
  },
  {
     "reference_id": "REFID01",
     "invoice": "INV01",
     "amount": "12.50",
     "txn_status": "00",
     "status": "Payment Successful",
     "time": "2021-04-19 10:06:50",
  }
]
total_page_available Total page available. (Max display per page is 100 rows)
  • Return '00' as a successful response / successful request for cancel. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
txn_status Status code for the payment
  • 00 - Successful Payment
  • 12 - Failed Payment
TYPE: STRING
EXAMPLE: 00.
status Message status for verification

TYPE: STRING
EXAMPLE: Payment Successful.
time Date of Transaction

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Get Transaction Details

Use this API to retrieve specific transactions in more details.

API Endpoint URLs

URL Parameters

Required Arguments

Example request (Get Transaction Details):

                
curl POST {Endpoint URL}\

                  -H 'Content-Type: application/json'\
                  -d merchant_id: 10010\
                  -d invoice: INV12\
                  -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
                                    

              
                
$data_request = array(
                  'merchant_id' => '10010',
                  'invoice' => 'INV12',
                  'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
                                    );

                $fields_string = json_encode($data_request);

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
                curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
                curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
                curl_setopt($ch, CURLOPT_POST, 1);
                curl_setopt($ch, CURLOPT_POSTFIELDS,
                            $fields_string);

                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                $server_output = curl_exec($ch);

                curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10010
invoice Your unique Invoice ID
  • Accept alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: INV12
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Respond from Get Transactions API

Response (200):

                
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "invoice": "INV01",
    "amount": "12.50",
    "credit_card_details": {
        "schemeCard": "MASTERCARD",
        "fundingMethodCard": "CREDIT"
    },
    "authorization_code": "764746",
    "status": "Payment Successful",
    "time": "2021-04-19 13:15:40"
}

              
                
{
    "response": "00",
    "reference_id": "REFERENCEID01",
    "invoice": "INV01",
    "amount": "12.50",
    "credit_card_details": {
        "schemeCard": "MASTERCARD",
        "fundingMethodCard": "CREDIT"
    },
    "authorization_code": "764746",
    "status": "Payment Successful",
    "time": "2021-04-19 13:15:40"
}
response Respond from the API. (This is not status of the payment)
  • Return '00' as a successful response. Otherwise, the API has an error.
TYPE: STRING
EXAMPLE: 00
reference_id Token Reference ID
  • Unique reference ID.
TYPE: STRING
EXAMPLE: REFID02
invoice Transaction Invoice Number

TYPE: STRING
EXAMPLE: INV01
amount Transaction Amount

TYPE: STRING
EXAMPLE: 10.50
txn_status Status of the transaction
  • 00 - Successful Payment
  • 12 - Failed Payment
  • 09 - Pending Payment
TYPE: STRING
EXAMPLE: 00
status Message status for transaction

TYPE: STRING
EXAMPLE: Payment Successful.
credit_card_details Details of the customer's card
  • schemeCard - Card Type
  • fundingMethodCard - Funding method type
TYPE: JSON
EXAMPLE: *Please refer our sample respond*
time Date of Transaction

TYPE: STRING
EXAMPLE: 2021-04-19 13:15:40

Batch Charge Card

Use this API to charge multiple VISA / MasterCard card in batch mode.

Below is a Tokenization flow diagram on how to charge multiple cards by using the token ID provided

API Endpoint URLs

Required Arguments

Example request (Batch Charge Card):

     
curl POST {Endpoint URL}\

       -H 'Content-Type: application/json'\
       -d merchant_id: 10010\
       -d token_list: 0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00;
caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00;
9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3dad5cc0e0d26f650ffd,INV03,31.00;\
       -d batch_id: BATCH01\
       -d callback_url_be: https://www.webina.me/callback\
       -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
              

   
     
$data_request = array(
       'merchant_id' => '10010',
       'token_list' => '0c671df1ad7419bea32204f0989e4522703045632ffe52eb98ab69c7891dd9cb,INV01,41.00;
caeb58f63f75b7f8026b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02,11.00;
9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3dad5cc0e0d26f650ffd,INV03,31.00;',
       'batch_id' => 'BATCH01',
       'callback_url_be' => 'https://www.webina.me/callback',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
token_list Your list of the generated token.
  • Must be less than 500 list of tokens.
  • Below is a sample format of the string with a list of tokens

*Click on the image for a larger resolution

Sample format for each detail:


Sample format for multiple payments:

  • Invoice No must be alphanumerics and less than 20 characters.
  • Amount must be more than RM1.50

TYPE: STRING
EXAMPLE: 0c671df1ad7419bea32204f0989e4522703045632ff
e52eb98ab69c7891dd9cb,INV01,41.00;caeb58f63f75b7f802
6b12e6f67971d5aa5b549d9aace00fbd7158af42ddff64,INV02
,11.00;9b6c94a3c89bd6f039503eece4d84646dbfea08411aa3
dad5cc0e0d26f650ffd,INV03,31.00;
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
callback_url_be Back-end Callback URL. Your payment status will be sent to your callback endpoint. Refer here on how to receive the payment status (via callback).
  • Accepts only valid URL (starts with HTTP / HTTPS)
  • Host name must be the same as the URL or Whitelist Domain specified in API Management page
  • API Management page
  • The default value will be ignored if this field is specified
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

How to receive the payment status (via callback)?

The payment status will be sent back to your specified back-end URL in the following format using POST method.

Field Name Example Value
batch_id Your unique Batch ID
  • Alphabets and numbers only.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: STRING
EXAMPLE: BATCH01
token_list Your list of the generated token including payment status and error codes (if any)
  • Below is a sample format of the string with a updated list of tokens

*Click on the image for a larger resolution

Sample format for UNSUCCESSFUL payment:


Sample format for SUCCESSFUL payment:


Sample format for multiple payments:

TYPE: STRING
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Alphabets and numbers only.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Cancel Charge Card by Batch

Use this API to cancel the payment that has been submitted by batch. You are only allowed to cancel payment request that is less than 10 minutes from the batch submission.

API Endpoint URLs

Required Arguments

Example request:

     
curl POST {Endpoint URL}\
     -H 'Content-Type: application/json'\
     -d merchant_id: 10010\
     -d batch_id: BATCH01\
     -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           

   
     
$data_request = array(
       'merchant_id' => '10010',
       'batch_id' => 'BATCH01',
       'hash' => 'fc85b97551f5a2b8bf28d916f2f8055d',
              );

     $fields_string = json_encode($data_request);

     $ch = curl_init();
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
     curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-type: multipart/form-data'));
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 $fields_string);

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: INTEGER
EXAMPLE: 10001
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Get Batch

Retrieve all submitted batches of data.

API Endpoint URLs

Required Arguments

Example request:

     
                          
curl POST {Endpoint URL}\
           -d merchant_id: 10001\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           
 
   
     
                       
$ch = curl_init();
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 "merchant_id=10001&hash=fc85b97551f5a2b8bf28d916f2f8055d");

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Example response (200):

     
[
     {
         "total_page_available": 1,
     },
     {
         "batch_id": "BATCH03",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "12",
         "status": "Payment Unsuccessful",
         "time": "2022-01-26 16:11:38",
     },
     {
         "batch_id": "BATCH02",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "00",
         "status": "Payment Successful",
         "time": "2022-01-25 15:15:00",
     },
     {
         "batch_id": "BATCH01",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "09",
         "status": "Payment Pending",
         "time": "2022-01-25 14:13:02",
     },
     {
         "batch_id": "BATCH00",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "01",
         "status": "Payment Partially Successful",
         "time": "2022-01-24 05:17:04",
     }

 ]
 

   
     
[
     {
         "total_page_available": 1,
     },
     {
         "batch_id": "BATCH03",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "12",
         "status": "Payment Unsuccessful",
         "time": "2022-01-26 16:11:38",
     },
     {
         "batch_id": "BATCH02",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "00",
         "status": "Payment Successful",
         "time": "2022-01-25 15:15:00",
     },
     {
         "batch_id": "BATCH01",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "09",
         "status": "Payment Pending",
         "time": "2022-01-25 14:13:02",
     },
     {
         "batch_id": "BATCH00",
         "callback_url_be": "https://www.webina.me/callback",
         "txn_status": "01",
         "status": "Payment Partially Successful",
         "time": "2022-01-24 05:17:04",
     }
 ]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Optional Arguments

Field Name Description
date_from By default the date will be the date of first transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last transaction data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
status By default the status will display all the status of the transactions.
  • 0 - All failed batches
  • 1 - All successful batches
  • 2 - Both failed and successful batches
  • 3 - Failed,successful,pending batches
  • 4 - All partially successful batches *means batch payment is partially successful and not all payment wihtin batch was failed.
TYPE: INTEGER
EXAMPLE: 1
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTEGER
EXAMPLE: 2

Get Batch Details

Retrieve selected batch in details

API Endpoint URLs

Required Arguments

Example request:

     
                          
curl POST {Endpoint URL}\
           -d merchant_id: 10001\
           -d batch_id: BATCH01\
           -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
           
 
   
     
                       
$ch = curl_init();
     curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS,
                 "merchant_id=10001&batch_id=BATCH01&hash=fc85b97551f5a2b8bf28d916f2f8055d");

     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

     $server_output = curl_exec($ch);

     curl_close ($ch)

Example response (200):

     
[
         "response": "00",
         "batch_id": "BATCH01",
         "token_list": "5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV56,31.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV782,11.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV923,41.00,00,;5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV709,21.00,00,;1417a502d6851600403bc383592255632e577a159484dc0fce59ee67f1d26bb7,INV504,11.00,00,;5dd36cd067ce6bfbe8563554019127b5a26a25400f80b9f44ff816b912ad2a43,INV548,32.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV767,31.00,00,;c31c989bdbb08fb5b94636f9279d745dd72ba1d00768c1cede6646aecdc824c3,INV162,12.00,00,;",
         "txn_status": "00",
         "status": "Payment Successful",
         "callback_url_be": "https://www.webina.me/test/",
         "time": "2022-01-21 15:36:40",
 ]
 

   
     
[
       "response": "00",
       "batch_id": "BATCH01",
       "token_list": "5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV56,31.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV782,11.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV923,41.00,00,;5a6fc0e96d8ae2bdfa70fb866ef9310144316a8965252c7fc5728eec340a4d92,INV709,21.00,00,;1417a502d6851600403bc383592255632e577a159484dc0fce59ee67f1d26bb7,INV504,11.00,00,;5dd36cd067ce6bfbe8563554019127b5a26a25400f80b9f44ff816b912ad2a43,INV548,32.00,00,;3c38bf7231aafdfc9f7532a10be822cf21e689644444bad4c033608e9480c48a,INV767,31.00,00,;c31c989bdbb08fb5b94636f9279d745dd72ba1d00768c1cede6646aecdc824c3,INV162,12.00,00,;",
       "txn_status": "00",
       "status": "Payment Successful",
       "callback_url_be": "https://www.webina.me/test/",
       "time": "2022-01-21 15:36:40",
 ]
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
batch_id Your unique Batch ID
  • Accept alphabets and numbers.
  • Length: Max 20 characters.
  • Ampersand (&), apostrophe (') and dash (-) is not accepted
TYPE: INTEGER
EXAMPLE: BATCH01
hash The secure hash string to validate the request. Refer here for more information on how to generate the secure hash string.
  • Generated value must contain only alphabets and numbers
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw

Get Settlement

You can retrieve all settlement records (successful transactions) for your account by calling this API.

API Endpoint URLs

Requirement to use the API

Kindly get the following credentials ready in order to start using this feature.

  • Merchant ID
  • API Key

You can retrieve these information at API Management page.

Required Arguments

Example request:

    
                         
curl POST {Endpoint URL}\
          -d merchant_id: 10001\
          -d date_from: 2020-01-02\
          -d date_to: 2020-04-19\
          -d page: 2\
          -d hash: fc85b97551f5a2b8bf28d916f2f8055d\
          
 
  
    
                      
$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"POST {Endpoint URL}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                "merchant_id=10001&date_from=2020-01-02&date_to=2020-04-19&page=2&hash=fc85b97551f5a2b8bf28d916f2f8055d");

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch);

    curl_close ($ch)

Example response (200):

    
[
    {
        "method": "FPX",
        "date": "2020-04-13 20:10:39",
        "invoice_no": "122384001",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    },
    {
        "method": "FPX",
        "date": "2020-04-13 20:35:16",
        "invoice_no": "122435184",
        "amount": "22.50",
        "fee": "1.50",
        "due": "21.00"
    },
    {
        "method": "FPX",
        "date": "2020-04-14 11:09:20",
        "invoice_no": "122622048",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    }
]


  
    
[
    {
        "method": "FPX",
        "date": "2020-04-13 20:10:39",
        "invoice_no": "122384001",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    },
    {
        "method": "FPX",
        "date": "2020-04-13 20:35:16",
        "invoice_no": "122435184",
        "amount": "22.50",
        "fee": "1.50",
        "due": "21.00"
    },
    {
        "method": "FPX",
        "date": "2020-04-14 11:09:20",
        "invoice_no": "122622048",
        "amount": "69.00",
        "fee": "1.50",
        "due": "67.50"
    }
]

Example response (400):

    
{
  "response": "97",
  "msg": "Invalid date_from format."
}


  
    
{
  "response": "97",
  "msg": "Invalid date_from format."
}

Example response (401):

    
{
  "response": "99",
  "msg": "Verification fail"
}


  
    
{
  "response": "99",
  "msg": "Verification fail"
}
Field Name Description
merchant_id Your merchant ID
  • Accept only numbers
  • Value is pre-defined by system
  • Do not modify this value to avoid error
TYPE: NUMBER
EXAMPLE: 10001
hash The secure hash string to validate the payment request sent to our Payment Gateway. Refer here on how to generate your hash verification.
  • Accept only alphabets
TYPE: STRING

Optional Arguments

Field Name Description
date_from By default the date will be the date of first settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
date_to By default the date will be the date of last settlement data.
  • Accept only numbers and '-' sign
  • Date format must be yyyy-mm-dd
TYPE: STRING
EXAMPLE: 2020-07-17
page By default the page is set to number 1.
  • Accept only numbers
  • Must be more than or equal to 1
TYPE: INTERGER
EXAMPLE: 2

Transaction Response Code and Description

Refer to this table for the description of the returned response code.

Transaction Status Code Description
00 Transaction Successful
11 Transaction Failed
22 Transaction Pending
failed Customer cancelled payment


Refer to this table for the description of the payment method code from the callback.

Payment Method Code Description
online_banking FPX Online banking payment
card Credit/Debit Card payment
ewallet E-wallet payment
bnpl Buy Now Pay Later payment




Hashing Guide

This section will explain how to secure your API request & response using hashing method. This will be used to generate the hash field in your API request as well as to validate the return hash from QlicknPay.

When Sending API Request. Please follow these steps:

  1. Sort all of your send parameter (parameter's name) into alphabets order (except 'hash' parameter). Below is a sample code for Standard Payment in PHP on how to sort the data:
    2. Before sorting

    $data_request = array(
      "merchant_id" "R10005",
      "invoice" =>"INV1001",
      "amount" => "1.50",
      "payment_desc" => "Parking fee",
      "currency" => "MYR"
    );

    ksort($data_request);
    After sorting
    [
      "amount": "1.50",
      "currency": "MYR",
      "invoice": "INV1001",
      "merchant_id": "R10005",
      "payment_desc": "Parking fee",
    ]

  2. Convert all the data into a single string and remove all spaces. Below is a sample of string of data:

    3. 1.50MYRINV1001R10005Parkingfee

  3. Encrypt the string of the data by using HMAC encryption method by using your API Key. Below is a sample code in PHP:

    4. hash_hmac('sha256', "1.50MYRINV1001R10005Parkingfee", "MYAPIKEY");

  4. You are now successfully generate your hash verification string. Store the hash string data into 'hash' parameter. Send the data to the given API endpoint by using POST method including with the others data.





WooCommerce

QlicknPay's Plugin for WooCommerce is supported by both older and newer versions of WooCommerce.

Download WooCommerce Plugin

Download the QlicknPay's Plugin for WooCommerce by clicking here.

Begin Installation

  1. Login into your WooCommerce Admin Panel using your WooCommerce login credentials.
  2. Go to the "Add Plugin" page by clicking on Plugins > Add New on the left side menu.
  3. Click on the "Upload Plugin" button and choose the downloaded .zip file.
  4. Click on "Install Now" then activate the plugin by clicking on "Activate Plugin" once the installation process finishes.

Configuring Your QlicknPay Plugin

NOTE: You will need your QlicknPay's Merchant ID and API Key in this step. Click here to retrieve your Merchant ID and API Key.

  1. In the WooCommerce Admin Panel, click on "Settings".
  2. Fill in all the required fields accordingly, enable the plugin by clicking on the "Enable/Disable" checkbox and save the changes.

Start Selling

Once you have configured your QlicknPay Plugin, kindly perform at least one test transaction before you start selling.

shell php