Download Mobile App

• Bakong App ( App Store | Play Store )
• Bakong Tourists ( App Store | Play Store )

Requirement

• Node.js >= 14.0.0
• A Bakong account with full KYC verification
• A Bakong developer token (register here: https://api-bakong.nbc.gov.kh/register)
• A VPS or hosting service located in Cambodia (a Cambodian IP address is recommended)

Installation

npm install bakong-khqr-npm

or using yarn:

yarn add bakong-khqr-npm

or Update Last Version

npm install --upgrade bakong-khqr-npm

Usage

The bakong-khqr-npm package provides the KHQR class for generating QR code, Deeplink, Check Payment, Get Payment transaction for Bakong KHQR.

Importing the package

You can import the KHQR class from the package as follows:

TypeScript:

import { KHQR } from 'bakong-khqr-npm';

JavaScript (CommonJS):

const { KHQR } = require('bakong-khqr-npm');

JavaScript (ES Modules):

import { KHQR } from 'bakong-khqr-npm';

Creating Payment Transaction

To generate QR code data for a transaction, create an instance of the KHQR() class with Bakong Token and call the:

• create_qr() method with the required parameters.
• generate_deeplink() method with the required parameters.
• generate_md5() method with the required parameters.
• check_payment() method with the required parameters.
• get_payment() method with the required parameters.
• check_bulk_payments() method with the required parameters.

Example:

import { KHQR } from 'bakong-khqr-npm';

// Create an instance of KHQR with Bakong Developer Token:
const khqr = new KHQR("eyJhbGciOiJIUzI1NiIsI...nMhgG87BWeDg9Lu-_CKe1SMqC0");

// Generate QR code data for a transaction:
const qr = khqr.create_qr({
  bank_account: 'user_name@bank', // Check your user_name@bank under Bakong profile (Mobile App)
  merchant_name: 'Your Name',
  merchant_city: 'Phnom Penh',
  amount: 9800, // 9800 Riel
  currency: 'KHR', // USD or KHR
  store_label: 'MShop',
  phone_number: '85512345678',
  bill_number: 'TRX01234567',
  terminal_label: 'Cashier-01',
  static: false // Static or Dynamic QR code (default: false)
});

console.log(qr);
// String Result: 00020101021229180014user_name@bank520459995802KH5909Your Name6010Phnom Penh991700131724927295157541100000009800530311662610112TRX0192837750211855123456780305MShop0717Buy 1A_Level_Book63041087

// Generate Deeplink:
const deeplink = await khqr.generate_deeplink(
  qr,
  "https://your_website.com/shop/details?q=ABC", // Or your app's custom scheme (e.g., mshop://purchase/39482)
  "https://your_website.com/images/logo.png", // Your logo image .png or .svg
  "MyAppName" // (e.g., MSHOP)
);

console.log(deeplink);
// String Result: https://bakong.page.link/CgXb....ks6az9a38

// Get Hash MD5
const md5 = khqr.generate_md5(qr);
console.log(md5);
// String Result: dfcabf4598d1c405a75540a3d4ca099d

// Check Transaction paid or unpaid:
const payment_status = await khqr.check_payment(md5);
console.log(payment_status);
// String Result: "UNPAID"
// Indicates that this transaction has not yet been paid.

// Retrieve the payment information:
// e.g. In case static QR code (static=true) is used for payment, and the amount is not known from the user's input.
const payment_info = await khqr.get_payment(md5);
console.log(payment_info);
// Object Result:
// {
//     "hash": "a7121ca103c.....eb3671b9601a6",
//     "fromAccountId": "bankkhppxxx@bank",
//     "toAccountId": "your_name@bank",
//     "currency": "KHR",
//     "amount": "9800",
//     "description": "Cashier-01",
//     "createdDateMs": 1739953000,
//     "acknowledgedDateMs": 1739954000,
//     "trackingStatus": null,
//     "receiverBank": null,
//     "receiverBankAccount": null,
//     "instructionRef": null,
//     "externalRef": "100FT36550298"
// }
// You can retrieve information such as the amount to integrate into your system.

// Check Bulk Transactions:
const md5_list = [
  "dfcabf4598d1c405a75540a3d4ca099d", 
  "5154e4f795634ff1a0ae4b48e53a6d9c",
  "a57d9bb85f52f12a20cf7beecb03d11d",
  "495fdaec0be5d94c89bc1283c7283d3d",
  "31bca02094ad576588e42b60db57bc98"
];

const bulk_payments_status = await khqr.check_bulk_payments(md5_list);
console.log(bulk_payments_status);
// Array Result: ["5154e4f795634ff1a0ae4b48e53a6d9c", "495fdaec0be5d94c89bc1283c7283d3d"]
// Returns an array containing only the MD5 hashes that correspond to successful (paid) transactions.

⚠️ Bulk Transaction Check Limit

The Bakong API allows a maximum of 50 MD5 hashes per request when using the check_bulk_payments() method. If you pass more than 50 hashes, the function will throw an error to prevent unexpected API errors.

const md5_list = [md5_1, md5_2, ..., md5_51]; // 51 hashes

// This will throw:
// Error: The md5_list exceeds the allowed limit of 50 hashes per request.
const result = await khqr.check_bulk_payments(md5_list);

// ✅ If you need to check more than 50 transactions, you must handle chunking manually:
function chunked<T>(array: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size));
  }
  return chunks;
}

const all_md5 = [...]; // more than 50 md5 hashes
const paid_md5: string[] = [];

for (const batch of chunked(all_md5, 50)) {
  const paid = await khqr.check_bulk_payments(batch);
  paid_md5.push(...paid);
}

console.log(paid_md5);
// Array Result: ["5154e4f795634ff1a0ae4b48e53a6d9c", "495fdaec0be5d94c89bc1283c7283d3d"]
// Returns an array containing only the MD5 hashes that correspond to successful (paid) transactions.

API Reference

new KHQR(bakongToken?, apiBaseUrl?)

Create a new KHQR instance.

Parameters:

• bakongToken (string, optional): Bakong Developer Token. Required for API calls.
• apiBaseUrl (string, optional): Bakong API base URL. Default: https://api-bakong.nbc.gov.kh

create_qr(params)

Generate QR code string for a transaction.

Parameters:

• params.bank_account (string, required): The bank account associated with the transaction (e.g., user_name@bank).
• params.merchant_name (string, required): Name of the merchant (max 25 characters).
• params.merchant_city (string, required): City where the merchant is located (max 15 characters).
• params.amount (number, required): Amount to be transacted.
• params.currency (string, required): Currency of the transaction ('USD' or 'KHR').
• params.store_label (string, optional): Label or name of the store (max 25 characters).
• params.phone_number (string, optional): Contact phone number (max 25 characters).
• params.bill_number (string, optional): Reference number for the bill (max 25 characters).
• params.terminal_label (string, optional): Label for the terminal (max 25 characters).
• params.static (boolean, optional): Static or Dynamic QR code (default: false).

Returns: string - Generated QR code string.

Note: Using static mode will create a Static QR Code for payment, allowing unlimited transactions, usage, and a zero amount included.

generate_md5(qr)

Generate an MD5 hash for the QR code.

Parameters:

• qr (string, required): QR code string generated from create_qr() method.

Returns: string - MD5 hash as a string (32 characters).

generate_deeplink(qr, callback?, appIconUrl?, appName?)

Generate a deep link for the QR code.

Parameters:

• qr (string, required): QR code string generated from create_qr() method.
• callback (string, optional): Deeplink URL for opening your app after payment is completed. Default: https://bakong.nbc.org.kh
• appIconUrl (string, optional): Your App Icon URL. Default: https://bakong.nbc.gov.kh/images/logo.svg
• appName (string, optional): Your App Name. Default: MyAppName

Returns: Promise<string | null> - Deep link URL as a string, or null if failed.

check_payment(md5)

Check the transaction status based on the MD5 hash.

Parameters:

• md5 (string, required): MD5 hash of the QR code generated from generate_md5() method.

Returns: Promise<'PAID' | 'UNPAID'> - Transaction status as a string.

get_payment(md5)

Retrieve information about a paid transaction based on MD5 hash.

Parameters:

• md5 (string, required): MD5 hash of the QR code generated from generate_md5() method.

Returns: Promise<TransactionData | null> - A object containing the transaction information if paid, or null if the transaction is not paid.

check_bulk_payments(md5_list)

Check the transaction status based on the list of MD5 hashes.

Parameters:

• md5_list (string[], required): Array of MD5 hashes generated from generate_md5() method. Maximum 50 hashes.

Returns: Promise<string[]> - Array of MD5 hashes that correspond to successful (paid) transactions.

Throws: Error - If the md5_list exceeds 50 items.

Bakong Official

KHQR SDK Documentation:

• https://api-bakong.nbc.gov.kh/document
• KHQR Content Guideline v1.4.pdf
• QR Payment Integration.pdf
• KHQR SDK Document.pdf

Development API: https://sit-api-bakong.nbc.gov.kh/

Production API: https://api-bakong.nbc.gov.kh/

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

If you would like to contribute to this project, please fork the repository and submit a pull request.

Contact

For any questions or feedback, please open an issue on GitHub.