KLiCKPAY Merchant Integration Guide

Overview

Call KLiCKPAY from your server only. Base URL https://pay.klicksev.net

Before integration, send KLiCKPAY:

Your server outgoing IP, for the whitelist
Your RSA public key only

Integration requires you to provide an RSA Public Key (1024 bit). It can be generated from the following web page (https://travistidwell.com/jsencrypt/demo/).

Send only RSA Public Key. Keep the private key to generate signature in codes.

KLiCKPAY then gives you:

Merchant code — the MerchantCode on every call
AES key — encrypt and decrypt the Data parameter
KLiCKPAY RSA public key — verify KLiCKPAY’s signature on the response and on the callback

Production site: klicksev.net. Reply the text success when KLiCKPAY calls your Notify URL or payout verification URL.

Callback IP

KLiCKPAY sends callbacks (NotifyUrl) and payout verification (ReturnUrl) from IP 34.87.162.255. Add it to your firewall allowlist, and still verify the Signature.

Key	Who creates it	Who keeps it	Use
AES key	KLiCKPAY	You and KLiCKPAY	Encrypt and decrypt `Data`
Merchant RSA private key	You	Your server only	Sign each request
Merchant RSA public key	You	Send to KLiCKPAY	KLiCKPAY verifies your signature
KLiCKPAY RSA public key	KLiCKPAY	You	Verify KLiCKPAY’s signature
KLiCKPAY RSA private key	KLiCKPAY	KLiCKPAY only	KLiCKPAY signs the callback

Call format

Every POST uses Content-Type: application/json. Version is 0.

Submit Deposit uses this JSON. The other calls use the same fields with a capital first letter: MerchantCode, Data, Signature, Version.

{
  "merchantCode": "VND00001",
  "data": "<base64>",
  "signature": "<base64>",
  "version": 0
}

Sign the exact JSON string inside Data, then encrypt that same string. AES is AES-256-CBC. The signature is RSA-SHA1. The Encryption tab has the steps.

Submit Deposit

POST /api/Deposit/SubmitDeposit

Plaintext inside Data

{
  "MerchantCode": "VND00001",
  "MerchantTransactionId": "Test0001",
  "MerchantClientId": "Member0001",
  "CurrencyCode": "VND",
  "Amount": 100000,
  "NotifyUrl": "https://api.example.com/notify",
  "ReturnUrl": "https://api.example.com/return",
  "IPAddress": "192.168.0.1",
  "PaymentMethodCode": "BQR"
}

Field	Required	Notes
`MerchantCode`	yes	Merchant account code. Example: `VND00001`
`MerchantTransactionId`	yes	Your deposit order id. Example: `20230525033836`
`MerchantClientId`	yes	Your client id. Example: `Testing`
`CurrencyCode`	yes	Example: `VND`
`Amount`	yes	Number, min 100,000 max 200,000,000
`NotifyUrl`	yes	Server callback URL
`ReturnUrl`	yes	Browser return URL
`IPAddress`	yes	Payer IP. Example: `192.168.0.1`
`PaymentMethodCode`	yes	See Payment Methods. Example: `BQR`
`AccountHolderName`	no	Depositor name

What you receive

{
  "isSuccess": true,
  "successCode": 200,
  "errorMessage": "",
  "errorList": null,
  "data": {
    "transactionId": "D2023111111111111",
    "url": "https://pay.klicksev.net/m/deposit/D2023111111111111",
    "bankCode": "ACB",
    "accountNumber": "01111111",
    "accountHolderName": "TEST",
    "referenceNo": "920111",
    "qrCode": "000201010212...",
    "depositActualAmount": 100000,
    "deepLink": null
  }
}

Field	Notes
`transactionId`	KLiCKPAY deposit id
`url`	Pay page. Open this for the payer.
`bankCode`	Receiving bank. Empty means use `url`.
`accountNumber`	Receiving account
`accountHolderName`	Receiving account name
`referenceNo`	Payer must enter this on a bank or e-wallet deposit
`qrCode`	QR image, base64
`depositActualAmount`	Amount to pay
`deepLink`	Not used for VND. The value is `null`.

A failed call uses HTTP 400. errorList holds errorCode and errorDescription.

Deposit Callback

KLiCKPAY POSTs this envelope to NotifyUrl. Reply the text success or KLiCKPAY keeps calling.

Sent from IP 34.87.162.255. Allow it in your firewall and still verify the Signature.

{
  "TransactionId": "D2023111111111111",
  "MerchantTransactionId": "TEST0001",
  "Data": "<base64>",
  "AdditionalInformationData": "<base64>",
  "Signature": "<base64>",
  "Version": 0
}

Decrypt Data

Field	Required	Notes
`MerchantCode`	yes	Merchant account code
`CurrencyCode`	yes	Example: `VND`
`MerchantTransactionId`	yes	Your deposit order id
`Status`	yes	Deposit status id. See Status.
`Amount`	yes	Number, min 100,000 max 200,000,000
`NetAmount`	yes	Net amount from the payer
`Remark`	no	Remark
`PaymentMethodCode`	yes	Payment method
`BankReferenceNo`	no	Transfer content the payer must use.
`UniqueReferenceNo`	no	Unique reference

Decrypt AdditionalInformationData

Field	Required	Notes
`UPIID`	no	Not used for VND.
`BankAccountNumber`	no	Receiving account
`BankAccountName`	no	Receiving account name
`BankCode`	no	Receiving bank

Deposit Requery

POST /api/Deposit/GetDepositDetail

Plaintext inside Data

{
  "MerchantCode": "VND00001",
  "MerchantTransactionId": "Test0001",
  "CurrencyCode": "VND"
}

Decrypt data

{
  "transactionId": "D2023111111111111",
  "merchantTransactionId": "Test0001",
  "statusId": 6,
  "status": "Success",
  "amount": 100,
  "netAmount": 98.5,
  "paymentMethodCode": "BQR"
}

bankReferenceNo and uniqueReferenceNo may also be present. Finished when statusId is 6 or 7.

Submit Withdrawal

POST /api/Withdrawal/SubmitWithdrawal

Field	Required	Notes
`MerchantCode`	yes	Merchant account code
`MerchantTransactionId`	yes	Your payout id
`MerchantClientId`	yes	Your client id
`CurrencyCode`	yes	Example: `VND`
`Amount`	yes	Number, min 100,000 max 200,000,000
`DestinationClientBankCode`	yes	Bank code. Example: `ACB`. See the bank list.
`DestinationClientAccountNumber`	yes	Account number
`DestinationClientAccountHolderName`	yes	Account name
`DestinationClientProvince`	no	Province
`DestinationClientCity`	no	City
`DestinationClientBranch`	no	Branch
`NotifyUrl`	yes	Server callback URL
`ReturnUrl`	verification only	Required when you use Payout Verification
`IPAddress`	yes	Client IP
`PaymentMethodCode`	yes	`WD`
`DestinationClientBranchCode`	no	Not used for VND payouts.

What you receive

{
  "isSuccess": true,
  "successCode": 200,
  "errorMessage": "",
  "errorList": null,
  "data": { "transactionId": "W2023111111111111" }
}

transactionId is the KLiCKPAY withdrawal id.

Withdrawal Callback

KLiCKPAY POSTs this envelope to NotifyUrl. Reply the text success.

Sent from IP 34.87.162.255. Allow it in your firewall and still verify the Signature.

{
  "TransactionId": "W2023111111111111",
  "MerchantTransactionId": "Test0001",
  "Data": "<base64>",
  "Signature": "<base64>",
  "Version": 0
}

Decrypt Data

Field	Required	Notes
`MerchantCode`	yes	Merchant account code
`CurrencyCode`	yes	Example: `VND`
`MerchantTransactionId`	yes	Your payout id
`Status`	yes	Withdrawal status id. See Status.
`Amount`	yes	Number, min 100,000 max 200,000,000
`NetAmount`	yes	Net amount
`Remark`	no	Remark
`PaymentMethodCode`	yes	Payment method
`BankReferenceNo`	no
`UniqueReferenceNo`	no

Payout Verification

KLiCKPAY POSTs this to ReturnUrl before it pays. Reply the text success to continue. Any other reply rejects the withdrawal at once.

Sent from IP 34.87.162.255. Allow it in your firewall and still verify the Signature.

{
  "MerchantCode": "TEST",
  "Data": "<base64>",
  "AdditionalInformationData": "<base64>",
  "Signature": "<base64>"
}

Decrypt Data

Field	Required	Notes
`MerchantTransactionId`	yes	Your payout id
`Amount`	yes	Number, min 100,000 max 200,000,000
`CurrencyCode`	yes	Example: `VND`

Decrypt AdditionalInformationData

Field	Required	Notes
`DestinationClientBankCode`	yes	Bank code
`DestinationClientAccountNumber`	yes	Account number
`DestinationClientAccountHolderName`	yes	Account name
`DestinationClientBranchCode`	no	Not used for VND payouts.

Withdrawal Requery

POST /api/Withdrawal/GetWithdrawalDetail

{
  "MerchantCode": "VND00001",
  "MerchantTransactionId": "Test0001",
  "CurrencyCode": "VND"
}

Decrypt data

{
  "transactionId": "W2023111111111111",
  "merchantTransactionId": "Test0001",
  "statusId": 4,
  "status": "Success",
  "amount": 100,
  "netAmount": 101.5,
  "paymentMethodCode": "WD"
}

Finished when statusId is 4 or 5.

CheckBalance

POST /api/Merchant/CheckBalance

Plaintext inside Data

{
  "MerchantCode": "VND00001",
  "CurrencyCode": "VND"
}

Decrypt data

{
  "merchantCode": "VND00001",
  "currencyCode": "VND",
  "currentBalance": 10000.00,
  "availableBalance": 10000.00
}

GetSupportedBank

GET /api/Bank/GetSupportedBanks

This call is not encrypted. PaymentMethodCode is WD.

https://pay.klicksev.net/api/Bank/GetSupportedBanks?MerchantCode=VND00001&PaymentMethodCode=WD&CurrencyCode=VND

data is a list. Use bankCode as DestinationClientBankCode.

{
  "bankName": "ACB (Asia Commercial Bank)",
  "bankNameOrigin": "Ngân hàng TMCP Á Châu",
  "bankCode": "ACB",
  "currencyCode": "VND",
  "merchantCode": "VND00001"
}

AES

Algorithm: AES-256-CBC
Build the key with PBKDF2-HMAC-SHA1: password and salt are both the AES key string, 1000 rounds, 32 bytes
Data: base64 of IV (16 bytes) + ciphertext
Padding: PKCS7
A new random IV is used for every Data value

const crypto = require('crypto');

function derivedKey(aesKey) {
  return crypto.pbkdf2Sync(aesKey, aesKey, 1000, 32, 'sha1');
}

function encryptData(obj) {
  const key = derivedKey(AES_KEY);
  const plain = JSON.stringify(obj);
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  const body = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
  return { plain, data: Buffer.concat([iv, body]).toString('base64') };
}

function decryptData(data) {
  const key = derivedKey(AES_KEY);
  const raw = Buffer.from(data, 'base64');
  const decipher = crypto.createDecipheriv('aes-256-cbc', key, raw.subarray(0, 16));
  const text = Buffer.concat([decipher.update(raw.subarray(16)), decipher.final()]).toString('utf8');
  return JSON.parse(text);
}

Form Encrypted Data

Convert the inner fields to one JSON string. Encrypt that string with the AES key from KLiCKPAY. Put the base64 result in Data.

{
  "MerchantCode": "VND00001",
  "MerchantTransactionId": "Test0001",
  "MerchantClientId": "Member0001",
  "CurrencyCode": "VND",
  "Amount": 100000,
  "NotifyUrl": "https://api.example.com/notify",
  "ReturnUrl": "https://api.example.com/return",
  "IPAddress": "192.168.0.1",
  "PaymentMethodCode": "BQR"
}

Sign this same string. Do not build the JSON a second time.

Decrypt Encrypted Data

Base64-decode Data. The first 16 bytes are the IV. Decrypt the rest with AES-256-CBC and the derived key. The result is JSON.

{
  "MerchantCode": "VND00001",
  "CurrencyCode": "VND",
  "MerchantTransactionId": "Test0001",
  "Status": 4,
  "Amount": 100,
  "NetAmount": 101.3,
  "Remark": "Success",
  "PaymentMethodCode": "WD"
}

RSA

Algorithm: RSA-SHA1 (SHA1withRSA)
Sign the exact JSON string inside Data, not the base64 ciphertext
Use your merchant RSA private key (PKCS#8)
signature is base64
KLiCKPAY checks it with the RSA public key you provided

Callbacks use the same envelope. Verify Signature with the KLiCKPAY RSA public key, then decrypt Data.

function signData(plain) {
  return crypto.createSign('RSA-SHA1').update(plain, 'utf8').sign(merchantPrivatePem, 'base64');
}

function verifyKLiCKPAY(plain, signature) {
  return crypto.createVerify('RSA-SHA1').update(plain, 'utf8').verify(klickPayPublicPem, signature, 'base64');
}

Payment Methods

Code	Name	Currency
`BQR`	QR code	VND
`BTR`	Bank transfer	VND
`MOMO`	Momo	VND
`ZALO`	Zalo	VND
`VTP`	ViettelPay	VND
`WD`	Payout	All

Payout (WD) VND Bank

The live list is GetSupportedBanks. These are the WD codes for VND.

Code	English name	Origin name
`ABB`	ABBank (An Binh Bank)	Ngân hàng TMCP An Bình
`ACB`	ACB (Asia Commercial Bank)	Ngân hàng TMCP Á Châu
`AGR`	Agribank	Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam
`BAB`	Bac A Bank	Ngân hàng TMCP Bắc Á
`BIDV`	BIDV (Joint Stock Commercial Bank for Investment and Development of Vietnam)	Ngân hàng TMCP Đầu tư và Phát triển Việt Nam
`BVB`	BaoVietBank	Ngân hàng TMCP Bảo Việt
`BVBANK`	Ban Viet Bank	Ngân hàng TMCP Bản Việt
`CAKE`	CAKE by VPBank	Ngân hàng số CAKE by VPBank
`CIMB`	CIMB Bank	Ngân hàng TNHH MTV CIMB Việt Nam
`EXI`	Eximbank	Ngân hàng TMCP Xuất Nhập khẩu Việt Nam
`GPB`	GPBank	Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu
`HDB`	HDBank	Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh
`HLBVN`	Hong Leong	Ngân hàng TNHH MTV Hong Leong Việt Nam
`HSBC`	HSBC Viet Nam	Ngân hàng TNHH MTV HSBC (Việt Nam)
`IVB`	Indovina Bank	Ngân hàng TNHH Indovina
`KLB`	Kien Long Bank	Ngân hàng TMCP Kiên Long
`LPB`	LPBank	Ngân hàng TMCP Lộc Phát Việt Nam
`MB`	MB Bank (Military Commercial Joint Stock Bank)	Ngân hàng TMCP Quân đội
`MBV`	MBV (Modern Bank of Vietnam Limited)	Ngân hàng TNHH MTV Việt Nam Hiện Đại
`MSB`	MSB (Maritime Bank)	Ngân hàng TMCP Hàng Hải Việt Nam
`NAB`	NamABank	Ngân hàng TMCP Nam Á
`NCB`	NCB (National Citizen Bank)	Ngân hàng TMCP Quốc Dân
`OCB`	OCB (Orient Commercial Joint Stock Bank)	Ngân hàng TMCP Phương Đông
`OCBC`	OCBC (Oversea-Chinese Banking Corporation Limited - HCMC branch)	Ngân hàng OCBC
`PBVN`	Public Bank	Ngân hàng TNHH MTV Public Việt Nam
`PGB`	PGBank (Prosperity and Growth Bank)	Ngân hàng TMCP Thịnh vượng và Phát triển
`PVCB`	PVcomBank	Ngân hàng TMCP Đại Chúng Việt Nam
`SCB`	SCB (Sai Gon Joint Stock Commercial Bank)	Ngân hàng TMCP Sài Gòn
`SCVN`	StanChart (Standard Chartered Bank Vietnam)	Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam
`SEAB`	SEABANK (SouthEast Asia Bank)	Ngân hàng TMCP Đông Nam Á
`SGB`	SaigonBank	Ngân hàng TMCP Sài Gòn Công Thương
`SHB`	SHB (Saigon - Hanoi Commercial Joint Stock Bank)	Ngân hàng TMCP Sài Gòn - Hà Nội
`SHBVN`	ShinhanBank	Ngân hàng TNHH MTV Shinhan Việt Nam
`STB`	Sacombank	Ngân hàng TMCP Sài Gòn Thương Tín
`TCB`	Techcombank	Ngân hàng TMCP Kỹ thương Việt Nam
`TIMO`	Timo by BVBank	Ngân hàng số Timo by Ban Viet Bank (Timo by Ban Viet Bank)
`TPB`	TPBank (TienPhongBank)	Ngân hàng TMCP Tiên Phong
`UOB`	UOB Vietnam	Ngân hàng TNHH MTV UOB Việt Nam
`VAB`	VietABank	Ngân hàng TMCP Việt Á
`VBSP`	VBSP (Vietnam Bank for Social Policies)	Ngân hàng Chính sách Xã hội
`VCB`	Vietcombank	Ngân hàng TMCP Ngoại Thương Việt Nam
`VCBN`	VCBNeo (Vietcombank Neo Bank Limited)	Ngân hàng Thương mại TNHH MTV Ngoại thương Công nghệ số (VCBNeo)
`VIB`	VIB (Vietnam International Bank)	Ngân hàng TMCP Quốc tế Việt Nam
`VIETBANK`	VietBank (Vietnam Thuong Tin Bank)	Ngân hàng TMCP Việt Nam Thương Tín
`VIKKI`	Vikki Bank	Ngân hàng TNHH một thành viên Số Vikki
`VIKKIHD`	Vikki by HDBank	Ngân hàng Vikki by HDBank
`VPB`	VPBank (Vietnam Prosperity Bank)	Ngân hàng TMCP Việt Nam Thịnh Vượng
`VRB`	VRB (Vietnam - Russia Joint Venture Bank)	Ngân hàng Liên doanh Việt - Nga
`VTB`	VietinBank	Ngân hàng TMCP Công thương Việt Nam
`WVN`	Woori Bank Vietnam	Ngân hàng TNHH MTV Woori Việt Nam

Transaction Status

Deposit Status

statusId	Result
`6`	Success
`7`	Fail
any other value	Processing

Withdrawal Status

statusId	Result
`4`	Success
`5`	Fail
any other value	Processing

Error Appendix

A failed request returns JSON. errorList[].errorCode is the error code.

{
  "isSuccess": false,
  "successCode": 400,
  "errorMessage": "",
  "errorList": [
    {
      "errorCode": "KLK10000",
      "errorDescription": "Duplicate Merchant Reference Number."
    }
  ]
}

Deposit validation failure uses HTTP 400. errorMessage is a general exception when errorList is empty.

Error code	Error description
`KLK10000`	Duplicate Merchant Reference Number.
`KLK10001`	Invalid Bank Code.
`KLK10002`	Bank account not available.
`KLK10003`	Merchant Transaction Setting not available.
`KLK10004`	Company Bank account not exists.
`KLK10005`	Invalid Transaction Amount.
`KLK10006`	Invalid Payment Method.
`KLK10007`	Merchant Cashier URL not available.
`KLK10008`	Invalid Bank Account Number.
`KLK10009`	Invalid Bank Account Holder Name.
`KLK10010`	Invalid Province.
`KLK10011`	Invalid City.
`KLK10012`	Invalid Branch.
`KLK10013`	Insufficient Balance.
`KLK10014`	Channel Error.
`KLK10015`	Payment Method Group Setting Limit Error.
`KLK10016`	Merchant Reference ID is not exist.
`KLK10017`	Channel is not exist.
`KLK10018`	Channel is not available.
`KLK10019`	Invalid IFS Code.
`KLK10020`	Invalid Merchant.
`KLK10021`	Failed to generate Unique Amount.
`KLK10022`	Merchant Reference ID or Payment Transaction ID is not exist.
`KLK10023`	UTR Number exists, cannot be updated.
`KLK10024`	Invalid Payment Method Routing Amount.
`KLK10025`	Not support decimal amount.
`KLK10026`	Intra bank account not available.
`KLK10027`	Fail Payout Verification.
`KLK99999`	General System Error.

KLiCKPAY

Overview

Callback IP

Call format

Submit Deposit

Plaintext inside Data

What you receive

Deposit Callback

Decrypt Data

Decrypt AdditionalInformationData

Deposit Requery

Plaintext inside Data

Decrypt data

Submit Withdrawal

What you receive

Withdrawal Callback

Decrypt Data

Payout Verification

Decrypt Data

Decrypt AdditionalInformationData

Withdrawal Requery

Decrypt data

CheckBalance

Plaintext inside Data

Decrypt data

GetSupportedBank

AES

Form Encrypted Data

Decrypt Encrypted Data

RSA

Form Signature

Verify Signature

Payment Methods

Payout (WD) VND Bank

Transaction Status

Deposit Status

Withdrawal Status

Error Appendix