Bakong KHQR Developer API

Complete guide, interactive examples, and webhook reference for the Bakong KHQR reverse proxy integration.

បាគង / BAKONG / BAKONG KHQR Gateway Active

National Bank of Cambodia • Unified Payment System

This reverse-proxy integration forwards standard client queries securely to the Bakong KHQR gateway. It automatically handles encryption, signing, and verification, allowing your systems to check payment status instantly.

Base URLhttps://www.taskio.site/api/

Gateway ProtocolHTTPS / REST API

Auth PatternBearer API Token

Overview Authentication Endpoints Request & Response Webhooks Reference Error Codes Code Examples

Webhooks Reference

Setting up asynchronous transaction status callbacks.

Webhooks allow you to receive real-time POST events at your designated URL when transaction statuses update. We sign the request raw body with HMAC-SHA256, placing the signature in the x-taskio-signature header.

webhook.controller.ts

import { Controller, Post, Body, Req, Headers, UnauthorizedException, BadRequestException } from '@nestjs/common';
import * as crypto from 'crypto';

@Controller('bakong')
export class WebhookController {
    @Post('webhook')
    async handleWebhook(
        @Req() req: any,
        @Body() body: any,
        @Headers('x-taskio-signature') signature: string,
    ) {
        const webhookSecret = process.env.TASKIO_WEBHOOK_KEY;
        if (!webhookSecret) {
            throw new BadRequestException('Webhook secret is not configured.');
        }

        // IMPORTANT: Ensure rawBody is enabled in main.ts config:
        // const app = await NestFactory.create(AppModule, { rawBody: true });
        // And if you use manual body parser overrides, configure the verify callback:
        // app.use(bodyParser.json({ limit: '50mb', verify: (req, res, buf) => { req.rawBody = buf; } }));
        
        const rawBody = req.rawBody ? req.rawBody.toString('utf8') : JSON.stringify(body);
        const computedHex = crypto
            .createHmac('sha256', webhookSecret)
            .update(rawBody)
            .digest('hex');

        if (signature !== computedHex) {
            throw new UnauthorizedException('Invalid signature');
        }

        console.log('Taskio Webhook verified:', body);
        const { hash, amount, currency } = body;
        
        // Process payment success...
        return { success: true };
    }
}

Webhook Event Schema Sample

{
  "event": "transaction.checked",
  "timestamp": "2026-07-03T10:23:45.000Z",
  "hash": "8465d722d7d5065f2886f0a474a4d34dc6a7855355b611836f7b6111228893e9",
  "md5": "0b153b05f238b693eb14ea...",
  "billNumber": "BILL-10023",
  "externalRef": "REF-99231",
  "amount": 25.00,
  "currency": "USD",
  "description": "testing bakong generator",
  "data": {
    "responseCode": 0,
    "responseMessage": "Getting transaction successfully.",
    "data": {
      "hash": "8465d722d7d5065f2886f0a474a4d34dc6a7855355b611836f7b6111228893e9",
      "fromAccountId": "rieu_dhqj_1984@devb",
      "toAccountId": "bridge_account@devb",
      "currency": "USD",
      "amount": 25.00,
      "description": "testing bakong generator"
    }
  }
}