Bakong Technical Integration Guide for Enterprise Developers

The Bakong payment infrastructure operates as a four-tier architecture with distinct access levels, capabilities, and security requirements at each tier. The NBC operates Tier 1 with full administrative control over the Hyperledger Iroha ledger, including node management, consensus configuration, and system-wide policy enforcement. Tier 2 comprises licensed commercial banks that connect to the Bakong Open API gateway via dedicated network links with mutual TLS authentication. Tier 3 includes licensed payment service providers (PSPs) and microfinance institutions with restricted API access for e-wallet operations and merchant services. Tier 4 represents enterprises and merchants that access Bakong indirectly through their bank partner's API. For enterprise developers, the practical integration surface is the bank partner's API, which wraps Bakong primitives in a bank-specific interface. While API specifications vary between banks, the NBC has published standardized message formats and error codes that banks must implement consistently. CamFinTech maintains a compatibility matrix across major Cambodian banks to help enterprises select partners with the most mature and well-documented APIs.

Bakong enforces layered security at every integration tier. At the network level, all Bakong API traffic traverses dedicated VPN tunnels or MPLS circuits between participating institutions and the NBC data center. At the transport level, mutual TLS (mTLS) with X.509 certificates issued by the NBC's Certificate Authority ensures both client and server authentication. At the application level, OAuth 2.0 with client credentials flow provides authorization tokens scoped to specific API operations. For Tier 4 enterprises, security requirements are defined by the bank partner but must meet NBC minimum standards. These include: TLS 1.2 or higher for all API communication, API key rotation at minimum every 90 days, IP whitelist restrictions for production API access, webhook signature verification using HMAC-SHA256, and PCI DSS Level 2 or higher for merchants handling card-based payment data. Enterprise developers should implement a secrets management system (HashiCorp Vault, AWS Secrets Manager, or equivalent) to handle API keys, certificates, and webhook signing keys across development, staging, and production environments. The NBC conducts annual security assessments of Tier 2 and Tier 3 participants and requires vulnerability remediation within 30 days of findings. Tier 4 enterprises are subject to their bank partner's security requirements, which typically include SOC 2 Type II compliance or equivalent for high-volume integrations.

KHQR (Khmer QR) is the NBC-standardized QR code protocol built on the EMVCo QR Code Specification for Payment Systems (EMV QRCPS). Every KHQR code encodes a structured data payload using Tag-Length-Value (TLV) format, containing the merchant identifier, acquiring institution code, transaction amount (for dynamic codes), currency code, merchant name and city, and additional data fields for invoice references or loyalty program identifiers. The payment flow for a KHQR transaction follows a defined sequence. The merchant system generates a KHQR code (static or dynamic) and displays it to the customer. The customer scans the code using any Bakong-connected banking app. The customer's banking app decodes the TLV payload, displays transaction details for confirmation, and upon user approval, submits the payment to the originating bank's core system. The bank forwards the transaction to the Bakong switch, which validates, debits the payer, credits the beneficiary, and records the settlement on the Iroha ledger. The beneficiary bank notifies the merchant system via webhook. Dynamic KHQR codes include a transaction-specific reference number and expiration timestamp, enabling automated reconciliation. CamFinTech recommends using dynamic codes for all e-commerce and invoicing scenarios, as they eliminate manual amount entry errors and enable real-time payment matching against accounting systems.

Every Bakong transaction transitions through a defined set of states from initiation to final settlement. Understanding these states is critical for building robust payment systems that handle edge cases correctly. The lifecycle begins with INITIATED when the payer's banking app submits the payment request. The Bakong switch validates the request and transitions to VALIDATED, confirming that both accounts exist, the payer has sufficient funds, and the transaction passes AML/CFT screening rules. Upon successful validation, the system atomically debits the payer and credits the beneficiary, transitioning to SETTLED. This state is final and irrevocable for domestic transactions. The beneficiary bank receives a settlement notification and must acknowledge receipt within 5 seconds. If the bank fails to acknowledge, the transaction remains settled on the ledger but is flagged for operational follow-up. Failure states include REJECTED (validation failure, insufficient funds, blocked account), TIMEOUT (no response from beneficiary bank within 30 seconds), and ERROR (system-level failures). Enterprise systems should implement a state machine that handles all possible transitions and triggers appropriate business logic at each state change. CamFinTech provides a reference state machine implementation in Java and Node.js that covers all documented Bakong transaction states. For cross-border transactions through bilateral corridors, additional states exist: FX_PENDING (awaiting foreign exchange rate confirmation), CORRIDOR_PROCESSING (transaction handed off to the foreign payment system), and CROSS_BORDER_SETTLED (final settlement confirmed by both systems).

Bakong uses webhooks for asynchronous notification of transaction state changes. Bank partners expose webhook registration endpoints where enterprises configure callback URLs for different event types. The most critical webhook event is settlement confirmation, which notifies the merchant that payment has been received and funds are available. Webhook payloads are JSON-encoded and include the transaction reference, amount, currency, payer information (masked account number), settlement timestamp, and a digital signature for payload verification. The signature is computed as HMAC-SHA256 over the canonicalized payload using a shared secret established during webhook registration. Enterprises must verify the signature before processing any webhook to prevent spoofing attacks. Enterprise systems should implement idempotent webhook handlers, as Bakong may deliver duplicate notifications during network instability. The recommended pattern is to use the transaction reference as an idempotency key, checking whether the transaction has already been processed before executing business logic. Webhook endpoints must return HTTP 200 within 5 seconds; otherwise, the system retries with exponential backoff (5s, 15s, 45s, 135s) up to 5 attempts before marking the notification as failed and requiring manual reconciliation. CamFinTech recommends implementing a webhook ingestion queue (using RabbitMQ, AWS SQS, or equivalent) that decouples receipt acknowledgment from business logic processing. This pattern ensures timely HTTP 200 responses while allowing complex downstream processing (accounting updates, inventory management, notification dispatch) to execute asynchronously.

The Bakong system defines a standardized set of error codes that banks must propagate to Tier 4 enterprises. Error codes follow a hierarchical structure: 1xxx for authentication and authorization errors, 2xxx for validation errors, 3xxx for processing errors, 4xxx for system errors, and 5xxx for cross-border corridor errors. Understanding these codes is essential for building user-friendly error handling and for diagnosing integration issues during development and production. The most common error encountered during integration is 2001 (Insufficient Funds), which requires clear user messaging and should not trigger automatic retries. Error 2003 (Invalid Account) typically indicates a mis-keyed account number or a closed account. Error 3001 (Transaction Timeout) requires a status query before retrying to prevent duplicate transactions. Error 4001 (System Unavailable) indicates Bakong maintenance windows, which are scheduled on the first Sunday of each month from 02:00-06:00 ICT. Enterprise developers should implement comprehensive error logging that captures the full request payload, error code, error message, timestamp, and correlation ID for every failed transaction. CamFinTech recommends integrating error logs with monitoring systems (Datadog, Grafana, or equivalent) with alerts configured for error rate thresholds: warning at 1% error rate, critical at 5% error rate.

Daily reconciliation between the enterprise accounting system and Bakong settlement records is a critical operational requirement. The NBC requires all participating institutions to reconcile within T+1, and enterprises should implement automated reconciliation to meet this timeline. The reconciliation process involves comparing the enterprise's internal transaction log against the bank partner's settlement report, identifying discrepancies, and resolving exceptions. Bank partners provide daily settlement files in CSV or JSON format, typically available by 06:00 ICT for the previous day's transactions. The file includes every settled transaction with the Bakong transaction reference, amount, currency, counterparty details, settlement timestamp, and fees deducted. Enterprise reconciliation systems should match on the transaction reference number (not amount, as FX conversions may produce rounding differences) and flag any transactions present in one system but not the other. Common reconciliation discrepancies include: timing differences for transactions initiated near midnight ICT (the Bakong settlement day ends at 23:59:59 ICT), FX rate differences between the enterprise's quoted rate and the actual NBC settlement rate, and webhook delivery failures where the enterprise system missed a settlement notification. CamFinTech provides a reconciliation module that handles these edge cases and generates exception reports for manual review.

Bakong's bilateral payment corridors with Thailand (PromptPay), Malaysia (DuitNow), and China (Alipay) each have unique technical characteristics that enterprise developers must account for. The Thailand-Cambodia corridor, the most mature, supports real-time settlement in both directions with FX conversion handled at the NBC reference rate. Maximum transaction amounts are limited to THB 50,000 (approximately USD 1,400) for person-to-person transfers and THB 200,000 (approximately USD 5,600) for business payments. The Malaysia-Cambodia corridor operates through a store-and-forward model where transactions are batched and settled every 15 minutes during business hours (08:00-20:00 MYT). The China-Cambodia corridor integrates with Alipay's international payment infrastructure, primarily serving Chinese tourists and businesses in Cambodia, with settlement in USD. Enterprise developers integrating cross-border corridors must handle additional complexity: multi-currency FX management, corridor-specific transaction limits and operating hours, extended settlement states, and bilateral regulatory compliance requirements. The recommended integration pattern is to abstract corridor-specific logic behind a unified payment gateway interface, allowing the enterprise application to initiate cross-border payments through a consistent API regardless of the destination corridor.

The NBC mandates that all Bakong integrations undergo testing in a sandbox environment before receiving production access. The Bakong sandbox mirrors the production API with simulated financial institution endpoints, test accounts with pre-loaded balances, and the full range of transaction states and error codes. Bank partners provide sandbox credentials and documentation as part of the enterprise onboarding process. Effective sandbox testing should cover the complete payment lifecycle: successful payments in both KHR and USD, cross-currency transactions, all error codes (using test accounts configured to trigger specific errors), webhook delivery and signature verification, reconciliation file download and parsing, and idempotency handling for duplicate transaction submissions. CamFinTech recommends a minimum of 200 test transactions across all scenarios before requesting production access. The typical enterprise integration timeline from sandbox access to production deployment is 8-12 weeks. The first two weeks focus on API connectivity and authentication. Weeks 3-6 cover core payment flow implementation and testing. Weeks 7-10 address reconciliation, error handling, and edge case coverage. The final two weeks involve User Acceptance Testing (UAT) with the bank partner and NBC technical review. CamFinTech provides project management and technical quality assurance services to help enterprises complete integration within this timeline.

Enterprise systems processing high volumes of Bakong transactions must be architected for performance and scalability. The Bakong switch processes up to 500 transactions per second (TPS) at peak, but individual bank partner APIs may have lower throughput limits. Enterprises should confirm their bank partner's API rate limits and implement client-side rate limiting to avoid HTTP 429 (Too Many Requests) responses. For high-volume merchants (over 10,000 daily transactions), CamFinTech recommends the following architectural patterns: connection pooling with keep-alive for persistent HTTP connections to the bank API, asynchronous payment submission using message queues to decouple user-facing transaction initiation from backend API calls, batch KHQR pre-generation for predictable transaction volumes (e.g., recurring invoice payments), and horizontally scaled webhook handlers behind a load balancer to absorb settlement notification bursts. Database design for transaction storage should use partitioning by settlement date to optimize reconciliation queries, composite indexes on transaction reference and status for status lookups, and separate read replicas for reporting queries to avoid impacting transaction processing performance. The NBC publishes monthly peak transaction periods (salary payment dates, public holidays, tax filing deadlines) that enterprises should factor into capacity planning. CamFinTech provides load testing services using production-equivalent traffic patterns derived from real Bakong transaction distributions, helping enterprises validate their system architecture before going live.