.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
TYPE: STRING
EXAMPLE:INV0001
|
| amount |
Final amount to be paid by buyer
TYPE: STRING
EXAMPLE:250
|
| payment_desc |
Purpose of payment
TYPE: STRING
EXAMPLE:PARKING FEE
|
| currency |
Currency of payment
TYPE: STRING
EXAMPLE:MYR
|
| hash |
The secure hash string to validate the payment request sent to our Payment Gateway.
TYPE: STRING
|
Optional Arguments
| Parameter | Description |
|---|---|
| buyer_name |
Buyer's name
TYPE: STRING
EXAMPLE:JOHN
|
| buyer_email |
Buyer's email. Buyer will receive payment notification at this address if specified
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
|
| phone |
Buyer's phone number
TYPE: STRING
EXAMPLE:+60171234567
|
| add_line_1 |
Buyer's address line 1
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
|
| add_line_2 |
Buyer's address line 2
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
|
| postcode |
Buyer's postcode
TYPE: INTEGER
EXAMPLE:47810
|
| city |
Buyer's city location
TYPE: STRING
EXAMPLE:PETALING JAYA
|
| comment |
Buyer's additional comments / notes on the purchase
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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.
For the installment payment channel: You can set the
installment payment plan period that you want to offer to your customers.
Please include 'installmentPeriodFilter' as a value for this parameter. Otherwise, the default value offered to customers will be 12 months.
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
For the installment payment channel: If you have included
'installmentPeriodFilter' in your baggage_variable, you may add a new parameter in your API request called
'installmentPeriodFilter'. The value must be a STRING containing the list of offered plans, separated by commas ",".
TYPE: STRING
EXAMPLE:VALUE1
|
| header_title |
Modify your company name at payment gateway checkout page
TYPE: STRING
EXAMPLE:PAYMENT HEADER TITLE
|
| header_email |
Modify your company email address at payment gateway checkout page
TYPE: STRING
EXAMPLE:SUPPORT@MERCHANT.COM
|
| header_phone |
Modify your company phone number at payment gateway checkout page
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:
callback_url_be variable OR2. 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
TYPE: STRING
EXAMPLE:INV0001
|
| amount |
Final amount to be paid by buyer
TYPE: STRING
EXAMPLE:250.00
|
| payment_desc |
Purpose of payment
TYPE: STRING
EXAMPLE: PARKING FEE
|
| currency |
Currency of payment
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Parameter | Description |
|---|---|
| buyer_name |
Buyer's name
TYPE: STRING
EXAMPLE:JOHN
|
| buyer_email |
Buyer's email. Buyer will receive payment notification at this address if specified
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
|
| phone |
Buyer's phone number
TYPE: STRING
EXAMPLE:+60171234567
|
| add_line_1 |
Buyer's address line 1
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
|
| add_line_2 |
Buyer's address line 2
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
|
| postcode |
Buyer's postcode
TYPE: INTEGER
EXAMPLE:47810
|
| city |
Buyer's city location
TYPE: STRING
EXAMPLE:PETALING JAYA
|
| comment |
Buyer's additional comments / notes on the purchase
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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.
For the installment payment channel: You can set the
installment payment plan period that you want to offer to your customers.
Please include 'installmentPeriodFilter' as a value for this parameter. Otherwise, the default value offered to customers will be 12 months.
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
For the installment payment channel: If you have included
'installmentPeriodFilter' in your baggage_variable, you may add a new parameter in your API request called
'installmentPeriodFilter'. The value must be a STRING containing the list of offered plans, separated by commas ",".
TYPE: STRING
EXAMPLE:VALUE1
|
| header_title |
Modify your company name at payment gateway pages
TYPE: STRING
EXAMPLE:PAYMENT HEADER TITLE
|
| header_email |
Modify your company email address at payment gateway pages
TYPE: STRING
EXAMPLE:SUPPORT@MERCHANT.COM
|
| header_phone |
Modify your company phone number at payment gateway pages
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
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.
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
- Request an API called ‘Get Bank List’ to get list of banks available for the payer.
- Merchant send a payment request to an API called ‘Direct Payment’.
- Payer directly to selected bank portal
- 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.
- 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
||||||||||||
| invoice |
Unique invoice number
TYPE: STRING
EXAMPLE:INV0001
|
||||||||||||
| amount |
Final amount to be paid by buyer
TYPE: STRING
EXAMPLE:250
|
||||||||||||
| payment_desc |
Purpose of payment
TYPE: STRING
EXAMPLE:PARKING FEE
|
||||||||||||
| currency |
Currency of payment
TYPE: STRING
EXAMPLE:IDR
|
||||||||||||
| payment_method |
Payment Method of the payment.
TYPE: STRING
EXAMPLE:b2c
|
||||||||||||
| agent_channel_code |
Conditional. This parameter is required if you are choosing 'indo_bank' as a 'payment_method'
TYPE: STRING
EXAMPLE:ATM
|
||||||||||||
| bank_code |
For Online Banking (B2B, B2C), eWallet Payment and Indonesia Bank Portal Payment:
For Credt Card Payment:
For Buy Now Pay Later Payment:
For Instalment Payment Plan (IPP):
TYPE: STRING
EXAMPLE:MB2U0227
|
||||||||||||
| hash |
The secure hash string to validate the payment request sent through our Payment Gateway.
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.
TYPE: INTEGER
EXAMPLE:1
|
| buyer_name |
Buyer's name
TYPE: STRING
EXAMPLE:JOHN
|
| buyer_email |
Buyer's email. Buyer will receive payment notification at this address if specified
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
|
| phone |
Buyer's phone number
TYPE: STRING
EXAMPLE:+60171234567
|
| add_line_1 |
Buyer's address line 1
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
|
| add_line_2 |
Buyer's address line 2
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
|
| postcode |
Buyer's postcode
TYPE: INTEGER
EXAMPLE:47810
|
| city |
Buyer's city location
TYPE: STRING
EXAMPLE:PETALING JAYA
|
| comment |
Buyer's additional comments / notes on the purchase
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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.
For the installment payment channel: You can set the
installment payment plan period that you want to offer to your customers.
Please include 'installmentPeriodFilter' as a value for this parameter. Otherwise, the default value offered to customers will be 12 months.
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
For the installment payment channel: If you have included
'installmentPeriodFilter' in your baggage_variable, you may add a new parameter in your API request called
'installmentPeriodFilter'. The value must be a STRING containing the list of offered plans, separated by commas ",".
TYPE: STRING
EXAMPLE:VALUE1
|
| skip_receipt |
Skip QlicknPay receipt page and directly to merchant page. Set '0' as false and '1' as true
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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-11-21\
-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-11-21 &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
TYPE: STRING
EXAMPLE: R1001
|
| purpose | Description of the payment link. Must be a unique
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
|
| amount_option | Type of amount for payment link. Only accept a fixed or flexi 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"
TYPE: STRING
EXAMPLE: 100.55
|
| delivery_option | Allow checkout page to display the delivery form as mandatory fields.
TYPE: INTERGER
EXAMPLE: 0
|
| currency |
Currency of payment
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| due_date | Expiry date of the Payment Link.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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
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.
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: STRING
EXAMPLE: 1
|
| merchant_id |
Your merchant ID
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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.
TYPE: DATE
|
Report Collection Payment Link API
This API allows you to access a list collection of Payment Links.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| date_to | By default the date will be the date of last batch data.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| date_to | By default the date will be the date of last batch data.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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
|
Create Invoice API
This API allow you to create an invoice and include it with a payment link.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
Required Arguments
Example request:
curl -X POST {Endpoint URL}\
-H "Content-Type: application/json" \
-d '{
"merchant_id": "R10001",
"invoice_id": "INV0123",
"currencies": [
"MYR"
],
"items": {
"1": {
"description": "Product #1",
"quantity": "3",
"amount": "30.20"
},
"2": {
"description": "Product #2",
"quantity": "1",
"amount": "100.20"
},
"3": {
"description": "Product #3",
"quantity": "10",
"amount": "310.20"
}
},
"email": "customer@domain.com",
"phone": "+60179999999",
"partial_payment_status": 1,
"description": "General description of this invoice is here",
"note": "Sample note for invoicing #1",
"send_at": "2024-11-22 16:15:00",
"expired_at": "2024-12-21 16:15:00",
"attachments": [
"https://www.domain.com/attachment/document_1.pdf",
"https://www.domain.com/attachment/img.gif",
],
"tax": [
{
"type": "percentage",
"amount": "10"
},
{
"type": "fixed",
"amount": "2.50"
}
],
"reminders": {
"due_in": {
"1": {
"message": "Your invoice is due in 3 days!"
},
"3": {
"message": "Hi there please make a payment ASAP!"
}
},
"overdue": {
"1": {
"message": "Your invoice is already overdue by 4 days!"
},
"4": {
"message": "No payment are received! Please contact me."
}
}
},
"hash": "{{Generated hash value}}"
}'
$data = [
"merchant_id" => "R10001",
"invoice_id" => "INV0123",
"currencies" => ["MYR"],
"items" => [
"1" => [
"description" => "Product #1",
"quantity" => "3",
"amount" => "30.20"
],
"2" => [
"description" => "Product #2",
"quantity" => "1",
"amount" => "100.20"
],
"3" => [
"description" => "Product #3",
"quantity" => "10",
"amount" => "310.20"
]
],
"email" => "customer@domain.com",
"phone" => "+60179999999",
"partial_payment_status" => 1,
"description" => "General description of this invoice is here",
"note" => "Sample note for invoicing #1",
"send_at" => "2024-07-04 16:15:00",
"expired_at" => "2024-08-02 16:15:00",
"attachments" => [
"https://www.domain.com/attachment/document_1.pdf",
"https://www.domain.com/attachment/img.gif"
],
"tax" => [
[
"type" => "percentage",
"amount" => "10"
],
[
"type" => "fixed",
"amount" => "2.50"
]
],
"reminders" => [
"due_in" => [
"1" => [
"message" => "Your invoice is due in 3 days!"
],
"3" => [
"message" => "Hi there please make a payment ASAP!"
]
],
"overdue" => [
"1" => [
"message" => "Your invoice is already overdue by 4 days!"
],
"4" => [
"message" => "No payment are received! Please contact me."
]
]
],
"hash" => "{{Generated hash value}}"
];
$endpointUrl = "{Endpoint URL}";
$payload = json_encode($data);
$ch = curl_init($endpointUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($payload)
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
| Field Name | Description |
|---|---|
| merchant_id | Your merchant ID
TYPE: STRING
EXAMPLE: R10001
|
| invoice_id | Unique Invoice ID defined by your system
TYPE: STRING
EXAMPLE: INV0123
|
| currencies | Payment currecies
TYPE: ARRAY
EXAMPLE: ['MYR','IDR']
|
| items |
Here is a list of items. The payable amount includes the total for all listed items, exclude taxes.
items: {
"{{Your pre-defined ID}}": {
"description": "{{Description of the item}}",
"quantity": "{{Total quantity of the item}}",
"amount": "{{Amount of the item that has been calculated with the quantity}}"
}
...
}
|
| partial_payment_status | Enable your customers to make partial payments
TYPE: BOOLEAN
EXAMPLE: 1
|
| hash | The secure hash string to validate the API request. You may refer Generate Hash Invoice section on how to generate your hash value.
TYPE: STRING
|
Optional Arguments
| Field Name | Description |
|---|---|
| invoice_to_name | Recipient's name. By default it will set as 'Customer'
TYPE: STRING
EXAMPLE: John
|
| tax | Tax is included in the invoice.
These taxes will be calculated based on the total amount of all items specified. You are allowed to
enter multiple taxes. Refer to the format below:
tax: {
{
"type": "{{Type of calculation (percentage / fixed)}}",
"amount": "{{Total tax}}",
},
...
}
|
Recipient email address. An invoice details and reminders will be sent to this email.
TYPE: STRING
EXAMPLE: JOHN@DOMAIN.COM
|
|
| phone | Recipient phone number: An invoice details and reminders will be sent to this WhtasApp number. Must include with a country code with plus '+' sign.
TYPE: STRING
EXAMPLE: +60171234567
|
| reminders | Send a notification to your recipient as a reminder via email or WhatsApp.
You are allowed to send the reminder either before the due date or after the expiry date of the invoice. Refer to the format below:
"reminders": {
"due_in": {
"{{Total day before the expiry date}}": {
"message": "{{Message content}}"
},
...
},
"overdue": {
"{{Total day after the expiry date}}": {
"message": "{{Message content}}"
},
...
}
}
|
| description | Description of the invoice
TYPE: STRING
EXAMPLE: This is an invoice for your plan subscription
|
| note | Note for recipient
TYPE: STRING
EXAMPLE: Please make the payment ASAP
|
| paid_at | If the invoice is already paid, you may set the date of the payment.
If this parameter is set, no payment is needed for this invoice. An invoice is generated without a payment request.
TYPE: STRING
EXAMPLE: 2024-11-21 06:38:02
|
| send_at | The date of invoice notification is send including with the details. Please ensure you have include with either 'email' or/and 'phone' parameters.
TYPE: STRING
EXAMPLE: 2024-11-21 06:38:02
|
| expired_at | The date of invoice expiry date. Recipient unable to make a payment after the expiry date.
TYPE: STRING
EXAMPLE: 2024-11-21 06:38:02
|
Respond data
The response data after calling the API
You may refer to "invoice_url" parameter to redirect to your created invoice page.
Example response:
{
"status": "00",
"merchant_id": "R10001",
"company_name": "COMPANY NAME SDN BHD",
"company_number": "ABCZYX-123",
"logo": "https://www.betterpay.me/merchant/assets/images/logo-small-2.png",
"invoice_id": "INV0123",
"invoice_to_name": "Customer",
"currencies": [
"MYR"
],
"items": {
"1": {
"description": "Product #1",
"quantity": "3",
"amount": "30.20"
},
"2": {
"description": "Product #2",
"quantity": "1",
"amount": "100.20"
},
"3": {
"description": "Product #3",
"quantity": "10",
"amount": "310.20"
}
},
"partial_payment_status": 1,
"paid_amount": null,
"email": "customer@domain.com",
"phone": "60179999999",
"description": null,
"note": "Sample note for invoicing #1",
"tax": [
{
"type": "percentage",
"amount": "10"
},
{
"type": "fixed",
"amount": "2.50"
}
],
"reminders": {
"due_in": {
"1": {
"message": "Your invoice is due in 3 days!"
},
"3": {
"message": "Hi there please make a payment ASAP!"
}
},
"overdue": {
"1": {
"message": "Your invoice is already overdue by 4 days!"
},
"4": {
"message": "No payment are received! Please contact me."
}
}
},
"invoice_url": "https://www.betterpay.me/payment/invoice/?id=669e0f68df332",
"paid_at": null,
"send_at": "2024-02-27 16:15:00",
"expired_at": "2025-02-28 16:15:00",
"created_at": "2024-07-22 07:51:04"
}
{
"status": "00",
"merchant_id": "R10001",
"company_name": "COMPANY NAME SDN BHD",
"company_number": "ABCZYX-123",
"logo": "https://www.betterpay.me/merchant/assets/images/logo-small-2.png",
"invoice_id": "INV0123",
"invoice_to_name": "Customer",
"currencies": [
"MYR"
],
"items": {
"1": {
"description": "Product #1",
"quantity": "3",
"amount": "30.20"
},
"2": {
"description": "Product #2",
"quantity": "1",
"amount": "100.20"
},
"3": {
"description": "Product #3",
"quantity": "10",
"amount": "310.20"
}
},
"partial_payment_status": 1,
"paid_amount": null,
"email": "customer@domain.com",
"phone": "60179999999",
"description": null,
"note": "Sample note for invoicing #1",
"tax": [
{
"type": "percentage",
"amount": "10"
},
{
"type": "fixed",
"amount": "2.50"
}
],
"reminders": {
"due_in": {
"1": {
"message": "Your invoice is due in 3 days!"
},
"3": {
"message": "Hi there please make a payment ASAP!"
}
},
"overdue": {
"1": {
"message": "Your invoice is already overdue by 4 days!"
},
"4": {
"message": "No payment are received! Please contact me."
}
}
},
"invoice_url": "https://www.betterpay.me/payment/invoice/?id=669e0f68df332",
"paid_at": null,
"send_at": "2024-02-27 16:15:00",
"expired_at": "2025-02-28 16:15:00",
"created_at": "2024-07-22 07:51:04"
}
Update Invoice API
This API allow you to update your created invoice.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
Required Arguments
| Field Name | Description |
|---|---|
| merchant_id | Your merchant ID
TYPE: STRING
EXAMPLE: R10001
|
| invoice_id | Use Invoice ID you have created
TYPE: STRING
EXAMPLE: INV0123
|
| hash | The secure hash string to validate the API request. You may refer Generate Hash Invoice section on how to generate your hash value.
TYPE: STRING
|
Optional Arguments
You may refer parameters in Create Invoice API section. Any changes you are required, you may use same parameter's name.
Get All Invoices API
This API allow you to get all your invoices you have created within specific date.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
Required Arguments
Example request:
curl -X POST {Endpoint URL}\
-H "Content-Type: application/json" \
-d '{
"merchant_id": "R10001",
"hash": "{{Generated hash value}}"
}'
$data = [
"merchant_id" => "R10001",
"hash" => "{{Generated hash value}}"
];
$endpointUrl = "{Endpoint URL}";
$payload = json_encode($data);
$ch = curl_init($endpointUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($payload)
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
| Field Name | Description |
|---|---|
| merchant_id | Your merchant ID
TYPE: STRING
EXAMPLE: R10001
|
| hash | The secure hash string to validate the API request. You may refer Generate Hash Invoice section on how to generate your hash value.
TYPE: STRING
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from | The date of the invoice is created. By default, it is set to 30 days prior to the current date.
TYPE: STRING
EXAMPLE: 2024-11-21 06:38:02
|
| date_to | The date of the invoice is created. By default, it is set to the current date.
TYPE: STRING
EXAMPLE: 2024-11-21 06:38:02
|
Get Invoice API
This API allow you to get specific invoice details.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
Required Arguments
Example request:
curl -X POST {Endpoint URL}\
-H "Content-Type: application/json" \
-d '{
"merchant_id": "R10001",
"invoice_id": "INV0123",
"hash": "{{Generated hash value}}"
}'
$data = [
"merchant_id" => "R10001",
"invoice_id" => "INV0123",
"hash" => "{{Generated hash value}}"
];
$endpointUrl = "{Endpoint URL}";
$payload = json_encode($data);
$ch = curl_init($endpointUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($payload)
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
| Field Name | Description |
|---|---|
| merchant_id | Your merchant ID
TYPE: STRING
EXAMPLE: R10001
|
| invoice_id | Use Invoice ID you have created
TYPE: STRING
EXAMPLE: INV0123
|
| hash | The secure hash string to validate the API request. You may refer Generate Hash Invoice section on how to generate your hash value.
TYPE: STRING
|
Generate Hash Invoice 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:
- Sort all of your send parameter (parameter's name) into alphabets order (except
'hash'parameter). Below is a sample code in PHP on how to sort the data:
Before sorting
- Convert all the data into a single string and remove all spaces. Below is a sample of string of data:
- Encrypt the string of the data by using HMAC encryption method by using your API Key. Below is a sample code in PHP:
- 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.
$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",
]
1.50MYRINV1001R10005Parkingfee
hash_hmac('sha256', "1.50MYRINV1001R10005Parkingfee", "MYAPIKEY");
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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.
TYPE: STRING
EXAMPLE: Monthly
|
| subscription_id |
Unique ID for your subscription package
TYPE: STRING
EXAMPLE: FIXED001
|
| name |
Name of your subscription
TYPE: STRING
EXAMPLE: Monthly Subscription
|
| price |
Price of the subscription. This variable is only available for 'fixed' subscription package. Otherwise, please ignore this variable.
TYPE: STRING
EXAMPLE: 105.00
|
| purpose |
Short description of the subscription
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.
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)
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)
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 >)
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| subscription_id |
Unique ID from your created Subscription
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.
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.
TYPE: STRING
EXAMPLE: Monthly
|
| price |
Price of the subscription. This variable is only available for 'fixed' subscription package. Otherwise, please ignore this variable.
TYPE: STRING
EXAMPLE: 105.00
|
| purpose |
Short description of the subscription
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.
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)
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)
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 >)
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Add Subscribers)
| Field Name | Description | |
|---|---|---|
| {Subscription ID} |
Your Unique Subscription ID
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| subscriber_details: | {id_number:value} |
Payer ID Number (Ex: IC Number)
TYPE: INTEGER
EXAMPLE: 950711251499
|
| subscriber_details: | {id_type:value} |
ID Number Type
TYPE: INTEGER
EXAMPLE: 1
|
| subscriber_details: | {name:value} |
Subscribers full name
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
|
| subscriber_details: | {reference_no:value} |
Your reference no
TYPE: INTEGER
EXAMPLE: 101
|
| mandate_frequency |
If the subscription package is flexi, this variable is mandatory
TYPE: STRING
EXAMPLE: Monthly
|
|
| bank_id |
Subscriber selected bank
TYPE: STRING
EXAMPLE: MB2U0227
|
|
| amount |
This variable is mandatory for Flexi Subscription
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.
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)
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)
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 >)
TYPE: STRING
EXAMPLE: 20.00
|
Optional Arguments (Add Subscribers)
| Field Name | Description | |
|---|---|---|
| payment_method |
Payment method of the emandate.
TYPE: STRING
EXAMPLE: b2c
|
|
| subscriber_details: | {email:value} |
Subscriber email address
TYPE: STRING
EXAMPLE: JOHN@DOMAIN.COM
|
| subscriber_details: | {phone:value} |
Subscriber phone number
TYPE: STRING
EXAMPLE: 0173649226
|
| callbacks: | {back_end:value} |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE: https://www.webina.me/callback
|
| callbacks: | {fe_success:value} |
Return URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE: https://www.webina.me/success
|
| callbacks: | {fe_fail:value} |
Return URL for your front-end failed transaction process
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Add Subscribers)
| Field Name | Description | |
|---|---|---|
| {Subscription ID} |
Your Unique Subscription ID
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments (Get Subscribers)
| Field Name | Description |
|---|---|
| page |
By default the page is set to number 1.
TYPE: INTEGER
EXAMPLE: 2
|
| no_of_record_per_page |
No of record per pages. By default it will display 100 records per pages.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Get Subscriber Details)
| Field Name | Description | |
|---|---|---|
| {Subscriber Reference No} |
Your Unique Subscriber Reference No
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
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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.
TYPE: INTEGER
EXAMPLE: 2
|
| offset |
List of mandates display per pages. Must be below 100 mandates.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Get Subscription Details)
| Field Name | Description | |
|---|---|---|
| {Subscription ID} |
Your Unique Subscription ID
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
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Modify Subscriber)
| Field Name | Description | |
|---|---|---|
| {Subscriber Reference No} |
Your Unique Subscriber Reference No
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
|
Optional Arguments (Modify Active Subscriber)
| Field Name | Description | |
|---|---|---|
| terms |
Terms or payment frequency of the subscription
TYPE: STRING
EXAMPLE: Monthly
|
|
| price |
Price of the subscription
TYPE: STRING
EXAMPLE: 105.00
|
|
| last_date_payment |
Date of the last day of the subscription
TYPE: STRING
EXAMPLE: 2021-10-16
|
|
| subscriber_details: | {phone:value} |
Subscriber phone number
TYPE: STRING
EXAMPLE: 0173649226
|
| subscriber_details: | {email:value} |
Subscriber 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters (Terminate Subscribers)
| Field Name | Description | |
|---|---|---|
| {Subscriber Reference No} |
Your Unique Subscriber Reference No
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
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10115
|
||||||||||||
| batch_id |
Your unique batch ID
TYPE: STRING
EXAMPLE:B99123
|
||||||||||||
| collection_date |
Date for subscribers bank account to be debited.
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.
|
||||||||||||
| 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.
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
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;
Set value with '2': In array format. Example:
"data": {
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10115
|
| batch_id |
Your unique batch ID
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10115
|
| batch_id |
Your unique batch ID
TYPE: STRING
EXAMPLE:B99123
|
| fpx_reference_no |
Your submitted FPX Rereference No
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first batch data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last batch data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| page |
By default the page is set to number 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10115
|
| batch_id |
Your unique batch ID
TYPE: STRING
EXAMPLE:B99123
|
| status |
Filter by status of the 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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10115
|
| batch_id |
Your unique batch ID
TYPE: STRING
EXAMPLE:B99123
|
| fpx_reference_no |
Your submitted FPX Rereference No
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.
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.
- Follow the instruction for requirement on Refund API request.
- Make sure you have a valid QlicknPay Reference No or your Invoice No from the transaction that has been made by payer.
- 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
- 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.
- 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
- For Production: Please proceed to your bank portal to approve or decline the refund request.
- 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.
- 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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.
TYPE: STRING
EXAMPLE:SHAHRUL
|
| organization_id |
Your Organization ID. You can retrieve your Organization ID by login to your bank portal.
TYPE: STRING
EXAMPLE:BVCOMPANY123
|
| refund_list |
List of transactions that need to be refunded. Must be in a correct format.
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Parameter | Description |
|---|---|
| enable_callback |
Callback requirement
TYPE: INTEGER
EXAMPLE:1
|
| enable_email |
Email requirement
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.
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
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the transactions.
TYPE: INTEGER
EXAMPLE: 1
|
| page |
By default the page is set to number 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
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: NUMBER
EXAMPLE: 10001
|
| ref_no |
Your invoice number
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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:
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
|
| type |
Bank List Type. 'b2b' or 'b2c' or 'indo_bank' or 'ewallet'
TYPE: STRING
EXAMPLE: b2c
|
| hash |
The secure hash string to validate the request.
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
|
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: NUMBER
EXAMPLE: 10001
|
| invoice |
Your invoice number
TYPE: STRING
EXAMPLE: 10011-FS789-20181009-Mt
|
| method |
Transaction method
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.
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
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first settlement data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last settlement data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| page |
By default the page is set to number 1.
TYPE: INTERGER
EXAMPLE: 2
|
| invoice |
Unique invoice number
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 Balance
This feature is available exclusively for accounts utilizing our Credit Balance system. Merchants can retrieve their credit balance through this API endpoint.
API Endpoint URLs
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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):
{
"response": 00,
"merchant_id": "10001",
"fee": "0.80",
"total_balance": "150.50"
}
{
"response": 00,
"merchant_id": "10001",
"fee": "0.80",
"total_balance": "150.50"
}
| Field Name | Description |
|---|---|
| merchant_id |
Your merchant ID
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.
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 |
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 0cce72d6f37eef7aa35ac05c0fd8e9cc
Get Disburse Records
You can retrieve all disbursement records for your account by calling this API.
API Endpoint URLs
- Production:
GET Please login to view the endpoint - Sandbox: This feature is disabled in demo account.
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first settlement data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last settlement data.
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
- Create Verification URL for payer.
- 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
- Once verification is done, our system will send an email and callback data to your callback URL with the Token ID
- You may use the Token ID to initiate a payment by using the Charge Card API.
- For every successful payment (by token), please wait 5 minutes before making a new payment with the same token ID.
- 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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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?TM79191462353",
"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?TM79191462353",
"created": "2021-04-19 12:40:34",
"modified": "2021-04-19 12:40:34"
}
| Field Name | Description |
|---|---|
| merchant_id |
Your merchant ID
TYPE: INTEGER
EXAMPLE: 10001
|
| reference_id |
Your unique reference ID
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| amount |
Amount to charge.
TYPE: STRING
EXAMPLE: 192.50
|
| invoice |
Unique reference number of this payment
TYPE: STRING
EXAMPLE: INV01
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE: http://www.webina.me/success
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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
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.
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
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
TYPE: STRING
EXAMPLE: REFERENCEID01
|
| txn_status |
Response code of the status of verification.* Refer Response Code table for description.
TYPE: STRING
EXAMPLE: 00
|
| msg |
Message status for verification
TYPE: STRING
EXAMPLE: Verification Approved
|
| token |
Unique ID for Card's Token
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
| nameOnCard |
Name on the card
TYPE: STRING
EXAMPLE: JOHN SMITH
|
| numberCard |
Card number
TYPE: STRING
EXAMPLE: 512345xxxxxx0008
|
| schemeCard |
Card scheme
TYPE: STRING
EXAMPLE: MASTERCARD
|
| issuerCard |
Card issuer
TYPE: STRING
EXAMPLE: MAYBANK BERHAD
|
| expiryMonthCard |
Card expiry (Month)
TYPE: INTEGER
EXAMPLE: 5
|
| expiryYearCard |
Card expiry (Year)
TYPE: INTEGER
EXAMPLE: 21
|
| fundingMethodCard |
Card funding method
TYPE: STRING
EXAMPLE: CREDIT
|
| amount |
Amount of the first payment
TYPE: STRING
EXAMPLE: 121.50
|
| invoice |
Unique invoice number from the first payment
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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters
| Field Name | Example Value |
|---|---|
| {Token ID} |
Token ID that you received from your callback endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Your unique invoice number
TYPE: STRING
EXAMPLE: INV01
|
| amount |
Final amount to be paid by payer
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.
TYPE: INT
EXAMPLE: 0
|
| 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)
TYPE: STRING
EXAMPLE: 00
|
| txn_status |
Status of the transaction
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
|
| 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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters
| Field Name | Example Value |
|---|---|
| {Reference ID / Token ID} |
Your unique reference ID or Token ID
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
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.
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)
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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the data.
TYPE: INTEGER
EXAMPLE: 3
|
| page |
By default the page is set to number 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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token Reference ID
TYPE: STRING
EXAMPLE: REFID02
|
| verification_status |
Token verification status
TYPE: STRING
EXAMPLE: Success
|
| token |
Customer's Token ID.
TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
|
| 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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters
| Field Name | Example Value |
|---|---|
| {Reference ID} |
Your unique reference ID
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
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.
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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token Reference ID
TYPE: STRING
EXAMPLE: REFID02
|
| verification_status |
Token verification status
TYPE: STRING
EXAMPLE: Success
|
| token |
Customer's Token ID.
TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
|
| 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
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
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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the data.
TYPE: INTEGER
EXAMPLE: 3
|
| page |
By default the page is set to number 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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token 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
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
- Production (Non-3DS):
POST Please login to view the endpoint - Production (3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
URL Parameters
| Field Name | Example Value |
|---|---|
| {Invoice} |
Your unique Invoice ID
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
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.
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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token 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
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
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
- Production (Both 3DS and Non-3DS):
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| token_list |
Your list of the generated token.
*Click on the image for a larger resolution Sample format for each detail:
Sample format for multiple payments:
TYPE: STRING
EXAMPLE: 0c671df1ad7419bea32204f0989e4522703045632ff
|
| batch_id |
Your unique Batch ID
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).
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.
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
TYPE: STRING
EXAMPLE: BATCH01
|
| token_list |
Your list of the generated token including payment status and error codes (if any)
*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 |
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| batch_id |
Your unique Batch ID
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.
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
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the transactions.
TYPE: INTEGER
EXAMPLE: 1
|
| page |
By default the page is set to number 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
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
TYPE: NUMBER
EXAMPLE: 10001
|
| batch_id |
Your unique Batch ID
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.
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/?Betterpay |
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
- Login into your OpenCart Admin Panel using your OpenCart login credentials.
- Proceed to "Extension Installer" setting.
- Click on the upload button and choose the
.zipfolder from the downloaded file. - 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.
- In the OpenCart Admin Panel, go to the Extension List page and choose "Payment" as the extension type selection option.
- Search for QlicknPay extension and click on the "Edit" button.
- 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.
|
Download Prestashop Plugins
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
.zipfile 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.
- In the PrestaShop Admin Panel, go to the Module and click on the "Configure" button next to the QlicknPay Module List.
- 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
- Login into your WooCommerce Admin Panel using your WooCommerce login credentials.
- Go to the "Add Plugin" page by clicking on Plugins > Add New on the left side menu.
- Click on the "Upload Plugin" button and choose the downloaded
.zipfile. - 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.
- In the WooCommerce Admin Panel, click on "Settings".
- 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.
- Login into your ECWID Admin Panel using your ECWID login credentials.
- Go to "Payment" page by clicking on Payment menu.
- 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).
- 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.
- Fill in all the required fields accordingly.
- Choose your account type (Production) in the "Advanced Settings" section.
- 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.
- Login into your Drupal Admin Panel using your Drupal login credentials.
- Click on "Commerce" tab to proceed with configuring the plugin.
- Next, click on the "Configuration" tab.
- Click on "Payment Gateways" configuration.
- Click on "Add payment gateway" button to add and enable QlicknPay as your payment gateway.
- 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.
- Login into your Easystore Admin Panel.
- Go to "Settings" page by clicking on Settings on the left side menu.
- Go to "Payments" section.
- Click on "Add payment method" button and choose "Betterpay".
- Fill all requirement information and click save.
- 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
- At checkout pages, you need to manually enter parameters
?testing=trueat the end of Storefront checkout url. - Example:
https://yourstore.easy.co/sf/checkout/9b6a59bf-f971-4b4b-b3c4-f0b485db89a7?testing=true - Proceed to the URL.
- 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.
- 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.
- 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. - IMPORTANT! Specify your callback URL with the following URL: Please login to view the URL
-
Get your
App KeyandApp Secretat 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
- 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.
- 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. - 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
- 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).
- 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
TYPE: STRING
EXAMPLE:INV0001
|
| amount |
Final amount to be paid by buyer
TYPE: STRING
EXAMPLE:250
|
| payment_desc |
Purpose of payment
TYPE: STRING
EXAMPLE:PARKING FEE
|
| currency |
Currency of payment
TYPE: STRING
EXAMPLE:MYR
|
| buyer_name |
Buyer's name
TYPE: STRING
EXAMPLE:JOHN
|
| buyer_email |
Buyer's email. Buyer will receive payment notification at this address if specified
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
|
| phone |
Buyer's phone number
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.
TYPE: STRING
|
Optional Arguments
| Parameter | Description |
|---|---|
| add_line_1 |
Buyer's address line 1
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
|
| add_line_2 |
Buyer's address line 2
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
|
| postcode |
Buyer's postcode
TYPE: INTEGER
EXAMPLE:47810
|
| city |
Buyer's city location
TYPE: STRING
EXAMPLE:PETALING JAYA
|
| comment |
Buyer's additional comments / notes on the purchase
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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.
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
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:
callback_url_be variable OR2. 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| invoice |
Unique invoice number
TYPE: STRING
EXAMPLE:INV0001
|
| amount |
Final amount to be paid by buyer
TYPE: STRING
EXAMPLE:250
|
| payment_desc |
Purpose of payment
TYPE: STRING
EXAMPLE:PARKING FEE
|
| currency |
Currency of payment
TYPE: STRING
EXAMPLE:MYR
|
| buyer_name |
Buyer's name
TYPE: STRING
EXAMPLE:JOHN
|
| buyer_email |
Buyer's email. Buyer will receive payment notification at this address if specified
TYPE: STRING
EXAMPLE:JOHN@DOMAIN.COM
|
| phone |
Buyer's phone number
TYPE: STRING
EXAMPLE:+60171234567
|
| bank_code |
Payment channel code / Bank code. You can retrieve bank code by calling Get
Payment Channels API.
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.
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.
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.
TYPE: INTEGER
EXAMPLE: 1
|
| add_line_1 |
Buyer's address line 1
TYPE: STRING
EXAMPLE:10-3, 3RD FLOOR JLN PJU 5/9
|
| add_line_2 |
Buyer's address line 2
TYPE: STRING
EXAMPLE:DATARAN SUNWAY KOTA DAMANSARA
|
| postcode |
Buyer's postcode
TYPE: INTEGER
EXAMPLE:47810
|
| city |
Buyer's city location
TYPE: STRING
EXAMPLE:PETALING JAYA
|
| comment |
Buyer's additional comments / notes on the purchase
TYPE: STRING
EXAMPLE:COMMENT HERE FOR MERCHANT REFERENCE
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE:HTTPS://WWW.EXAMPLE.COM/CALLBACK_SUCCESS
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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.
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
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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-11-21\
-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-11-21 &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
TYPE: STRING
EXAMPLE: R1001
|
| purpose | Description of the payment link. Must be a unique
TYPE: STRING
EXAMPLE: Online Payment for Parking Ticket
|
| amount_option | Type of amount for payment link. Only accept a fixed or flexi 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"
TYPE: STRING
EXAMPLE: 100.55
|
| delivery_option | Allow checkout page to display the delivery form as mandatory fields.
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| due_date | Expiry date of the Payment Link.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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
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.
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: STRING
EXAMPLE: 1
|
| merchant_id |
Your merchant ID
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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.
TYPE: DATE
|
Report Collection Payment Link API
This API allows you to access a list collection of Payment Links.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| date_to | By default the date will be the date of last batch data.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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
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.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| date_to | By default the date will be the date of last batch data.
TYPE: DATE
EXAMPLE: 2024-11-21
|
| 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: STRING
EXAMPLE: R1001
|
| invoice |
Your invoice number
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: fixed
|
|
| subscription_id |
Unique ID for your subscription package
TYPE: STRING
EXAMPLE: FIXED001
|
|
| name |
Name of your subscription
TYPE: STRING
EXAMPLE: Monthly Subscription
|
|
| purpose |
Short description of the subscription
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)
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)
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| subscriber_details: | {id_number:value} |
Payer ID Number (Ex: IC Number)
TYPE: INTEGER
EXAMPLE: 950711251499
|
| subscriber_details: | {id_type:value} |
ID Number Type
TYPE: INTEGER
EXAMPLE: 1
|
| subscriber_details: | {name:value} |
Subscribers full name
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
|
| subscriber_details: | {reference_no:value} |
Your reference no
TYPE: INTEGER
EXAMPLE: 101
|
| subscriber_details: | {name:email} |
Subscriber's email
TYPE: STRING
EXAMPLE: john@domain.com
|
| subscriber_details: | {name:value} |
Subscriber's full name
TYPE: STRING
EXAMPLE: SHAHRUL IZWAN
|
| subscriber_details: | {phone:value} |
Subscriber's phone numberTYPE: STRING
EXAMPLE: 60123456789
|
| subscription_id |
Your subscription ID. Must created your subscription package to retrieved your subscription ID
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| page |
Page of the response data. By default the page is set to number 1.
TYPE: INTEGER
EXAMPLE: 2
|
| offset |
Maximum subscription display for each pages
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| subscription_id |
Unique ID for your subscription package
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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: STRING
EXAMPLE: R1001
|
| subscription_id |
Your Subscription ID
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| page |
Page of the response data. By default the page is set to number 1.
TYPE: INTEGER
EXAMPLE: 2
|
| offset |
Maximum subscription display for each pages
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| system_subscriber_id |
Unique ID for your subscription package
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.
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
- Create Verification URL for payer.
- 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
- Once verification is done, our system will send an email and callback data to your callback URL with the Token ID
- You may use the Token ID to initiate a payment by using the Charge Card API.
- For every successful payment (by token), please wait 5 minutes before making a new payment with the same token ID.
- 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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?TM48973303761",
"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?TM48973303761",
"created": "2021-04-19 12:40:34",
"modified": "2021-04-19 12:40:34"
}
| Field Name | Description |
|---|---|
| merchant_id |
Your merchant ID
TYPE: INTEGER
EXAMPLE: 10001
|
| reference_id |
Your unique reference ID
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| amount |
Amount to charge.
TYPE: STRING
EXAMPLE: 192.50
|
| invoice |
Unique reference number of this payment
TYPE: STRING
EXAMPLE: INV01
|
| callback_url_be |
Callback URL for your back-end process
TYPE: STRING
EXAMPLE: http://www.webina.me/callback
|
| callback_url_fe_succ |
Callback URL for your front-end successful transaction process
TYPE: STRING
EXAMPLE: http://www.webina.me/success
|
| callback_url_fe_fail |
Callback URL for your front-end failed transaction process
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
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
TYPE: STRING
EXAMPLE: REFERENCEID01
|
| txn_status |
Response code of the status of verification.* Refer Response Code table for description.
TYPE: STRING
EXAMPLE: 00
|
| msg |
Message status for verification
TYPE: STRING
EXAMPLE: Verification Approved
|
| token |
Unique ID for Card's Token
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
| schemeCard |
Card scheme
TYPE: STRING
EXAMPLE: MASTERCARD
|
| fundingMethodCard |
Card funding method
TYPE: STRING
EXAMPLE: CREDIT
|
| amount |
Amount of the first payment
TYPE: STRING
EXAMPLE: 121.50
|
| invoice |
Unique invoice number from the first payment
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| token |
Token ID that you received from your callback endpoint
TYPE: STRING
EXAMPLE: 1474809955578058
|
| invoice |
Your unique invoice number
TYPE: STRING
EXAMPLE: INV01
|
| amount |
Final amount to be paid by payer
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.
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)
TYPE: STRING
EXAMPLE: 00
|
| txn_status |
Status of the transaction
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
|
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| token |
Your unique reference ID or Token ID
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.
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)
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the data.
TYPE: INTEGER
EXAMPLE: 3
|
| page |
By default the page is set to number 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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token Reference ID
TYPE: STRING
EXAMPLE: REFID02
|
| verification_status |
Token verification status
TYPE: STRING
EXAMPLE: Success
|
| token |
Customer's Token ID.
TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
|
| 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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10010
|
| reference_id |
Your unique reference ID
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.
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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token Reference ID
TYPE: STRING
EXAMPLE: REFID02
|
| verification_status |
Token verification status
TYPE: STRING
EXAMPLE: Success
|
| token |
Customer's Token ID.
TYPE: STRING
EXAMPLE: 547b946bda42d20a35b6bas19231d3n13ud16f3
|
| 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
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
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the data.
TYPE: INTEGER
EXAMPLE: 3
|
| page |
By default the page is set to number 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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token 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
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10010
|
| invoice |
Your unique Invoice ID
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.
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)
TYPE: STRING
EXAMPLE: 00
|
| reference_id |
Token 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
TYPE: STRING
EXAMPLE: 00
|
| status |
Message status for transaction
TYPE: STRING
EXAMPLE: Payment Successful.
|
| credit_card_details |
Details of the customer's card
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
| token_list |
Your list of the generated token.
*Click on the image for a larger resolution Sample format for each detail:
Sample format for multiple payments:
TYPE: STRING
EXAMPLE: 0c671df1ad7419bea32204f0989e4522703045632ff
|
| batch_id |
Your unique Batch ID
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).
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.
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
TYPE: STRING
EXAMPLE: BATCH01
|
| token_list |
Your list of the generated token including payment status and error codes (if any)
*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.
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
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
TYPE: INTEGER
EXAMPLE: 10001
|
|
| batch_id |
Your unique Batch ID
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
|
Get Batch
Retrieve all submitted batches of data.
API Endpoint URLs
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last transaction data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| status |
By default the status will display all the status of the transactions.
TYPE: INTEGER
EXAMPLE: 1
|
| page |
By default the page is set to number 1.
TYPE: INTEGER
EXAMPLE: 2
|
Get Batch Details
Retrieve selected batch in details
API Endpoint URLs
- Production:
GET Please login to view the endpoint - Sandbox:
GET Please login to view the endpoint
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
TYPE: NUMBER
EXAMPLE: 10001
|
| batch_id |
Your unique Batch ID
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.
TYPE: STRING
EXAMPLE: dc8e364d222d6025cbc505674b701asdw
|
Get Settlement
You can retrieve all settlement records (successful transactions) for your account by calling this API.
API Endpoint URLs
- Production:
POST Please login to view the endpoint - Sandbox:
POST Please login to view the endpoint
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
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.
TYPE: STRING
|
Optional Arguments
| Field Name | Description |
|---|---|
| date_from |
By default the date will be the date of first settlement data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| date_to |
By default the date will be the date of last settlement data.
TYPE: STRING
EXAMPLE: 2020-07-17
|
| page |
By default the page is set to number 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:
- 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:
Before sorting
- Convert all the data into a single string and remove all spaces. Below is a sample of string of data:
- Encrypt the string of the data by using HMAC encryption method by using your API Key. Below is a sample code in PHP:
- 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.
$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",
]
1.50MYRINV1001R10005Parkingfee
hash_hmac('sha256', "1.50MYRINV1001R10005Parkingfee", "MYAPIKEY");
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
- Login into your WooCommerce Admin Panel using your WooCommerce login credentials.
- Go to the "Add Plugin" page by clicking on Plugins > Add New on the left side menu.
- Click on the "Upload Plugin" button and choose the downloaded
.zipfile. - 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.
- In the WooCommerce Admin Panel, click on "Settings".
- 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.