promptpay-qrcode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devhyphenplus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# promptpay-qrcode
+
+Zero-dependency Node.js generator for **PromptPay QR payload strings** (the
+EMVCo / Thai QR text you encode into a QR image). Three generators plus a
+decoder:
+
+1. **Standard PromptPay** (Tag 29) — mobile number, national/tax ID, or
+   e-wallet ID, inspired by [saladpuk/PromptPay](https://github.com/saladpuk/PromptPay).
+2. **Bill Payment** (Tag 30) — biller ID + reference(s). The merchant
+   "bill payment" QR family, the same shape SCB's **แม่มณี (Mae Manee)** and
+   similar merchant QRs use (the payer's app shows the shop name).
+3. **KShop** — the KShop-format merchant QR (Tag 30 + Tag 31). You supply the
+   account-identifying fields; the library ships no merchant data.
+
+Plus `decode()` to read any PromptPay/Thai QR back into structured fields.
+
+See [`docs/promptpay-qr-structure.md`](docs/promptpay-qr-structure.md) for a
+deep dive on the EMVCo / Thai QR tag structure.
+
+Output is the **payload string only** — pass it to any QR library, or use the
+optional built-in image helpers (see [Rendering to an image](#rendering-to-an-image-optional)).
+
+## Install
+
+```
+npm install promptpay-qrcode
+```
+
+The core has **no dependencies**. Image rendering uses the optional `qrcode`
+peer dependency (install it only if you need images).
+
+```js
+const { generatePromptPay, generateBillPayment, generateKShopQR } = require('promptpay-qrcode');
+```
+
+## Standard PromptPay (Tag 29)
+
+```js
+generatePromptPay({ mobile: '0812345678' });              // static (no amount)
+generatePromptPay({ mobile: '0812345678', amount: 100 }); // dynamic, 100.00 THB
+generatePromptPay({ nationalId: '1234567890123' });
+generatePromptPay({ ewallet: '123456789012345', amount: 50.25 });
+```
+
+Provide **exactly one** of `mobile`, `nationalId`, `ewallet`. By default the QR
+is dynamic (POI `12`) when `amount` is present and static (POI `11`) otherwise.
+Pass `dynamic: true | false` to force it either way:
+
+```js
+generatePromptPay({ mobile: '0812345678', amount: 100, dynamic: false }); // static w/ amount
+generatePromptPay({ mobile: '0812345678', dynamic: true });               // dynamic w/o amount
+```
+
+Mobile numbers are normalized to the 13-char proxy form
+(`0812345678` → `0066812345678`).
+
+## Bill Payment (Tag 30) — Mae Manee / SCB merchant style
+
+```js
+generateBillPayment({
+  billerId: '000000000000000', // bank-issued Biller ID (usually 15 digits)
+  ref1: 'INV20240001',         // Reference 1 (mandatory)
+  ref2: 'BRANCH01',            // Reference 2 (optional)
+  amount: 50,                  // optional; present => dynamic QR (POI 12) by default
+  dynamic: true,               // optional; force POI (true='12', false='11')
+  merchantName: 'MY SHOP',     // optional (tag 59)
+  merchantCity: 'BANGKOK',     // optional (tag 60)
+});
+```
+
+The Biller ID and references are issued/defined by your bank (for SCB, via the
+Mae Manee / Business QR onboarding). `ref1` is required; `ref2` is optional.
+
+## KShop
+
+The KShop-format merchant QR (Tag 30 + Tag 31). This library ships **no
+merchant data** — you must supply the account-identifying fields, which your
+bank issues. `billerId`, `merchantRef`, `merchantName` and `merchantCity` are
+required; `generateKShopQR` throws if any are missing.
+
+```js
+const config = {
+  billerId:     '000000000000000', // bank-issued Biller ID    (required)
+  merchantRef:  'KB000000000000',  // bank merchant reference   (required)
+  merchantName: 'MY SHOP',         // tag 59                    (required)
+  merchantCity: 'BANGKOK',         // tag 60                    (required)
+  // Optional — emitted only when provided:
+  // visaTemplate, mastercardTemplate, unionpayTemplate, cardScheme,
+  // mcc, additionalData, dynamic (default true), innovationSubId (default '004')
+};
+
+generateKShopQR(100, 'ORDER0000000001', config);                        // dynamic (POI '12')
+generateKShopQR(100, 'ORDER0000000001', { ...config, dynamic: false }); // static  (POI '11')
+```
+
+`amount` (1st arg) and `reference` (2nd arg — the per-order ref placed in tag
+30/03 and 31/04) vary per call. Structural defaults (`dynamic: true`,
+`currency: '764'`, `countryCode: 'TH'`, `innovationSubId: '004'`) live in
+`KSHOP_DEFAULTS`; the required fields are listed in `REQUIRED_FIELDS`.
+
+If you already have a master QR for an account, you can decode it and reuse its
+fields — see [`kshopParamsFrom`](#decoding-a-qr-read-a-master-qr-back) below.
+
+## Decoding a QR (read a master QR back)
+
+`decode(payload)` parses any EMVCo / PromptPay / Thai QR string into structured
+fields and validates the CRC:
+
+```js
+const { decode } = require('promptpay-qrcode');
+
+const d = decode(masterQrString);
+d.amount;        // 100        (null if none)
+d.merchantName;  // 'MY SHOP'
+d.poiMethod;     // '12'  (d.static === false)
+d.crc.valid;     // true  -> the QR's checksum is correct
+d.fields['30'];  // { '00': 'A000000677010112', '01': '000000000000000', ... }
+d.tags;          // ordered [{ id, length, value }] of the top level
+```
+
+It throws on a malformed payload (a declared length running past the string).
+
+### Cloning another KShop account from its master QR
+
+`kshopParamsFrom(qr)` pulls out exactly the account-identifying fields you'd
+pass to `generateKShopQR` — so you can mint new QRs for an existing account:
+
+```js
+const { kshopParamsFrom, generateKShopQR } = require('promptpay-qrcode');
+
+const params = kshopParamsFrom(masterQr);
+// params = { billerId, merchantRef, merchantName, merchantCity,
+//            additionalData, visaTemplate, mastercardTemplate,
+//            unionpayTemplate, cardScheme, innovationSubId, mcc,
+//            currency, countryCode, dynamic }  (only those present)
+
+// Generate a fresh QR for that account with your own amount + order ref:
+const qr = generateKShopQR(250.5, 'ORDER123', params);
+```
+
+Per-transaction values (`amount`, and the order reference in tag 30/03 & 31/04)
+are **not** included in `params` — you supply those per call. Round-trip is
+exact: `generateKShopQR(amount, ref, kshopParamsFrom(qr))` reproduces the
+original master QR byte-for-byte when given the same amount and ref.
+
+## Rendering to an image (optional)
+
+The core is zero-dependency. To turn a payload into an actual QR image, install
+the optional [`qrcode`](https://www.npmjs.com/package/qrcode) package:
+
+```
+npm install qrcode
+```
+
+Then use the built-in helpers — they lazy-load `qrcode` and reject with a clear
+message if it isn't installed:
+
+```js
+const { generatePromptPay, toFile, toDataURL, toSVG, toBuffer, toTerminal } = require('promptpay-qrcode');
+
+const payload = generatePromptPay({ mobile: '0812345678', amount: 100 });
+
+await toFile('qr.png', payload, { width: 300, margin: 2 }); // PNG file
+const url = await toDataURL(payload);                        // data:image/png;base64,...
+const svg = await toSVG(payload);                            // SVG markup string
+const buf = await toBuffer(payload);                         // PNG Buffer
+console.log(await toTerminal(payload));                      // scannable QR in the terminal
+```
+
+The second `options` argument is passed straight through to `qrcode`
+(`width`, `margin`, `color`, `errorCorrectionLevel`, …). See `example-image.js`
+(`npm run example:image`) for a full demo.
+
+## API
+
+| Function | Returns |
+| --- | --- |
+| `generatePromptPay({ mobile \| nationalId \| ewallet, amount?, dynamic? })` | payload string |
+| `generateBillPayment({ billerId, ref1, ref2?, amount?, dynamic?, merchantName?, merchantCity? })` | payload string |
+| `generateKShopQR(amount, reference, config)` | payload string |
+| `KSHOP_DEFAULTS` / `REQUIRED_FIELDS` | KShop structural defaults / required field list |
+| `decode(payload)` | structured decode + CRC validation |
+| `parseTLV(payload)` | low-level ordered `[{ id, length, value }]` |
+| `kshopParamsFrom(qr)` | account params to clone a KShop master QR |
+| `crc16Ccitt(str)` / `crc16Hex(str)` | CRC16-CCITT (number / 4-char hex) |
+| `formatMobile(str)` | 13-char PromptPay mobile proxy |
+| `toFile(path, payload, opts?)` | `Promise<void>` — write PNG file *(needs `qrcode`)* |
+| `toDataURL(payload, opts?)` | `Promise<string>` — data URL *(needs `qrcode`)* |
+| `toBuffer(payload, opts?)` | `Promise<Buffer>` — PNG buffer *(needs `qrcode`)* |
+| `toSVG(payload, opts?)` | `Promise<string>` — SVG markup *(needs `qrcode`)* |
+| `toTerminal(payload, opts?)` | `Promise<string>` — terminal QR *(needs `qrcode`)* |
+
+## Files
+
+- `crc.js` — CRC16-CCITT (0xFFFF init, 0x1021 poly).
+- `promptpay.js` — standard PromptPay (Tag 29) + bill payment (Tag 30) generators.
+- `kshop.js` — KShop generator (configurable, no bundled merchant data).
+- `decode.js` — decode/parse a payload + `kshopParamsFrom` extractor.
+- `image.js` — optional image helpers (lazy-load `qrcode`).
+- `index.js` — public entry point.
+- `test.js` — `npm test`. `example.js` — `npm run example`.
+  `example-image.js` — `npm run example:image` (needs `qrcode`).
+- `docs/promptpay-qr-structure.md` — EMVCo / Thai QR tag-structure reference.
+
+## Tests
+
+```
+npm test
+```
+
+Verifies CRC against the `123456789 → 0x29B1` vector, TLV nesting parity, the
+Tag 29 / Tag 30 / KShop structures, decode + CRC validation, and the
+`kshopParamsFrom` → `generateKShopQR` round-trip.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/crc.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * CRC16-CCITT (False) checksum — the standard used for Thai QR codes.
+ *
+ * Initial value 0xFFFF, polynomial 0x1021, no final XOR.
+ * Port of the PHP `crc16_ccitt` implementation.
+ *
+ * @param {string} data Input string (treated as Latin-1 / single-byte chars).
+ * @returns {number} The CRC16 checksum (0..0xFFFF).
+ */
+function crc16Ccitt(data) {
+  let crc = 0xffff;
+  for (let i = 0; i < data.length; i++) {
+    crc ^= data.charCodeAt(i) << 8;
+    for (let j = 0; j < 8; j++) {
+      if (crc & 0x8000) {
+        crc = (crc << 1) ^ 0x1021;
+      } else {
+        crc = crc << 1;
+      }
+      crc &= 0xffff; // keep it 16-bit (JS uses 32-bit bitwise ops)
+    }
+  }
+  return crc & 0xffff;
+}
+
+/**
+ * CRC as the uppercase 4-char hex string appended to QR payloads.
+ * @param {string} data
+ * @returns {string}
+ */
+function crc16Hex(data) {
+  return crc16Ccitt(data).toString(16).toUpperCase().padStart(4, '0');
+}
+
+module.exports = { crc16Ccitt, crc16Hex };

package/decode.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const { crc16Hex } = require('./crc');
+
+// Templates whose value is itself a string of nested TLV sub-fields.
+const NESTED_TAGS = new Set(['26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '62', '64', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99']);
+
+/**
+ * Parse a TLV string into an array of { id, length, value } in order.
+ * Throws if a declared length runs past the end of the string (malformed QR).
+ * @param {string} payload
+ * @returns {{id:string,length:number,value:string}[]}
+ */
+function parseTLV(payload) {
+  const out = [];
+  let i = 0;
+  while (i < payload.length) {
+    if (i + 4 > payload.length) {
+      throw new Error(`Malformed payload: truncated tag header at offset ${i}`);
+    }
+    const id = payload.slice(i, i + 2);
+    const length = parseInt(payload.slice(i + 2, i + 4), 10);
+    if (Number.isNaN(length)) {
+      throw new Error(`Malformed payload: bad length for tag ${id} at offset ${i}`);
+    }
+    const start = i + 4;
+    const end = start + length;
+    if (end > payload.length) {
+      throw new Error(`Malformed payload: tag ${id} length ${length} exceeds payload at offset ${i}`);
+    }
+    out.push({ id, length, value: payload.slice(start, end) });
+    i = end;
+  }
+  return out;
+}
+
+/**
+ * Recursively turn a TLV list into a plain object keyed by tag id. Nested
+ * templates become nested objects. Where a tag id repeats (rare), values are
+ * collected into an array.
+ * @param {{id:string,value:string}[]} tags
+ * @param {boolean} nested Whether this level may contain sub-templates.
+ * @returns {Object}
+ */
+function tagsToObject(tags, nested) {
+  const obj = {};
+  for (const { id, value } of tags) {
+    let v = value;
+    if (nested && NESTED_TAGS.has(id)) {
+      v = tagsToObject(parseTLV(value), true);
+    }
+    if (id in obj) {
+      obj[id] = Array.isArray(obj[id]) ? obj[id].concat([v]) : [obj[id], v];
+    } else {
+      obj[id] = v;
+    }
+  }
+  return obj;
+}
+
+/**
+ * Decode an EMVCo / PromptPay / Thai QR payload string.
+ *
+ * @param {string} payload The raw QR text.
+ * @returns {object} Structured decode:
+ *   - tags: ordered [{id,length,value}] of the top level
+ *   - fields: nested object keyed by tag id (templates expanded)
+ *   - crc: { value, expected, valid }
+ *   - amount, currency, countryCode, merchantName, merchantCity, poiMethod, static
+ */
+function decode(payload) {
+  if (typeof payload !== 'string' || payload.length < 8) {
+    throw new Error('decode() expects a QR payload string');
+  }
+
+  const tags = parseTLV(payload);
+  const fields = tagsToObject(tags, true);
+
+  // CRC: recompute over everything up to (but not including) the 4 CRC chars.
+  const crcValue = fields['63'];
+  let crc = null;
+  if (typeof crcValue === 'string' && payload.endsWith(crcValue)) {
+    const body = payload.slice(0, payload.length - crcValue.length);
+    const expected = crc16Hex(body);
+    crc = { value: crcValue, expected, valid: expected === crcValue.toUpperCase() };
+  }
+
+  const poi = fields['01'];
+  return {
+    tags,
+    fields,
+    crc,
+    poiMethod: poi || null,
+    static: poi === '11',
+    amount: fields['54'] != null ? Number(fields['54']) : null,
+    currency: fields['53'] || null,
+    countryCode: fields['58'] || null,
+    merchantName: fields['59'] || null,
+    merchantCity: fields['60'] || null,
+  };
+}
+
+/**
+ * Given a KSHOP-style master QR, extract the account-identifying fields needed
+ * to regenerate QRs for that account via generateKShopQR(amount, ref, params).
+ *
+ * Returns ONLY the mandatory / account-specific fields that are present, so the
+ * result can be spread straight into the options argument. Per-transaction
+ * values (amount, the order reference in 30/03 & 31/04) are intentionally
+ * omitted — those are supplied per call.
+ *
+ * @param {string|object} qr A payload string or a prior decode() result.
+ * @returns {object} Options suitable for generateKShopQR's 3rd argument.
+ */
+function kshopParamsFrom(qr) {
+  const d = typeof qr === 'string' ? decode(qr) : qr;
+  const f = d.fields;
+  const t30 = f['30'] || {};
+  const t31 = f['31'] || {};
+  const t51 = f['51'] || {};
+
+  const params = {};
+  if (f['02'] != null) params.visaTemplate = f['02'];
+  if (f['04'] != null) params.mastercardTemplate = f['04'];
+  if (f['15'] != null) params.unionpayTemplate = f['15'];
+  if (t30['01'] != null) params.billerId = t30['01'];
+  // Merchant ref appears in 30/02 (and usually mirrored in 31/02).
+  if (t30['02'] != null) params.merchantRef = t30['02'];
+  if (t31['01'] != null) params.innovationSubId = t31['01'];
+  if (Object.keys(t51).length) params.cardScheme = t51;
+  if (f['52'] != null) params.mcc = f['52'];
+  if (f['53'] != null) params.currency = f['53'];
+  if (f['58'] != null) params.countryCode = f['58'];
+  if (f['59'] != null) params.merchantName = f['59'];
+  if (f['60'] != null) params.merchantCity = f['60'];
+  if (f['62'] != null) {
+    // tag 62 is stored as an expanded object; re-flatten to its raw string.
+    params.additionalData = flattenTag62(d.tags);
+  }
+  params.dynamic = d.poiMethod === '12';
+
+  return params;
+}
+
+/** Pull tag 62's raw inner string from the ordered top-level tag list. */
+function flattenTag62(tags) {
+  const tag = tags.find((t) => t.id === '62');
+  return tag ? tag.value : undefined;
+}
+
+module.exports = { decode, parseTLV, kshopParamsFrom };

package/docs/promptpay-qr-structure.md

@@ -0,0 +1,231 @@
+# PromptPay / Thai QR Code — Structure Deep Dive
+
+PromptPay QR is a profile of the **EMVCo Merchant-Presented Mode (MPM)** QR
+standard, localized by the **Bank of Thailand (BOT) Thai QR Payment Standard**.
+This document is the reference behind this library's generators.
+
+Sources: EMVCo *EMV QR Code Specification for Payment Systems — MPM* (v1.1),
+BOT *Thai QR Code Standard* (FPG circular), `dtinth/promptpay-qr`,
+`saladpuk/PromptPay`, and a full decode of the in-repo KSHOP PHP example.
+
+---
+
+## 1. Encoding: TLV (Tag-Length-Value)
+
+The whole payload is a flat string of TLV fields:
+
+```
+ID (2 digits) | LEN (2 digits, decimal, zero-padded) | VALUE (LEN chars)
+```
+
+- **ID**: 2 numeric digits (`00`–`99`).
+- **LEN**: 2 **decimal** digits, zero-padded (`05`, `16`). NOT hex. Because it's
+  2 digits, a single value maxes at 99 chars.
+- **VALUE**: exactly LEN characters (ASCII).
+
+Some IDs are **templates** — their VALUE is itself a string of nested TLV
+sub-fields using the same rules. PromptPay uses templates at `29`, `30`, `31`,
+`51`, and `62`.
+
+Example: `000201` = ID `00`, LEN `02`, VALUE `01`.
+
+---
+
+## 2. Top-level ID allocation (EMVCo)
+
+| ID | Meaning | PromptPay usage |
+|----|---------|-----------------|
+| `00` | Payload Format Indicator | always `01` |
+| `01` | Point of Initiation Method | `11` static / `12` dynamic |
+| `02`–`03` | Visa account templates | merchant card schemes (optional) |
+| `04`–`05` | Mastercard account templates | merchant card schemes (optional) |
+| `06`–`08` | EMVCo reserved | |
+| `09`–`10` | Discover | |
+| `11`–`12` | Amex | |
+| `13`–`14` | JCB | |
+| `15`–`16` | UnionPay | merchant card schemes (optional) |
+| `17`–`25` | EMVCo reserved (payment networks) | |
+| `26`–`51` | **Merchant Account Information templates** | **`29` P2P, `30` bill-pay, `31` e-wallet innovation** |
+| `52` | Merchant Category Code (MCC, ISO 18245) | e.g. `5732` electronics |
+| `53` | Transaction Currency (ISO 4217 numeric) | `764` = THB |
+| `54` | Transaction Amount | e.g. `100.00` (omit for static) |
+| `55` | Tip / convenience indicator | rarely used |
+| `56`–`57` | Convenience fee fixed / percentage | rarely used |
+| `58` | Country Code (ISO 3166-1 alpha-2) | `TH` |
+| `59` | Merchant Name | e.g. `MY SHOP` |
+| `60` | Merchant City | e.g. `BANGKOK` |
+| `61` | Postal Code | optional |
+| `62` | Additional Data Field Template | refs / labels (see §6) |
+| `63` | **CRC** | 4 hex chars (see §7) |
+| `64` | Merchant Info — Language Template | optional |
+| `65`–`79` | RFU for EMVCo | |
+| `80`–`99` | Unreserved templates | |
+
+`63` (CRC) is always the **last** field.
+
+---
+
+## 3. PromptPay Application IDs (AIDs)
+
+PromptPay merchant-account templates begin with sub-tag `00` = the AID.
+
+| AID | Purpose | Template |
+|-----|---------|----------|
+| `A000000677010111` | Credit Transfer (mobile / national ID / e-wallet) | tag `29` |
+| `A000000677010112` | Bill Payment (domestic biller) | tag `30` |
+| `A000000677010113` | Payment / e-wallet Innovation | tag `31` |
+| `A000000677010114` | Customer-Presented | (customer-side QR) |
+
+---
+
+## 4. Tag 29 — Credit Transfer (the common P2P PromptPay QR)
+
+```
+29 LL
+   00 16 A000000677010111      ← AID
+   01 13 0066812345678         ← mobile  (one of 01/02/03)
+   02 13 1234567890123         ← national ID / tax ID
+   03 15 123456789012345       ← e-wallet ID
+```
+
+Provide **exactly one** of sub-tags `01`/`02`/`03`.
+
+**Mobile normalization** (sub-tag `01`, always 13 chars):
+1. Strip non-digits.
+2. Drop a single leading `0`.
+3. Prepend `66` (Thailand).
+4. Left-pad with `0` to 13 chars.
+
+`0812345678 → 812345678 → 66812345678 → 0066812345678`
+
+National ID / tax ID → sub-tag `02`, 13 digits as-is.
+E-wallet ID → sub-tag `03`, 15 digits as-is.
+
+---
+
+## 5. Tag 30 — Bill Payment (biller) + Reference 1 / Reference 2
+
+```
+30 LL
+   00 16 A000000677010112      ← AID (domestic)
+   01 LL <BillerID>            ← Biller ID = 13-digit Tax ID + 2-digit suffix (15)
+   02 LL <Reference1>          ← mandatory, biller-defined
+   03 LL <Reference2>          ← optional, biller-defined
+```
+
+- **Biller ID**: assigned by the bank; the merchant's 13-digit tax ID plus a
+  2-digit suffix (commonly `00`), so 15 chars.
+- **Reference 1 (`02`)**: mandatory. The biller decides its meaning — usually the
+  customer/account/invoice identifier. Alphanumeric.
+- **Reference 2 (`03`)**: optional secondary reference (e.g. branch, terminal,
+  order id). Alphanumeric. Omit the whole sub-tag if unused.
+
+> The KSHOP PHP puts the bank-issued merchant ref in `02` and the per-order
+> KShop reference in `03`. That's a valid biller-specific choice — not a fixed
+> rule of the standard.
+
+---
+
+## 6. Tag 62 — Additional Data Field Template
+
+Nested template carrying references/labels. Common sub-tags:
+
+| Sub | Meaning |
+|-----|---------|
+| `01` | Bill Number |
+| `02` | Mobile Number |
+| `03` | Store Label |
+| `04` | Loyalty Number |
+| `05` | Reference Label |
+| `06` | Customer Label |
+| `07` | Terminal Label |
+| `08` | Purpose of Transaction |
+| `09` | Additional Consumer Data Request |
+
+In the KSHOP example, `62` decodes as `05` (reference label) + `07` (terminal
+label).
+
+---
+
+## 7. Tag 63 — CRC16
+
+Algorithm: **CRC-16/CCITT-FALSE**.
+
+- Width 16, polynomial `0x1021`, init `0xFFFF`.
+- **No** input/output reflection, **no** final XOR.
+- Computed over the **entire preceding payload INCLUDING the literal `6304`**
+  (the CRC tag id + length), then the 4-char uppercase hex result is appended.
+
+Test vector: `CRC("123456789") = 0x29B1`.
+
+```
+payload += "6304" + crc16(payload + "6304").toString(16).toUpperCase().padStart(4,"0")
+```
+
+---
+
+## 8. Static vs Dynamic (tag 01)
+
+| Value | Meaning |
+|-------|---------|
+| `11` | **Static** — reusable; amount usually omitted, payer types it. |
+| `12` | **Dynamic** — single use; amount (`54`) present. |
+
+Convention: include `54` ⇒ use `12`; omit `54` ⇒ use `11`. Scanners still read
+an amount even if `01=11` (as the KSHOP payload does), but `12` is the correct
+marker for a one-time amount.
+
+---
+
+## 9. Worked example — KSHOP payload layout
+
+Field layout of a KSHOP-format merchant QR. Values shown are **placeholders**;
+the account-identifying fields (biller ID, merchant ref, card templates,
+additional data) are supplied by the caller and issued by the bank.
+
+```
+00 02 01                                   Payload format = 01
+01 02 12                                   Point of init = dynamic (carries amount)
+02 .. <visa template>                      Visa merchant template (optional)
+04 .. <mastercard template>                Mastercard merchant template (optional)
+15 .. <unionpay template>                  UnionPay merchant template (optional)
+30 ..                                       PromptPay BILL PAYMENT
+   00 16 A000000677010112                      AID (domestic)
+   01 .. <biller id>                           Biller ID
+   02 .. <merchant ref>                        Reference 1 (merchant ref)
+   03 .. <order ref>                           Reference 2 (per-order ref)
+31 ..                                       PromptPay PAYMENT INNOVATION
+   00 16 A000000677010113                      AID
+   01 03 004                                    (network/sub-id)
+   02 .. <merchant ref>                        merchant ref
+   04 .. <order ref>                           order ref
+51 ..                                       Card-scheme merchant template (optional)
+   00 14 A0000000041010                         RID (Mastercard, public)
+   01 .. <bin>                                  BIN/issuer
+   02 .. <account ref>                          account ref
+52 .. <mcc>                                 MCC (optional)
+53 03 764                                   Currency = THB
+54 06 100.00                                Amount
+58 02 TH                                    Country
+59 .. <merchant name>                       Merchant name
+60 .. <merchant city>                       Merchant city
+62 ..                                       Additional data (optional)
+   05 .. <reference label>                      Reference label
+   07 .. <terminal label>                       Terminal label
+63 04 <crc>                                 CRC16
+```
+
+This library ships no merchant data: `generateKShopQR` requires the
+account-identifying fields and emits the optional card/MCC/additional-data tags
+only when they are provided.
+
+---
+
+## 10. Validation checklist for a generated payload
+
+1. Starts with `000201`.
+2. `01` is `11` or `12`, consistent with presence of `54`.
+3. Exactly one merchant template identifies the payee (`29` *or* `30`/`31`).
+4. `53` = `764`, `58` = `TH`.
+5. Every TLV length matches its value; payload re-parses with no leftover bytes.
+6. Ends with `6304` + valid CRC16 of everything before the 4 CRC chars.

package/image.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Optional QR-image helpers. These wrap the `qrcode` npm package, which is a
+// PEER dependency: the core payload generators stay zero-dependency, and
+// `qrcode` is only required the moment one of these functions is called.
+//
+//   npm install qrcode
+//
+// All functions take a payload string (from generatePromptPay / generateKShopQR
+// / generateBillPayment) plus an optional `options` object forwarded to the
+// underlying `qrcode` library (e.g. { width, margin, color, errorCorrectionLevel }).
+
+/**
+ * Lazily load the `qrcode` package, throwing a helpful error if it's missing.
+ * @returns {import('qrcode')}
+ */
+function loadQrcode() {
+  try {
+    return require('qrcode');
+  } catch (err) {
+    throw new Error(
+      "The 'qrcode' package is required for image generation. Install it with: npm install qrcode"
+    );
+  }
+}
+
+// Each wrapper is `async` so a missing-`qrcode` error surfaces as a promise
+// rejection (catchable with .catch / try-await), not a synchronous throw.
+
+/**
+ * Render a payload to a PNG file on disk.
+ * @param {string} filePath Destination path (e.g. './qr.png').
+ * @param {string} payload  QR payload string.
+ * @param {object} [options] Options forwarded to qrcode.toFile.
+ * @returns {Promise<void>}
+ */
+async function toFile(filePath, payload, options = {}) {
+  return loadQrcode().toFile(filePath, payload, options);
+}
+
+/**
+ * Render a payload to a data URL (PNG by default), e.g. for an <img src>.
+ * @param {string} payload QR payload string.
+ * @param {object} [options] Options forwarded to qrcode.toDataURL.
+ * @returns {Promise<string>} data: URL string.
+ */
+async function toDataURL(payload, options = {}) {
+  return loadQrcode().toDataURL(payload, options);
+}
+
+/**
+ * Render a payload to a PNG image Buffer.
+ * @param {string} payload QR payload string.
+ * @param {object} [options] Options forwarded to qrcode.toBuffer.
+ * @returns {Promise<Buffer>}
+ */
+async function toBuffer(payload, options = {}) {
+  return loadQrcode().toBuffer(payload, Object.assign({ type: 'png' }, options));
+}
+
+/**
+ * Render a payload to an SVG string.
+ * @param {string} payload QR payload string.
+ * @param {object} [options] Options forwarded to qrcode.toString.
+ * @returns {Promise<string>} SVG markup.
+ */
+async function toSVG(payload, options = {}) {
+  return loadQrcode().toString(payload, Object.assign({ type: 'svg' }, options));
+}
+
+/**
+ * Render a payload as a scannable QR in the terminal (UTF-8 blocks).
+ * @param {string} payload QR payload string.
+ * @param {object} [options] Options forwarded to qrcode.toString.
+ * @returns {Promise<string>} The terminal-art string (also handy to print).
+ */
+async function toTerminal(payload, options = {}) {
+  return loadQrcode().toString(payload, Object.assign({ type: 'terminal', small: true }, options));
+}
+
+module.exports = { toFile, toDataURL, toBuffer, toSVG, toTerminal };

package/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { crc16Ccitt, crc16Hex } = require('./crc');
+const { generatePromptPay, generateBillPayment, formatMobile } = require('./promptpay');
+const { generateKShopQR, KSHOP_DEFAULTS } = require('./kshop');
+const { decode, parseTLV, kshopParamsFrom } = require('./decode');
+const image = require('./image');
+
+module.exports = {
+  crc16Ccitt,
+  crc16Hex,
+  generatePromptPay,
+  generateBillPayment,
+  formatMobile,
+  generateKShopQR,
+  KSHOP_DEFAULTS,
+  // Decoding / parsing.
+  decode,
+  parseTLV,
+  kshopParamsFrom,
+  // Optional image helpers (require the `qrcode` package).
+  image,
+  toFile: image.toFile,
+  toDataURL: image.toDataURL,
+  toBuffer: image.toBuffer,
+  toSVG: image.toSVG,
+  toTerminal: image.toTerminal,
+};

package/kshop.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const { crc16Hex } = require('./crc');
+
+// ---- Public PromptPay Application IDs (not account-specific) ----
+const AID_MERCHANT_PRESENTED = 'A000000677010111';
+const AID_DOMESTIC = 'A000000677010112'; // bill payment        -> tag 30
+const AID_PAYMENT_INNOVATION = 'A000000677010113'; // payment innovation -> tag 31
+const AID_CUSTOMER_PRESENTED = 'A000000677010114';
+const CURRENCY_THB = '764';
+const COUNTRY_CODE = 'TH';
+
+/**
+ * Build an EMVCo TLV field, mirroring the PHP `buildTagPayload`.
+ *
+ * - Array form (single positional value): `['value']` -> `id + len + value`.
+ * - Object form (sub-tags): `{ '00': v, '01': v }` -> nested sub-TLVs wrapped
+ *   in the outer `id + len`.
+ *
+ * @param {string} tagId
+ * @param {string[]|Object<string,string>} data
+ * @returns {string}
+ */
+function buildTagPayload(tagId, data) {
+  if (Array.isArray(data)) {
+    if (data.length === 0) return '';
+    if (data.length === 1) {
+      const v = data[0];
+      return tagId + String(v.length).padStart(2, '0') + v;
+    }
+    // Multiple positional values are not used by the PHP; treat as concat.
+    data = Object.assign({}, data);
+  }
+
+  const entries = Object.entries(data);
+  if (entries.length === 0) return '';
+
+  let inner = '';
+  for (const [subTagId, v] of entries) {
+    inner += subTagId + String(v.length).padStart(2, '0') + v;
+  }
+  return tagId + String(inner.length).padStart(2, '0') + inner;
+}
+
+/**
+ * Format amount as a fixed 2-decimal string (PHP number_format equivalent).
+ * @param {number|string} amount
+ * @returns {string}
+ */
+function formatAmount(amount) {
+  return Number(amount).toFixed(2);
+}
+
+// Universal, non-identifying defaults only. All account-specific values must be
+// supplied by the caller (see required fields in generateKShopQR).
+const KSHOP_DEFAULTS = {
+  dynamic: true, // tag 01: true -> '12' (dynamic), false -> '11' (static)
+  innovationSubId: '004', // tag 31 / 01 (network sub-id used by the KShop format)
+  currency: CURRENCY_THB, // tag 53
+  countryCode: COUNTRY_CODE, // tag 58
+};
+
+// Account-identifying fields the caller MUST provide.
+const REQUIRED_FIELDS = ['billerId', 'merchantRef', 'merchantName', 'merchantCity'];
+
+/**
+ * Generate a KShop-format PromptPay merchant QR payload (Tag 30 + Tag 31).
+ *
+ * All account-identifying values must be supplied via `config` — this library
+ * ships no merchant data. Card-scheme templates (tags 02/04/15/51), MCC (52)
+ * and the additional-data block (62) are optional and only emitted when given.
+ *
+ * @param {number} amount    Transaction amount in THB.
+ * @param {string} reference Per-order reference (tag 30/03 and tag 31/04).
+ * @param {object} config
+ * @param {string} config.billerId       Bank-issued Biller ID (required).
+ * @param {string} config.merchantRef    Bank merchant reference, e.g. "KB..." (required).
+ * @param {string} config.merchantName   Merchant name, tag 59 (required).
+ * @param {string} config.merchantCity   Merchant city, tag 60 (required).
+ * @param {boolean} [config.dynamic]     tag 01: true='12' (default), false='11'.
+ * @param {string} [config.innovationSubId] tag 31/01 (default '004').
+ * @param {string} [config.currency]     tag 53 (default '764' THB).
+ * @param {string} [config.countryCode]  tag 58 (default 'TH').
+ * @param {string} [config.visaTemplate]       tag 02 (optional).
+ * @param {string} [config.mastercardTemplate] tag 04 (optional).
+ * @param {string} [config.unionpayTemplate]   tag 15 (optional).
+ * @param {Object<string,string>} [config.cardScheme] tag 51 sub-tags (optional).
+ * @param {string} [config.mcc]          tag 52 merchant category code (optional).
+ * @param {string} [config.additionalData] tag 62 raw value (optional).
+ * @returns {string} The EMVCo QR payload including CRC.
+ */
+function generateKShopQR(amount, reference, config = {}) {
+  const cfg = Object.assign({}, KSHOP_DEFAULTS, config);
+
+  const missing = REQUIRED_FIELDS.filter((k) => cfg[k] == null || cfg[k] === '');
+  if (missing.length) {
+    throw new Error('generateKShopQR: missing required config field(s): ' + missing.join(', '));
+  }
+  if (reference == null || reference === '') {
+    throw new Error('generateKShopQR: reference is required');
+  }
+
+  let payload = '';
+  payload += buildTagPayload('00', ['01']);
+  payload += buildTagPayload('01', [cfg.dynamic ? '12' : '11']);
+  if (cfg.visaTemplate) payload += buildTagPayload('02', [cfg.visaTemplate]);
+  if (cfg.mastercardTemplate) payload += buildTagPayload('04', [cfg.mastercardTemplate]);
+  if (cfg.unionpayTemplate) payload += buildTagPayload('15', [cfg.unionpayTemplate]);
+  payload += buildTagPayload('30', {
+    '00': AID_DOMESTIC,
+    '01': cfg.billerId,
+    '02': cfg.merchantRef,
+    '03': reference,
+  });
+  payload += buildTagPayload('31', {
+    '00': AID_PAYMENT_INNOVATION,
+    '01': cfg.innovationSubId,
+    '02': cfg.merchantRef,
+    '04': reference,
+  });
+  if (cfg.cardScheme && Object.keys(cfg.cardScheme).length) {
+    payload += buildTagPayload('51', cfg.cardScheme);
+  }
+  if (cfg.mcc) payload += buildTagPayload('52', [cfg.mcc]);
+  payload += buildTagPayload('53', [cfg.currency]);
+  payload += buildTagPayload('54', [formatAmount(amount)]);
+  payload += buildTagPayload('58', [cfg.countryCode]);
+  payload += buildTagPayload('59', [cfg.merchantName]);
+  payload += buildTagPayload('60', [cfg.merchantCity]);
+  if (cfg.additionalData) payload += buildTagPayload('62', [cfg.additionalData]);
+
+  // CRC tag 63 over payload + '6304', appended.
+  payload += buildTagPayload('63', [crc16Hex(payload + '6304')]);
+  return payload;
+}
+
+module.exports = {
+  generateKShopQR,
+  buildTagPayload,
+  KSHOP_DEFAULTS,
+  REQUIRED_FIELDS,
+  constants: {
+    AID_MERCHANT_PRESENTED,
+    AID_DOMESTIC,
+    AID_PAYMENT_INNOVATION,
+    AID_CUSTOMER_PRESENTED,
+    CURRENCY_THB,
+    COUNTRY_CODE,
+  },
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "promptpay-qrcode",
+  "version": "1.0.0",
+  "description": "Zero-dependency PromptPay QR payload generator (PromptPay P2P, Tag 30 bill payment / Mae Manee, and KShop)",
+  "main": "index.js",
+  "type": "commonjs",
+  "files": [
+    "crc.js",
+    "promptpay.js",
+    "kshop.js",
+    "decode.js",
+    "image.js",
+    "index.js",
+    "docs/promptpay-qr-structure.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "example": "node example.js",
+    "example:image": "node example-image.js"
+  },
+  "peerDependencies": {
+    "qrcode": "^1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "qrcode": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "promptpay",
+    "qrcode",
+    "qr",
+    "thai",
+    "thailand",
+    "emvco",
+    "maemanee",
+    "mae-manee",
+    "scb",
+    "kshop",
+    "payment"
+  ],
+  "engines": {
+    "node": ">=12"
+  },
+  "license": "MIT",
+  "author": "devhyphenplus <dev.hyphenplus@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devhyphenplus/promptpay-qrcode.git"
+  },
+  "homepage": "https://github.com/devhyphenplus/promptpay-qrcode#readme",
+  "bugs": {
+    "url": "https://github.com/devhyphenplus/promptpay-qrcode/issues"
+  }
+}

package/promptpay.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const { crc16Hex } = require('./crc');
+
+// Application IDs (AID) for PromptPay.
+const AID_PERSON = 'A000000677010111'; // credit transfer (mobile, national id, ewallet) -> tag 29
+const AID_BILLPAY = 'A000000677010112'; // bill payment (domestic biller) -> tag 30
+
+const CURRENCY_THB = '764';
+const COUNTRY_TH = 'TH';
+
+/**
+ * Build a single EMVCo TLV field: id (2) + length (2, zero-padded) + value.
+ * @param {string} id Two-char tag id.
+ * @param {string} value Field value.
+ * @returns {string}
+ */
+function tlv(id, value) {
+  const len = String(value.length).padStart(2, '0');
+  return `${id}${len}${value}`;
+}
+
+/**
+ * Resolve the Point of Initiation Method value (tag 01).
+ *
+ * `dynamic` overrides when set (`true` -> '12', `false` -> '11'). When left
+ * undefined it defaults to dynamic if an amount is present, static otherwise.
+ *
+ * @param {boolean|undefined} dynamic Explicit override, or undefined to auto.
+ * @param {boolean} hasAmount Whether the payload carries an amount.
+ * @returns {'11'|'12'}
+ */
+function poiMethod(dynamic, hasAmount) {
+  if (dynamic === undefined) return hasAmount ? '12' : '11';
+  return dynamic ? '12' : '11';
+}
+
+/**
+ * Format a Thai mobile number into the 13-char PromptPay proxy value.
+ * e.g. "081-234-5678" -> "0066812345678"
+ * @param {string} mobile
+ * @returns {string}
+ */
+function formatMobile(mobile) {
+  const digits = String(mobile).replace(/\D/g, '').replace(/^0/, '');
+  return ('66' + digits).padStart(13, '0');
+}
+
+/**
+ * Generate a standard PromptPay QR payload string.
+ *
+ * Provide exactly one of: mobile, nationalId, ewallet.
+ * By default the QR is dynamic (POI '12') when `amount` is given and static
+ * (POI '11') otherwise; pass `dynamic` to force either.
+ *
+ * @param {object} opts
+ * @param {string} [opts.mobile]     Thai mobile number (any format).
+ * @param {string} [opts.nationalId] 13-digit national ID / tax ID.
+ * @param {string} [opts.ewallet]    15-digit e-Wallet ID.
+ * @param {number} [opts.amount]     Optional amount in THB.
+ * @param {boolean} [opts.dynamic]   Force POI: true='12', false='11'. Auto if omitted.
+ * @returns {string} The EMVCo QR payload including CRC.
+ */
+function generatePromptPay({ mobile, nationalId, ewallet, amount, dynamic } = {}) {
+  const provided = [mobile, nationalId, ewallet].filter((v) => v != null);
+  if (provided.length !== 1) {
+    throw new Error('Provide exactly one of: mobile, nationalId, ewallet');
+  }
+
+  let merchantField;
+  if (mobile != null) {
+    merchantField = tlv('01', formatMobile(mobile));
+  } else if (nationalId != null) {
+    merchantField = tlv('02', String(nationalId).replace(/\D/g, ''));
+  } else {
+    merchantField = tlv('03', String(ewallet).replace(/\D/g, ''));
+  }
+
+  const merchantAccount = tlv('00', AID_PERSON) + merchantField;
+  const hasAmount = amount != null && amount !== '';
+
+  let payload = '';
+  payload += tlv('00', '01'); // payload format indicator
+  payload += tlv('01', poiMethod(dynamic, hasAmount)); // dynamic vs static
+  payload += tlv('29', merchantAccount); // PromptPay merchant account info
+  payload += tlv('53', CURRENCY_THB);
+  if (hasAmount) {
+    payload += tlv('54', Number(amount).toFixed(2));
+  }
+  payload += tlv('58', COUNTRY_TH);
+
+  payload += '6304' + crc16Hex(payload + '6304');
+  return payload;
+}
+
+/**
+ * Generate a PromptPay Bill Payment (Tag 30) QR payload string.
+ *
+ * This is the merchant "bill payment" QR family — the same shape SCB's
+ * แม่มณี (Mae Manee) and other merchant QRs use. The payer's app shows the
+ * merchant name (tag 59) rather than a person's name.
+ *
+ * @param {object} opts
+ * @param {string} opts.billerId       Bank-issued Biller ID (usually 15 digits:
+ *                                      13-digit tax ID + 2-digit suffix).
+ * @param {string} opts.ref1           Reference 1 (mandatory, biller-defined).
+ * @param {string} [opts.ref2]         Reference 2 (optional, biller-defined).
+ * @param {number} [opts.amount]       Amount in THB. Present => dynamic by default.
+ * @param {boolean} [opts.dynamic]     Force POI: true='12', false='11'. Auto if omitted.
+ * @param {string} [opts.merchantName] Merchant name (tag 59).
+ * @param {string} [opts.merchantCity] Merchant city (tag 60).
+ * @returns {string} The EMVCo QR payload including CRC.
+ */
+function generateBillPayment({ billerId, ref1, ref2, amount, dynamic, merchantName, merchantCity } = {}) {
+  if (!billerId) throw new Error('billerId is required');
+  if (!ref1) throw new Error('ref1 is required');
+
+  let merchantAccount = tlv('00', AID_BILLPAY) + tlv('01', String(billerId)) + tlv('02', String(ref1));
+  if (ref2 != null && ref2 !== '') {
+    merchantAccount += tlv('03', String(ref2));
+  }
+
+  const hasAmount = amount != null && amount !== '';
+
+  let payload = '';
+  payload += tlv('00', '01'); // payload format indicator
+  payload += tlv('01', poiMethod(dynamic, hasAmount)); // dynamic vs static
+  payload += tlv('30', merchantAccount); // bill payment merchant account info
+  payload += tlv('53', CURRENCY_THB);
+  if (hasAmount) {
+    payload += tlv('54', Number(amount).toFixed(2));
+  }
+  payload += tlv('58', COUNTRY_TH);
+  if (merchantName) payload += tlv('59', merchantName);
+  if (merchantCity) payload += tlv('60', merchantCity);
+
+  payload += '6304' + crc16Hex(payload + '6304');
+  return payload;
+}
+
+module.exports = { generatePromptPay, generateBillPayment, formatMobile, tlv };