aba-payway-sdk-unofficial 1.2.0 → 1.2.2

package/README.md

@@ -1,8 +1,13 @@
-# aba-payway-unofficial
+# aba-payway-sdk-unofficial
 
 ![npm version](https://img.shields.io/npm/v/aba-payway-sdk-unofficial)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/aba-payway-sdk-unofficial)
+![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue)
+![Edge Ready](https://img.shields.io/badge/Edge-Ready-success)
 
-Unofficial ABA PayWay SDK for Cambodia. Supports KHQR generation, purchase creation, status checking, and webhook verification. Works in Node.js 18+, Deno, Bun, and Cloudflare Workers.
+Unofficial ABA PayWay SDK for Cambodia. The lightweight, zero-dependency, edge-ready TypeScript SDK to integrate ABA PayWay. Creates instant **KHQR** codes, generates 1-tap mobile deeplinks, checks transactions, and verifies webhooks.
+
+Works natively on Next.js, Node.js 18+, Deno, Bun, and Cloudflare Workers using standard Web Crypto and native `fetch`.
 
 > **Why this project exists**: Online guides for ABA PayWay can look confusing and risky. Many developers fear losing money from wrong setups. We built this simple SDK with AI help so any developer can integrate ABA PayWay quickly and safely.
 
@@ -12,7 +17,16 @@ Unofficial ABA PayWay SDK for Cambodia. Supports KHQR generation, purchase creat
 - **ABA PayWay Business & Pricing**: [https://www.payway.com.kh/business](https://www.payway.com.kh/business)
 - **NBC Bakong API Docs**: [https://api-bakong.nbc.gov.kh/document](https://api-bakong.nbc.gov.kh/document)
 
-> **Disclaimer**: This is an unofficial open-source SDK. It is not affiliated with, endorsed by, or supported by ABA Bank or ABA PayWay.
+> **Disclaimer**: This is an unofficial open-source community project. It is not affiliated with, endorsed by, or supported by ABA Bank or ABA PayWay.
+
+---
+
+## Features
+
+- 🇰🇭 **Universal KHQR & Deeplinks**: Generates standard EMVCo KHQR payload strings, pre-rendered QR image URLs, and 1-tap mobile deeplinks for ABA Mobile.
+- ⚡ **Zero Dependencies & Edge Ready**: Built on standard Web Crypto (`crypto.subtle`) and native `fetch`. Bundle size is < 4kB minified.
+- 🛡️ **Automatic HMAC-SHA512 Security**: Eliminates hash sorting errors. Automatically arranges parameters and computes cryptographic signatures, with constant-time safe compare for webhooks.
+- 💎 **Strict TypeScript Safety**: Every request and response is strictly typed. Catch bugs at compile time with full IDE autocompletion.
 
 ---
 
@@ -21,7 +35,7 @@ Unofficial ABA PayWay SDK for Cambodia. Supports KHQR generation, purchase creat
 Fetch the full integration guide and follow it step by step:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/rithsila/aba-payway-sdk-unofficial/main/docs/agent-guide.md
+Integrate aba-payway-sdk-unofficial into this project following: https://raw.githubusercontent.com/rithsila/aba-payway-unofficial/main/docs/agent-guide.md
 ```
 
 ---
@@ -66,9 +80,7 @@ const purchase = await aba.createPurchase({
 });
 
 if (purchase.success) {
-  // The current (v3) API answers with the KHQR payload and a PNG that ABA
-  // rendered for you. `checkoutUrl` is only set by older API versions, so
-  // check for it rather than assuming it.
+  // The current (v3) API answers with the KHQR payload and a PNG that ABA rendered
   console.log("KHQR payload:", purchase.qrString);
   console.log("QR image:", purchase.qrImage); // "data:image/png;base64,..."
   console.log("ABA app deeplink:", purchase.abapayDeeplink);
@@ -79,15 +91,11 @@ if (purchase.success) {
 const status = await aba.checkStatus(txnId);
 console.log("Payment status:", status.status); // "APPROVED" | "PENDING" | ...
 
-// 4. Verify a webhook
-const isValid = await aba.verifyWebhook(
-  rawBody,
-  signatureHeader,
-  webhookSecret,
-);
+// 4. Verify a pushback. The secret defaults to your apiKey, which is what
+//    ABA signs with; `body` may be the raw string or the parsed object.
+const isValid = await aba.verifyWebhook(body, signatureHeader);
 
 // 5. Optionally render your own styled KHQR card (base64 SVG data URI).
-//    Skip this if `purchase.qrImage` is enough — that one needs no extra call.
 const khqrImage = await generateKHQR({
   emvData: purchase.qrString ?? "",
   amount: 10.0,
@@ -102,9 +110,7 @@ console.log("KHQR image:", khqrImage); // "data:image/svg+xml;base64,..."
 
 ## Opening the ABA app (deeplink)
 
-For a mobile checkout — a Telegram mini app, a WebView, a native app — you want
-the payer to land *inside* ABA Mobile, not squint at a QR on the same phone they
-are paying with. Ask for it with `paymentOption` and ABA answers with a link:
+For a mobile checkout — a Telegram mini app, a WebView, a native app — you want the payer to land *inside* ABA Mobile. Ask for it with `paymentOption` and ABA answers with a link:
 
 ```typescript
 const purchase = await aba.createPurchase({
@@ -113,8 +119,7 @@ const purchase = await aba.createPurchase({
   currency: "USD",
   items: [{ name: "Fried rice", quantity: 1, price: 4.5 }],
   paymentOption: "abapay_khqr_deeplink",
-  // Where ABA Mobile sends the payer back once they have paid. Pass the object
-  // and the SDK base64-encodes it the way ABA expects.
+  // Where ABA Mobile sends the payer back once they have paid
   returnDeeplink: {
     ios_scheme: "myapp://order/42",
     android_scheme: "myapp://order/42",
@@ -124,34 +129,13 @@ const purchase = await aba.createPurchase({
 purchase.abapayDeeplink; // "abamobilebank://ababank.com?type=payway&qrcode=..."
 purchase.qrString;       // same payment, as EMV data — for desktop
 purchase.qrImage;        // same payment, as a PNG data URI
-purchase.playStoreUrl;   // where to send a payer with no ABA Mobile installed
-purchase.appStoreUrl;
 ```
 
-One call gives you all of them, so branch on the device rather than making two
-purchases:
-
-| Payer is on | Show |
-| ----------- | ---- |
-| Phone with ABA Mobile | `abapayDeeplink` |
-| Phone without it | `playStoreUrl` / `appStoreUrl` |
-| Desktop | `qrImage`, or `generateKHQR(qrString)` for a branded card |
-
-Then poll `checkStatus(txnId)` until it leaves `PENDING`. **Never treat the
-payer returning through your `returnDeeplink` as proof of payment** — anyone can
-open that URL. `checkStatus` is the only authority.
-
-> A brand-new transaction answers `checkStatus` with `errorCode === "6"`
-> ("tran_id not found") for a second or so before it becomes queryable. Retry
-> rather than reporting a failure; the SDK does not hide this, because code 6
-> also means a genuinely unknown transaction.
+Then poll `checkStatus(txnId)` until it leaves `PENDING`. **Never treat the payer returning through your `returnDeeplink` as proof of payment** — anyone can open that URL. `checkStatus` is the only authority.
 
 ### `returnDeeplink` encoding
 
-ABA wants `return_deeplink` as base64-encoded JSON. Pass the object and the SDK
-encodes it; pass a string and it goes through untouched, so code that encoded it
-by hand keeps working. `encodeReturnDeeplinkForABA` is exported if you need it
-directly.
+ABA wants `return_deeplink` as base64-encoded JSON. Pass the object and the SDK encodes it. Pass a string and it goes through untouched.
 
 ---
 
@@ -163,122 +147,129 @@ directly.
 | `ABAPayWay.createPurchase` | method   | Create a payment. Returns `PurchaseResponse`.       |
 | `ABAPayWay.checkStatus`    | method   | Check transaction status. Returns `StatusResponse`. |
 | `ABAPayWay.verifyWebhook`  | method   | Verify webhook signature. Returns `boolean`.        |
-| `generateKHQR`             | function | Build a KHQR image (base64 SVG data URI) from EMV data. Async. |
-| `encodeItemsForABA`        | function | Base64-encode a `PurchaseItem[]` the way ABA expects. |
-| `encodeReturnDeeplinkForABA` | function | Base64-encode a `ReturnDeeplink` the way ABA expects. |
-| `generateABAHash`          | function | Generate HMAC-SHA512 hash for ABA API calls.        |
-| `generateTransactionId`    | function | Generate a unique transaction ID.                   |
-| `getABATimestamp`          | function | Get current timestamp in ABA format.                |
-| `formatPhoneForABA`        | function | Normalize phone number for ABA API.                 |
-| `getQRExpiration`          | function | Get QR code expiration timestamp.                   |
-
-### Types
-
-| Type               | Description                                                      |
-| ------------------ | ---------------------------------------------------------------- |
-| `ABAConfig`        | SDK configuration (merchantId, apiKey, baseUrl, webhookSecret)   |
-| `PurchaseRequest`  | Input for `createPurchase`                                       |
-| `PurchaseResponse` | Result from `createPurchase`                                     |
-| `StatusResponse`   | Result from `checkStatus`                                        |
-| `PaymentStatus`    | `"PENDING" \| "APPROVED" \| "DECLINED" \| "REFUNDED" \| "ERROR"` |
-| `PaymentOption`    | `"cards" \| "abapay_khqr" \| "abapay_khqr_deeplink" \| "alipay" \| "wechat" \| "google_pay"` |
-| `ReturnDeeplink`   | `{ ios_scheme?, android_scheme? }` — where ABA Mobile returns the payer |
-| `KHQROptions`      | Input for `generateKHQR`                                         |
-| `HashParams`       | Raw parameters for hash generation                               |
-
----
-
-## KHQR Customization
-
-Use `KHQROptions` to customize the QR code display. `generateKHQR` is async and
-returns a base64-encoded SVG data URI you can use directly as an `<img>` `src`:
-
-```typescript
-import { generateKHQR } from "aba-payway-sdk-unofficial";
-
-const dataUri = await generateKHQR({
-  emvData: "your_emv_qr_string",
-  amount: 5.5,
-  currency: "USD",
-  merchantName: "Rith Shop", // shown above the QR code
-  headerColor: "#1a73e8", // hex color for the header bar
-});
-```
+| `generateKHQR`             | function | Build a KHQR image (base64 SVG data URI). Async.    |
 
 ---
 
 ## Environment Setup
 
-You need ABA PayWay merchant credentials to use this SDK:
+You need ABA PayWay merchant credentials:
 
 | Variable        | Description                                                |
 | --------------- | ---------------------------------------------------------- |
 | `merchantId`    | Your ABA PayWay merchant ID                                |
 | `apiKey`        | Your ABA PayWay API key                                    |
 | `baseUrl`       | ABA PayWay base URL (e.g.`https://checkout.payway.com.kh`) |
-| `webhookSecret` | Accepted but currently unused — see note below (optional)   |
+| `webhookSecret` | Optional. Key for pushback verification (see below)        |
 
-Contact ABA Bank to get these credentials.
+> **`webhookSecret`:** ABA does not issue a separate pushback secret — it signs
+> with your API key — so leave this unset and `verifyWebhook()` will use
+> `apiKey`. Set it only if ABA gives you a distinct key.
 
-> **`webhookSecret`:** ABA does not issue one and the SDK never reads it. ABA
-> signs pushback with an `X-PayWay-HMAC-SHA512` header that `verifyWebhook()`
-> does not implement yet.
+### Webhook verification
 
----
+`verifyWebhook()` implements ABA's pushback scheme: the JSON body's keys are
+sorted ascending, their **values** concatenated (no keys, no separator), then
+HMAC-SHA512'd with your merchant key and base64-encoded. That is compared in
+constant time against the `X-PayWay-HMAC-SHA512` header.
 
-## Development
+```ts
+// Express, Hono, Next — a parsed body works as well as the raw string.
+const isValid = await aba.verifyWebhook(
+  req.body,
+  req.header("X-PayWay-HMAC-SHA512") ?? "",
+);
+if (!isValid) return res.status(401).end();
+```
 
-```bash
-# Run unit tests (mocked, no network)
-npm test
+Three things worth knowing:
 
-# Build the package
-npm run build
-```
+- **The raw body is not required.** ABA rebuilds the signature from parsed
+  values, not raw bytes, so re-serialising the body cannot invalidate it —
+  unlike Stripe-style schemes. Key order in the incoming JSON is irrelevant too.
+- **The secret defaults to your `apiKey`.** ABA does not issue a separate
+  pushback secret. Pass one explicitly, or set `webhookSecret`, to override.
+- **It never throws.** A malformed body, a missing header, or a bad signature
+  all return `false`.
+
+Pushback fields are `tran_id`, `apv`, `status`, `return_params` and
+`merchant_ref`. The whole body is hashed rather than those five by name, so a
+field ABA adds later is included automatically.
+
+> Your callback domain must be whitelisted on your merchant profile, or ABA
+> rejects the `return_url` with code 81.
 
 ---
 
 ## Sandbox Testing
 
-You can test the SDK against the real ABA PayWay sandbox. This makes live
-network calls, so it needs sandbox credentials.
-
-### 1. Get sandbox credentials
+Register at [Sandbox Portal](https://sandbox.payway.com.kh/register-sandbox/). ABA will email you credentials.
 
-Register at https://sandbox.payway.com.kh/register-sandbox/. ABA will email you
-a merchant ID, an API key, and a webhook secret.
+Copy `.env.example` to `.env` and fill in your values:
 
-### 2. Set up your `.env` file
+```bash
+ABA_MERCHANT_ID=your_sandbox_merchant_id
+ABA_API_KEY=your_sandbox_api_key
+ABA_BASE_URL=https://checkout-sandbox.payway.com.kh
+```
 
-Copy the example file and fill in your values:
+Run sandbox tests:
 
 ```bash
-cp .env.example .env
+npm run test:sandbox
 ```
 
-Then edit `.env`:
+### Actually paying a sandbox transaction
+
+A sandbox KHQR code **cannot** be scanned by the real ABA Mobile app, so
+`abapay_khqr` transactions sit at `PENDING` forever. To exercise `APPROVED`,
+`DECLINED`, and your pushback handler you need the hosted **card** checkout and
+one of [ABA's test cards](docs/ABA%20Test%20Cards.md):
 
 ```bash
-ABA_MERCHANT_ID=your_sandbox_merchant_id
-ABA_API_KEY=your_sandbox_api_key
-ABA_BASE_URL=https://checkout-sandbox.payway.com.kh
-# ABA_WEBHOOK_SECRET=  # ABA does not issue one
+npm run pay:sandbox
 ```
 
-`.env` is gitignored. Never commit real credentials.
+It creates a $1 card purchase, opens the checkout page in your browser, and
+polls until ABA settles the transaction.
 
-### 3. Run the sandbox tests
+For a from-scratch walkthrough — installing Node, getting credentials, and
+every check in order — see **[TESTING_GUIDE.md](TESTING_GUIDE.md)**. To produce
+a dated evidence report for ABA when requesting production access:
 
 ```bash
-npm run test:sandbox
+npm run report:sandbox
+```
+
+When you're ready to switch to production, work through
+**[docs/GO-LIVE.md](docs/GO-LIVE.md)** — the readiness checklist, what changes
+between sandbox and production, and what to ask ABA for.
+
+The switch that makes this work is **`paymentGate: 0`**. A merchant profile with
+the QR Payment API service enabled answers every purchase with KHQR JSON and
+ignores `paymentOption`, so `"cards"` on its own never reaches a card form:
+
+```ts
+const purchase = await aba.createPurchase({
+  transactionId: generateTransactionId(),
+  amount: 1.0,
+  currency: "USD",
+  paymentOption: "cards",
+  paymentGate: 0,        // route to the Checkout service, not the QR API
+  viewType: "hosted_view",
+});
+
+// ABA answers 302; the SDK hands back the page to send the payer to.
+console.log(purchase.checkoutUrl);
 ```
 
-This creates a real `$1.00` test purchase and checks its status. A new
-transaction stays `PENDING` until you pay it by opening the returned checkout
-URL in a browser.
+---
+
+## Community & Support
 
-If you run `npm run test:sandbox` without a `.env` file, the tests are skipped
-(not failed), so they never block a normal `npm test` run.
+Connect with fellow developers building with ABA PayWay in Cambodia:
+- 📢 **Announcements**: [Telegram Channel (@abapaywayunofficial)](https://t.me/abapaywayunofficial)
+- 💬 **Q&A & Support**: [Telegram Group (@abaunofficialintegrate)](https://t.me/abaunofficialintegrate)
 
 ---
 

package/dist/index.cjs

@@ -33,6 +33,18 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/hash.ts
+async function hmacSha512Base64(message, secret) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-512" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return btoa(String.fromCharCode(...new Uint8Array(signature)));
+}
 async function generateABAHash(params, publicKey) {
   const hashString = [
     params.req_time,
@@ -57,16 +69,7 @@ async function generateABAHash(params, publicKey) {
     params.custom_fields ?? "",
     params.return_params ?? ""
   ].join("");
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(publicKey),
-    { name: "HMAC", hash: "SHA-512" },
-    false,
-    ["sign"]
-  );
-  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(hashString));
-  return btoa(String.fromCharCode(...new Uint8Array(signature)));
+  return hmacSha512Base64(hashString, publicKey);
 }
 
 // src/response.ts
@@ -114,8 +117,8 @@ function formatPhoneForABA(phone) {
   if (cleaned.startsWith("855")) return "0" + cleaned.slice(3);
   return cleaned;
 }
-function getQRExpiration() {
-  return new Date(Date.now() + 15 * 60 * 1e3);
+function getQRExpiration(minutes = 3) {
+  return new Date(Date.now() + minutes * 60 * 1e3);
 }
 function toBase64Utf8(text) {
   const bytes = new TextEncoder().encode(text);
@@ -215,6 +218,10 @@ var ABAPayWay = class {
       return_params: request.returnParams ?? "",
       hash
     });
+    if (request.paymentGate !== void 0) {
+      body.set("payment_gate", String(request.paymentGate));
+    }
+    if (request.viewType) body.set("view_type", request.viewType);
     const url = `${this.config.baseUrl}/api/payment-gateway/v1/payments/purchase`;
     const failure = (error, errorCode) => ({
       success: false,
@@ -228,8 +235,28 @@ var ABAPayWay = class {
       const response = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: body.toString()
+        body: body.toString(),
+        // The Checkout service answers 302 to the hosted payment page. Let it
+        // be followed and the body is that page's HTML, which parses as
+        // neither JSON nor an error worth reporting — so stop at the redirect
+        // and read the address out of it instead.
+        redirect: "manual"
       });
+      if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (!location) {
+          return failure(
+            `ABA PayWay redirected (HTTP ${response.status}) without a Location header.`
+          );
+        }
+        return {
+          success: true,
+          transactionId: request.transactionId,
+          amount: request.amount,
+          currency: request.currency,
+          checkoutUrl: new URL(location, this.config.baseUrl).toString()
+        };
+      }
       const parsed = await parseAbaJson(response);
       if (parsed.error) return failure(parsed.error);
       const status = readAbaStatus(parsed.data);
@@ -299,18 +326,30 @@ var ABAPayWay = class {
       return failure(err instanceof Error ? err.message : "Unknown error");
     }
   }
+  /**
+   * Verify an ABA pushback (callback) against its `X-PayWay-HMAC-SHA512`
+   * header. Returns false for anything it cannot positively verify — a bad
+   * signature, a malformed body, a missing key — so a caller can branch on
+   * the result without a try/catch.
+   *
+   * `payload` may be the raw request body or the already-parsed object.
+   * Unlike most gateways, ABA's scheme rebuilds the signature from the parsed
+   * values rather than the raw bytes, so re-serialising the body on the way
+   * in cannot invalidate it. Frameworks that hand you a parsed body are fine.
+   *
+   * `secret` defaults to `webhookSecret`, then to `apiKey` — ABA does not
+   * issue a separate pushback secret, it signs with the merchant API key.
+   */
   async verifyWebhook(payload, signature, secret) {
     try {
-      const encoder = new TextEncoder();
-      const key = await crypto.subtle.importKey(
-        "raw",
-        encoder.encode(secret),
-        { name: "HMAC", hash: "SHA-512" },
-        false,
-        ["sign"]
+      const key = secret ?? this.config.webhookSecret ?? this.config.apiKey;
+      if (!key || !signature) return false;
+      const body = typeof payload === "string" ? JSON.parse(payload) : payload;
+      if (body === null || typeof body !== "object" || Array.isArray(body)) return false;
+      const expected = await hmacSha512Base64(
+        buildPushbackHashBase(body),
+        key
       );
-      const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
-      const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
       if (expected.length !== signature.length) return false;
       let mismatch = 0;
       for (let i = 0; i < expected.length; i++) {
@@ -322,6 +361,16 @@ var ABAPayWay = class {
     }
   }
 };
+function buildPushbackHashBase(body) {
+  return Object.keys(body).sort().map((key) => stringifyPushbackValue(body[key])).join("");
+}
+function stringifyPushbackValue(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "1" : "";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
 function toNumber(value) {
   if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
   if (typeof value === "string" && value.trim() !== "") {
@@ -348,6 +397,16 @@ function mapPaymentStatus(raw) {
 // src/khqr.ts
 var DEFAULT_HEADER_COLOR = "#bc271a";
 var QR_API_BASE = "https://quickchart.io/qr";
+var CARD_SHELL_PATH = "M189.868 10.8675H27.8677C18.4788 10.8675 10.8677 18.4787 10.8677 27.8675V287.867C10.8677 297.256 18.4788 304.867 27.8677 304.867H189.868C199.257 304.867 206.868 297.256 206.868 287.867V27.8675C206.868 18.4787 199.257 10.8675 189.868 10.8675Z";
+var KHQR_HEADER_BACKGROUND_PATH = "M178.91 0C188.299 0.00000824649 195.91 7.61117 195.91 17V36.3516H196V54L178.582 37H0V17C0.00000103088 7.61116 7.61116 0 17 0H178.91Z";
+var KHQR_HEADER_MARK_PATHS = [
+  "M104.488 17.1027V20.5948H100.95C100.596 20.5948 100.331 20.3329 100.331 19.9836V17.1027C100.331 16.7535 100.596 16.4916 100.95 16.4916H103.781C104.223 16.4043 104.488 16.7535 104.488 17.1027Z",
+  "M120.944 18.5H119.175C119.175 16.4047 117.494 14.746 115.371 14.746C113.69 14.746 112.274 15.7936 111.743 17.365C111.655 17.7143 111.566 18.1507 111.566 18.5V23.9999H111.478C110.505 23.9999 109.797 23.2142 109.797 22.3412V18.5C109.797 17.0159 110.416 15.5317 111.566 14.4841C112.628 13.5238 113.955 13 115.371 13C118.467 13 120.944 15.4444 120.944 18.5Z",
+  "M120.945 24H118.467L117.848 23.3889L116.521 22.0794L114.663 20.2461H117.14L120.945 24Z",
+  "M105.107 22.2539H99.7994C99.18 22.2539 98.6492 21.7301 98.6492 21.119V15.8809C98.6492 15.2698 99.18 14.746 99.7994 14.746H105.107C105.727 14.746 106.257 15.2698 106.257 15.8809V21.119L108.027 22.865V14.6587C108.027 13.6984 107.231 13 106.346 13H98.6492C97.6756 13 96.9683 13.7857 96.9683 14.6587V22.2539C96.9683 23.2142 97.7642 23.9126 98.6492 23.9126H106.877L105.107 22.2539Z",
+  "M83.6093 23.9999H81.1318L76.0005 18.8492V23.9999H73.9658V13H76.0005V17.8888L80.9553 13H83.3436L78.0356 18.2381L83.6093 23.9999Z",
+  "M92.898 13H94.8446V23.9999H92.898V19.1984H87.2358V23.9999H85.2012V13H87.2358V17.6269H92.898V13Z"
+].map((path) => `<path d="${path}" fill="#ffffff"/>`).join("");
 function formatAmount(amount, currency) {
   if (currency === "KHR") {
     return amount.toLocaleString("en-US", { maximumFractionDigits: 0 }) + " KHR";
@@ -375,30 +434,46 @@ async function generateKHQR(options) {
   const innerQr = qrSvgContent.replace(/<\?xml[^>]*\?>/g, "");
   const formattedAmount = formatAmount(amount, currency);
   const safeMerchantName = escapeXml(merchantName);
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 540" width="400" height="540">
-  <defs><clipPath id="qr-clip"><rect x="60" y="160" width="280" height="280" rx="8"/></clipPath></defs>
-  <rect width="400" height="540" rx="16" fill="white" stroke="#e0e0e0" stroke-width="1"/>
-  <rect width="400" height="80" rx="16" fill="${headerColor}"/>
-  <rect y="16" width="400" height="64" fill="${headerColor}"/>
-  <polygon points="360,80 400,80 400,104" fill="${headerColor}"/>
-  <text x="200" y="42" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="18" font-weight="bold">${safeMerchantName}</text>
-  <text x="200" y="65" text-anchor="middle" fill="rgba(255,255,255,0.9)" font-family="system-ui,sans-serif" font-size="13">KHQR Payment</text>
-  <text x="200" y="108" text-anchor="middle" fill="#1a1a1a" font-family="system-ui,sans-serif" font-size="28" font-weight="bold">${formattedAmount}</text>
-  <text x="200" y="128" text-anchor="middle" fill="#999" font-family="system-ui,sans-serif" font-size="12" letter-spacing="2">SCAN &#8226; PAY &#8226; DONE</text>
-  <g stroke="#c9c9c9" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" fill="none">
-    <polyline points="44,166 44,144 66,144"/>
-    <polyline points="334,144 356,144 356,166"/>
-    <polyline points="44,434 44,456 66,456"/>
-    <polyline points="334,456 356,456 356,434"/>
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 218 316" width="218" height="316" role="img" aria-label="PayWay KHQR payment card">
+  <defs>
+    <filter id="card-shadow" x="0" y="0" width="217.735" height="315.735" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+      <feOffset/>
+      <feGaussianBlur stdDeviation="5.43375"/>
+      <feComposite in2="hardAlpha" operator="out"/>
+      <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.16 0"/>
+      <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
+      <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
+    </filter>
+    <clipPath id="card-clip"><path d="${CARD_SHELL_PATH}"/></clipPath>
+    <clipPath id="qr-clip"><rect id="qr-area" x="37" y="145" width="144" height="144"/></clipPath>
+  </defs>
+  <rect width="218" height="316" fill="#ffffff"/>
+  <g filter="url(#card-shadow)">
+    <path d="${CARD_SHELL_PATH}" fill="#ffffff"/>
   </g>
-  <g clip-path="url(#qr-clip)">
-    <g transform="translate(60,160)">
-      ${innerQr || '<svg width="280" height="280"><rect width="280" height="280" fill="#f5f5f5"/><text x="140" y="140" text-anchor="middle" fill="#999" font-size="14">QR Code</text></svg>'}
+  <g clip-path="url(#card-clip)">
+    <g id="khqr-header-logo" transform="translate(11,11)" aria-label="KHQR logo">
+      <path d="${KHQR_HEADER_BACKGROUND_PATH}" fill="${headerColor}"/>
+      ${KHQR_HEADER_MARK_PATHS}
+    </g>
+    <text x="51" y="81" fill="#111111" font-family="Arial, Helvetica, sans-serif" font-size="10">${safeMerchantName}</text>
+    <text x="51" y="108" fill="#000000" font-family="Arial, Helvetica, sans-serif" font-size="20" font-weight="500">${formattedAmount}</text>
+    <line x1="11" y1="124" x2="207" y2="124" stroke="#8a8a8a" stroke-width="1" stroke-dasharray="4 5"/>
+    <rect x="37" y="145" width="144" height="144" fill="#ffffff"/>
+    <g clip-path="url(#qr-clip)">
+      <g transform="translate(37,145) scale(0.5142857143)">
+        ${innerQr || '<svg width="280" height="280"><rect width="280" height="280" fill="#f5f5f5"/><text x="140" y="145" text-anchor="middle" fill="#777777" font-family="Arial, Helvetica, sans-serif" font-size="16">QR Code</text></svg>'}
+      </g>
+    </g>
+    <g aria-label="KHQR brand mark">
+      <circle cx="109" cy="217" r="17" fill="#ffffff"/>
+      <circle cx="109" cy="217" r="13" fill="${headerColor}"/>
+      <path d="M102 213h3v-3h8v3h3v8h-3v3h-8v-3h-3z" fill="none" stroke="#ffffff" stroke-width="1.4" stroke-linejoin="round"/>
+      <path d="M109 213v8M105 217h8" stroke="#ffffff" stroke-width="1.2" stroke-linecap="round"/>
     </g>
   </g>
-  <text x="200" y="480" text-anchor="middle" fill="#666" font-family="system-ui,sans-serif" font-size="11">Scan with any KHQR-compatible app</text>
-  <text x="200" y="501" text-anchor="middle" fill="#999" font-family="system-ui,sans-serif" font-size="10">Powered by Bakong</text>
-  <text x="200" y="521" text-anchor="middle" fill="#555" font-family="system-ui,sans-serif" font-size="11" font-weight="bold" letter-spacing="1">KHQR</text>
 </svg>`;
   return "data:image/svg+xml;base64," + btoa(svg);
 }