bakong-khqr-image 0.1.0

Generate styled Bakong KHQR card images with correct USD/KHR amount formatting.

bakong-khqr-image

Generate styled Bakong KHQR card images that match the official NBC design — with correct USD and KHR amount formatting.

Built from production experience: the official bakong-khqr library formats USD amounts with a comma (0,01 USD) instead of a period (0.01 USD). This library fixes that and ships a clean, standalone implementation.

---

Features

• ✅ EMV-compliant KHQR payload generation (no external bakong dependency)
• ✅ Correct amount formatting — 1,234.56 USD · 4,000 KHR
• ✅ Styled 300 × 450 px card (Bakong red header, merchant info, dashed separator, rounded corners)
• ✅ Bundled assets — works out of the box, no manual font/icon setup
• ✅ Multiple export formats: PNG · JPEG · WebP · bytes · Base64 · data URI
• ✅ Static (open-amount) and dynamic QR code support
• ✅ Typed, documented, tested

---

Installation

pip install bakong-khqr-image

Dependencies (Pillow and qrcode) are installed automatically.

---

Quick Start

from bakong_khqr_image import KHQRImage

# Create one instance per merchant — reuse it for every payment
khqr = KHQRImage(
    bakong_account_id="yourname@aclb",
    merchant_name="My Coffee Shop",
    merchant_city="Phnom Penh",   # optional, default "Phnom Penh"
    currency="USD",               # optional, default "USD"
)

# Generate a styled QR card image
result = khqr.generate_image(amount=2.50)

# Save as PNG
result.save_png("payment_qr.png")

# Or get bytes / Base64 / data URI for web / API responses
png_bytes = result.to_bytes()
b64       = result.to_base64()
data_uri  = result.to_data_uri()

---

API Reference

KHQRImage

KHQRImage(
    bakong_account_id: str,
    merchant_name: str,
    merchant_city: str = "Phnom Penh",
    currency: str = "USD",           # "USD" or "KHR"
)

generate_image(amount, *, bill_number, store_label, terminal_label, mobile_number, static) → QRImageResult

Renders the full styled card image.

Parameter	Type	Description
amount	float	Transaction amount. 0 = open-amount / static QR
bill_number	str	Unique reference ID (auto-generated if omitted)
store_label	str	Store label shown in the Bakong app
terminal_label	str	Terminal identifier
mobile_number	str	Merchant phone number
static	bool	True → static QR (no amount in payload)

generate_payload(amount, *, ...) → (payload, bill_number)

Returns only the raw EMV KHQR string — useful for custom renderers or the Bakong payment-verification API.

payload, ref_id = khqr.generate_payload(amount=5.00)
md5_hash = KHQRImage.md5(payload)   # pass to Bakong API to check payment status

KHQRImage.md5(payload) → str

Computes the MD5 hash of a payload string required by the Bakong transaction-check API.

---

QRImageResult

Method	Returns	Description
save_png(path)	str	Save PNG, returns absolute path
save_jpeg(path)	str	Save JPEG, returns absolute path
save_webp(path)	str	Save lossless WebP, returns absolute path
to_bytes()	bytes	PNG-encoded bytes
to_base64()	str	Base64-encoded PNG string
to_data_uri()	str	data:image/png;base64,… URI
.image	PIL.Image	Raw PIL Image for custom processing

---

Examples

KHR currency

from bakong_khqr_image import KHQRImage

khqr = KHQRImage(
    bakong_account_id="yourname@aclb",
    merchant_name="ហាងកាហ្វេ",
    currency="KHR",
)
result = khqr.generate_image(amount=4_000)
result.save_png("payment_khr.png")

Static (open-amount) QR

result = khqr.generate_image(amount=0, static=True)
result.save_png("static_qr.png")

Web / API response

result = khqr.generate_image(amount=1.50)
# Return as JSON
import json
response = {"qr_image": result.to_data_uri()}

Access the raw PIL image

result = khqr.generate_image(amount=2.50)
pil_image = result.image          # PIL.Image.Image
pil_image.show()                  # open in system viewer

---

Card Layout

┌─────────────────────────────┐  ◥ red fold
│  [KHQR / Bakong logo]       │  ← red header (60 px)
│                             │
│  Merchant Name              │
│  2.50 USD                   │
│ - - - - - - - - - - - - - - │  ← dashed separator
│                             │
│    ┌───────────────────┐    │
│    │                   │    │
│    │    QR Code        │    │
│    │      [💲]         │    │  ← currency icon overlay
│    │                   │    │
│    └───────────────────┘    │
│                             │
└─────────────────────────────┘
         300 × 450 px

---

Sample image

Running Tests

pip install -e ".[dev]"
pytest

---

Publishing to PyPI

pip install build twine
python -m build
twine upload dist/*

---

License

MIT © 2026 Virackbot