CHHEAN API Documentation

Base URL: https://api.kunchhunlichhean.org

All API requests must be made over HTTPS

API Overview

Authentication

All payment check endpoints require bakongid parameter for security validation.

Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

Rate Limiting

API requests are rate-limited to ensure service stability. Contact support for enterprise limits.

Error Handling

{
  "status": "ERROR",
  "message": "Description of the error",
  "details": "Additional error information"
}

Generate QR Code

GET /khqr/create

Description

Creates a new KHQR payment code for processing transactions. Returns QR code image URL, MD5 hash, and transaction ID.

Parameters

Parameter	Type	Required	Description
`amount`	number	Required	Payment amount in USD
`bakongid`	string	Required	Recipient Bakong account ID
`merchantname`	string	Required	Merchant display name

Response

200 OK

{
  "qr": "https://api.kunchhunlichhean.org/qr/AbC123xY",
  "md5": "e6c857f9bcf1d8e4158fe50c68099f3e",
  "tran": "AbC123xY",
  "amount": 5.00,
  "bakongAccountID": "yourbakong@id",
  "merchantName": "CHHEANSMM"
}

Check Payment Status by MD5

GET POST /check_by_md5

Description

Verify payment status using MD5 hash and BakongID. Returns complete transaction details from Bakong.

Parameters

Parameter	Type	Required	Description
`md5`	string	Required	MD5 hash from QR generation
`bakongid`	string	Required	Bakong account ID for validation

Example Request

GET /check_by_md5?md5=e6c857f9bcf1d8e4158fe50c68099f3e&bakongid=yourbakong@id

Response

200 OK

{
  "responseCode": 0,
  "responseMessage": "Success",
  "errorCode": null,
  "data": {
    "hash": "804184f08c9d0dc3f6d0f7cdd0af25c34b74472e27eb4d937abc9db7215c40ce",
    "fromAccountId": "wingkhppxxx@wing",
    "toAccountId": "yourbakong@id",
    "currency": "USD",
    "amount": 0.01,
    "description": "WG/PM/QR/0002454252220529",
    "createdDateMs": 1754763155000,
    "acknowledgedDateMs": 1754763156000,
    "trackingStatus": null,
    "receiverBank": null,
    "receiverBankAccount": null,
    "instructionRef": null,
    "externalRef": "0002454252220529"
  }
}

Error Responses

400 Bad Request

{
  "status": "ERROR",
  "message": "Both md5 and bakongid are required"
}

403 Forbidden

{
  "status": "ERROR",
  "message": "Unauthorized: bakongid mismatch"
}

404 Not Found

{
  "status": "ERROR",
  "message": "Transaction not found"
}

Check Payment Status by Transaction ID

GET POST /check/:tran_id

Description

Alternative method to check payment status using internal transaction ID with BakongID validation.

Parameters

Parameter	Type	Required	Description
`tran_id`	string	Required	Transaction ID from QR generation (URL parameter)
`bakongid`	string	Required	Bakong account ID for validation

Example Request

GET /check/AbC123xY?bakongid=yourbakong@id

Integration Examples

Complete Payment Flow

Step 1: Generate QR Code

curl -X GET "https://api.kunchhunlichhean.org/khqr/create?amount=5&bakongid=yourbakong@id&merchantname=CHHEANSMM"

Step 2: Poll Payment Status

curl -X GET "https://api.kunchhunlichhean.org/check_by_md5?md5=YOUR_MD5&bakongid=yourbakong@id"

JavaScript Example

// Generate QR Code
const createQR = async (amount, bakongid, merchantname) => {
  const response = await fetch(
    `https://api.kunchhunlichhean.org/khqr/create?amount=${amount}&bakongid=${bakongid}&merchantname=${merchantname}`
  );
  return await response.json();
};

// Check Payment Status
const checkPayment = async (md5, bakongid) => {
  const response = await fetch(
    `https://api.kunchhunlichhean.org/check_by_md5?md5=${md5}&bakongid=${bakongid}`
  );
  const data = await response.json();
  return data.responseCode === 0; // true if paid
};

// Usage
const qrData = await createQR(5, "yourbakong@id", "CHHEANSMM");
const isPaid = await checkPayment(qrData.md5, "yourbakong@id");

Python Example

import requests
import time

def create_qr(amount, bakongid, merchantname):
    url = f"https://api.kunchhunlichhean.org/khqr/create"
    params = {
        "amount": amount,
        "bakongid": bakongid,
        "merchantname": merchantname
    }
    response = requests.get(url, params=params)
    return response.json()

def check_payment(md5, bakongid):
    url = f"https://api.kunchhunlichhean.org/check_by_md5"
    params = {
        "md5": md5,
        "bakongid": bakongid
    }
    response = requests.get(url, params=params)
    data = response.json()
    return data.get("responseCode") == 0

# Usage
qr_data = create_qr(5, "yourbakong@id", "CHHEANSMM")
md5 = qr_data["md5"]

# Poll for payment (check every 10 seconds for 3 minutes)
for i in range(18):
    if check_payment(md5, "yourbakong@id"):
        print("Payment confirmed!")
        break
    time.sleep(10)
else:
    print("Payment timeout")