README

A comprehensive PHP package for generating, parsing, and validating Bakong KHQR (Cambodian QR payment) codes. This package provides tools for developers to easily integrate with Cambodia's Bakong payment system.

Features

• Generate Bakong KHQR codes for individuals and merchants
• Parse and validate existing KHQR codes
• Support for both KHR and USD currencies
• Deep link generation for mobile apps
• Token-based operations for account verification
• Comprehensive test suite using Pest
• PSR-4 autoloading and PSR-12 code style

Requirements

• PHP 8.0 or higher

Installation

You can install the package via Composer:

composer require pisethchhun/bakong-khqr-php

Usage

Generating Individual KHQR

use Piseth\BakongKhqr\Models\IndividualInfo;
use Piseth\BakongKhqr\BakongKHQR;

// Create individual information
$individualInfo = new IndividualInfo(
    'username@wing',    // Account ID
    'Your Name',        // Merchant Name
    'Phnom Penh'        // Merchant City
);

// Set optional properties
$individualInfo->merchantID = '012345678';
$individualInfo->currency = 116; // KHR (840 for USD)
$individualInfo->amount = 1000.0;

// Generate the KHQR
$result = BakongKHQR::generateIndividual($individualInfo);

// Get the QR code string
$qrString = $result->getData()['qr'];

// Get the QR code image URL
$qrImageUrl = $result->getData()['qrImageUrl'];

Generating Merchant KHQR

use Piseth\BakongKhqr\Models\MerchantInfo;
use Piseth\BakongKhqr\BakongKHQR;

// Create merchant information
$merchantInfo = new MerchantInfo(
    'merchant@wing',      // Account ID
    'Merchant Name',      // Merchant Name
    'Phnom Penh',         // Merchant City
    '987654321',          // Merchant ID
    'Bank Name'           // Acquiring Bank
);

// Set optional properties
$merchantInfo->currency = 840; // USD (116 for KHR)
$merchantInfo->amount = 25.50;

// Generate the KHQR
$result = BakongKHQR::generateMerchant($merchantInfo);

Verifying a KHQR Code

use Piseth\BakongKhqr\BakongKHQR;

// Verify the KHQR code
$verificationResult = BakongKHQR::verify($qrString);

// Check if valid
if ($verificationResult->isValid()) {
    echo "KHQR is valid!";
}

Decoding a KHQR Code

use Piseth\BakongKhqr\BakongKHQR;

// Decode the KHQR code
$decodedResult = BakongKHQR::decode($qrString);

// Access decoded data
$decodedData = $decodedResult->getData();
echo "Merchant Name: " . $decodedData['merchantName'];
echo "Amount: " . ($decodedData['amount'] ?? 'Not specified');

Using Additional Data Fields

// Set all possible additional fields
$additionalFields = [
    'merchantID' => '123456789',
    'acquiringBank' => 'Test Bank',
    'currency' => 116,
    'amount' => 15000.0,
    'mobileNumber' => '85512345678',
    'billNumber' => 'BILL-2023-001',
    'storeLabel' => 'Main Store',
    'terminalLabel' => 'TERM-001',
    'purposeOfTransaction' => 'Payment for services',
    'languagePreference' => 'KM',
    'merchantNameAlternateLanguage' => 'អ្នកលក់',
    'merchantCityAlternateLanguage' => 'ភ្នំពេញ',
    'upiMerchantAccount' => 'UPI-123456'
];

// Apply additional fields to individual info
foreach ($additionalFields as $field => $value) {
    if (property_exists($individualInfo, $field)) {
        $individualInfo->$field = $value;
    }
}

Token-Based Operations

use Piseth\BakongKhqr\BakongKHQR;

// Initialize with token
$token = 'your-bakong-api-token';
$bakongKHQR = new BakongKHQR($token);

// Check if a Bakong account exists
$accountResult = $bakongKHQR->checkBakongAccount('test@wing');

// Check transaction status
$transactionMD5 = md5('transaction-reference');
$transactionResult = $bakongKHQR->checkTransactionByMD5($transactionMD5);

Deep Link Generation

use Piseth\BakongKhqr\BakongKHQR;

// Generate deep link from KHQR code
$deepLinkResult = BakongKHQR::generateDeepLink($qrString);
$deepLink = $deepLinkResult->getData()['deeplink'];

Advanced Usage

For more advanced usage examples, please check the examples directory.

Testing

The package uses Pest for testing. To run the tests:

composer test

To run specific test suites:

composer test:unit     # Run unit tests only
composer test:feature  # Run feature tests only

Code Style

This package follows PSR-12 coding standards. You can check and fix code style issues with:

composer cs-check  # Check code style
composer cs-fix    # Fix code style issues

Static Analysis

To run static analysis:

composer analyse

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security related issues, please email chhunpiseth.mail@gmail.com instead of using the issue tracker.

Credits

• Piseth Chhun
• All Contributors

License

The MIT License (MIT). Please see License File for more information.