promptpay-qrcode 1.0.0 → 1.2.0

package/README.md

@@ -86,18 +86,40 @@ const config = {
   merchantCity: 'BANGKOK',         // tag 60                    (required)
   // Optional — emitted only when provided:
   // visaTemplate, mastercardTemplate, unionpayTemplate, cardScheme,
-  // mcc, additionalData, dynamic (default true), innovationSubId (default '004')
+  // mcc, additionalData, dynamic (default false), innovationSubId (default '004'),
+  // innovationAid (tag 31 AID — default KShop value; see below)
 };
 
-generateKShopQR(100, 'ORDER0000000001', config);                        // dynamic (POI '12')
-generateKShopQR(100, 'ORDER0000000001', { ...config, dynamic: false }); // static  (POI '11')
+generateKShopQR(100, 'ORDER0000000001', config);                       // static  (POI '11') — default
+generateKShopQR(100, 'ORDER0000000001', { ...config, dynamic: true }); // dynamic (POI '12')
 ```
 
 `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`,
+30/03 and 31/04) vary per call. Structural defaults (`dynamic: false`,
 `currency: '764'`, `countryCode: 'TH'`, `innovationSubId: '004'`) live in
 `KSHOP_DEFAULTS`; the required fields are listed in `REQUIRED_FIELDS`.
 
+> **Tag 31 AID (`innovationAid`).** The Bank of Thailand guideline documents
+> `A000000677012004` for the Payment-Innovation template, but **KBank/KShop QRs
+> in the wild use `A000000677010113`**. The library defaults to the KShop value
+> so real KShop QRs round-trip exactly; pass `innovationAid` to override:
+>
+> ```js
+> const { generateKShopQR, AID_PAYMENT_INNOVATION_BOT } = require('promptpay-qrcode');
+> generateKShopQR(100, 'ORDER1', { ...config, innovationAid: AID_PAYMENT_INNOVATION_BOT });
+> ```
+>
+> Both AIDs are exported: `AID_PAYMENT_INNOVATION` (KShop, default) and
+> `AID_PAYMENT_INNOVATION_BOT` (BOT). `detach`/`kshopParamsFrom` capture whichever
+> the source QR used.
+
+> **Static vs dynamic — bank-app compatibility.** KShop defaults to **static
+> (POI `11`) with the amount included**, because that form is accepted by the
+> widest range of apps — including **K PLUS** and the KShop app. In real-device
+> testing, **dynamic (POI `12`) is rejected by K PLUS** for this merchant QR
+> family (though it works in SCB, KTB Next, BBL and UOB). Pass `dynamic: true`
+> only if you specifically target apps that accept POI `12`.
+
 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.
 
@@ -120,6 +142,34 @@ d.tags;          // ordered [{ id, length, value }] of the top level
 
 It throws on a malformed payload (a declared length running past the string).
 
+### Detecting supported payment channels
+
+A KShop/merchant QR carries a separate template per enrolled payment rail, so an
+omitted template means that channel isn't offered. `channels(qr)` reports them:
+
+```js
+const { channels } = require('promptpay-qrcode');
+
+channels(kshopQr);
+// {
+//   promptpay: true,
+//   creditCard: true,                       // false if the merchant isn't card-enabled
+//   networks: ['visa', 'mastercard', 'unionpay'],
+//   promptpayTemplates: ['30', '31'],
+//   cardTemplates: ['02', '04', '15', '51'],
+// }
+```
+
+So a KShop account configured **without** credit-card acceptance produces a QR
+with no card templates, and `channels()` returns `creditCard: false`,
+`networks: []`. PromptPay rails are detected from tags `29`/`30`/`31`; card
+networks from the EMVCo template ranges (`02`–`16`) and from card RIDs in the
+generic `26`–`51` range. `detach(qr)` also includes this under `.channels`.
+
+> This reflects what the merchant has **enrolled** (capability advertised by the
+> QR). Whether a specific card actually authorizes is still the acquirer's call
+> at settlement.
+
 ### Cloning another KShop account from its master QR
 
 `kshopParamsFrom(qr)` pulls out exactly the account-identifying fields you'd
@@ -143,6 +193,78 @@ 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.
 
+### Detaching any master QR (all types)
+
+`detach(qr)` is the generic version: it auto-detects the QR type and splits it
+into reusable **account** info and the per-transaction values, for **all three**
+families. `kshopParamsFrom` is the KShop-specific case underneath it.
+
+```js
+const { detach, generatePromptPay, generateBillPayment, generateKShopQR } = require('promptpay-qrcode');
+
+const { type, account, transaction } = detach(masterQr);
+```
+
+| `type` | `account` (reusable) | `transaction` (per-call) | Regenerate |
+| --- | --- | --- | --- |
+| `'promptpay'` | `{ mobile \| nationalId \| ewallet }` | `{ amount, dynamic }` | `generatePromptPay({ ...account, ...transaction })` |
+| `'billpayment'` | `{ billerId, merchantName?, merchantCity? }` | `{ ref1, ref2?, amount, dynamic }` | `generateBillPayment({ ...account, ...transaction })` |
+| `'kshop'` | full KShop config (= `kshopParamsFrom`) | `{ amount, reference }` | `generateKShopQR(transaction.amount, transaction.reference, account)` |
+
+```js
+// Example: re-issue a bill-payment QR with a new amount, same account
+const { account } = detach(masterBillQr);
+const next = generateBillPayment({ ...account, ref1: 'INV2', amount: 75 });
+```
+
+For PromptPay the mobile proxy is reversed (`0066812345678` → `0812345678`) so
+it round-trips through `generatePromptPay`. `detach` accepts a payload string or
+a prior `decode()` result, and also returns the full `decoded` object.
+`detectType(fields)` is exposed separately if you only need the type.
+
+## CLI
+
+A small command-line inspector ships with the package (`promptpay-qr`, or
+`node cli.js` from the repo). It decodes a payload, validates the CRC, and shows
+the detached account/transaction split and a tag dump — all locally, nothing
+leaves your machine.
+
+```
+# from the repo
+node cli.js '00020101021130...C9ED'
+npm run decode -- '00020101...'          # via the npm script
+
+# installed globally (npm i -g promptpay-qrcode)
+promptpay-qr '00020101...'
+
+# pipe it in, or get raw JSON
+echo '00020101...' | promptpay-qr
+promptpay-qr --json '00020101...'
+```
+
+Example output:
+
+```
+Type      : kshop
+CRC       : C9ED  ✓ valid
+POI       : 11  (static — K PLUS compatible)
+Amount    : (none — payer enters)
+Merchant  : MY SHOP / CITY
+
+Account (reusable):    { billerId, merchantRef, merchantName, ... }
+Transaction (per-call): { amount, reference }
+
+Tags:
+00 02 01
+01 02 11
+30 81
+   00 16 A000000677010112
+   ...
+```
+
+Exit code is `0` for a valid CRC, `1` for an invalid/malformed payload — handy
+in scripts.
+
 ## Rendering to an image (optional)
 
 The core is zero-dependency. To turn a payload into an actual QR image, install
@@ -182,6 +304,9 @@ The second `options` argument is passed straight through to `qrcode`
 | `decode(payload)` | structured decode + CRC validation |
 | `parseTLV(payload)` | low-level ordered `[{ id, length, value }]` |
 | `kshopParamsFrom(qr)` | account params to clone a KShop master QR |
+| `detach(qr)` | `{ type, account, transaction, channels, decoded }` for any QR type |
+| `detectType(fields)` | `'promptpay'` \| `'billpayment'` \| `'kshop'` \| `'unknown'` |
+| `channels(qr)` | `{ promptpay, creditCard, networks, promptpayTemplates, cardTemplates }` |
 | `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`)* |
@@ -197,6 +322,7 @@ The second `options` argument is passed straight through to `qrcode`
 - `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`).
+- `cli.js` — command-line inspector (`promptpay-qr` / `npm run decode`).
 - `index.js` — public entry point.
 - `test.js` — `npm test`. `example.js` — `npm run example`.
   `example-image.js` — `npm run example:image` (needs `qrcode`).

package/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+'use strict';
+
+// Tiny CLI to inspect a PromptPay / Thai QR payload locally.
+//
+//   node cli.js <payload>          decode + detach a payload string
+//   node cli.js --json <payload>   print the raw JSON result
+//   echo "<payload>" | node cli.js read payload from stdin
+//
+// Nothing leaves your machine.
+
+const { decode, detach } = require('./index');
+
+function readInput() {
+  const args = process.argv.slice(2).filter((a) => a !== '--json');
+  if (args.length) return args.join('').trim();
+  // Fall back to stdin (e.g. piped input).
+  try {
+    return require('fs').readFileSync(0, 'utf8').trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+function tagLine(id, len, value, indent) {
+  return `${'  '.repeat(indent)}${id} ${String(len).padStart(2, '0')} ${value}`;
+}
+
+// Pretty-print top-level tags, expanding the nested merchant templates.
+function dumpTags(payload) {
+  const NESTED = new Set(['29', '30', '31', '51', '62']);
+  const { parseTLV } = require('./decode');
+  const lines = [];
+  for (const t of parseTLV(payload)) {
+    if (NESTED.has(t.id)) {
+      lines.push(tagLine(t.id, t.length, '', 0).trimEnd());
+      for (const s of parseTLV(t.value)) lines.push(tagLine(s.id, s.length, s.value, 1));
+    } else {
+      lines.push(tagLine(t.id, t.length, t.value, 0));
+    }
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const json = process.argv.includes('--json');
+  const payload = readInput();
+
+  if (!payload) {
+    console.error('Usage: node cli.js [--json] <payload>   (or pipe the payload via stdin)');
+    process.exit(2);
+  }
+
+  let d, r;
+  try {
+    d = decode(payload);
+    r = detach(payload);
+  } catch (err) {
+    console.error('Error: ' + err.message);
+    process.exit(1);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ type: r.type, channels: r.channels, account: r.account, transaction: r.transaction, crc: d.crc }, null, 2));
+    return;
+  }
+
+  const ok = d.crc && d.crc.valid;
+  const ch = r.channels;
+  const channelStr =
+    (ch.promptpay ? 'PromptPay' : '') +
+    (ch.creditCard ? (ch.promptpay ? ' + ' : '') + 'Card (' + ch.networks.join(', ') + ')' : '') ||
+    '(none)';
+  console.log('Type      : ' + r.type);
+  console.log('CRC       : ' + (d.crc ? d.crc.value : '(none)') + (ok ? '  ✓ valid' : '  ✗ INVALID (expected ' + (d.crc && d.crc.expected) + ')'));
+  console.log('POI       : ' + d.poiMethod + (d.static ? '  (static)' : '  (dynamic)'));
+  console.log('Amount    : ' + (d.amount == null ? '(none — payer enters)' : d.amount));
+  console.log('Channels  : ' + channelStr);
+  if (d.merchantName) console.log('Merchant  : ' + d.merchantName + (d.merchantCity ? ' / ' + d.merchantCity : ''));
+  console.log('\nAccount (reusable):');
+  console.log(JSON.stringify(r.account, null, 2));
+  console.log('\nTransaction (per-call):');
+  console.log(JSON.stringify(r.transaction, null, 2));
+  console.log('\nTags:');
+  console.log(dumpTags(payload));
+
+  if (!ok) process.exit(1);
+}
+
+main();

package/decode.js

@@ -126,6 +126,7 @@ function kshopParamsFrom(qr) {
   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['00'] != null) params.innovationAid = t31['00'];
   if (t31['01'] != null) params.innovationSubId = t31['01'];
   if (Object.keys(t51).length) params.cardScheme = t51;
   if (f['52'] != null) params.mcc = f['52'];
@@ -148,4 +149,161 @@ function flattenTag62(tags) {
   return tag ? tag.value : undefined;
 }
 
-module.exports = { decode, parseTLV, kshopParamsFrom };
+/**
+ * Reverse formatMobile: turn a 13-char PromptPay proxy back into a national
+ * mobile number so it round-trips through generatePromptPay.
+ * e.g. "0066812345678" -> "0812345678"
+ * @param {string} proxy
+ * @returns {string}
+ */
+function proxyToMobile(proxy) {
+  let s = String(proxy).replace(/^0+/, ''); // drop the left-pad zeros
+  if (s.startsWith('66')) s = s.slice(2); // drop the country code
+  return '0' + s;
+}
+
+/**
+ * Detect a QR's PromptPay type from its decoded fields.
+ * @param {object} fields decode().fields
+ * @returns {'promptpay'|'kshop'|'billpayment'|'unknown'}
+ */
+function detectType(fields) {
+  if (fields['29']) return 'promptpay';
+  if (fields['30'] && fields['31']) return 'kshop';
+  if (fields['30']) return 'billpayment';
+  return 'unknown';
+}
+
+// PromptPay merchant-account templates -> rail name.
+const PROMPTPAY_TAG = { '29': 'credit-transfer', '30': 'bill-payment', '31': 'payment-innovation' };
+
+// EMVCo fixed template-ID allocations for card networks.
+const CARD_NETWORK_BY_TAG = {
+  '02': 'visa', '03': 'visa',
+  '04': 'mastercard', '05': 'mastercard',
+  '09': 'discover', '10': 'discover',
+  '11': 'amex', '12': 'amex',
+  '13': 'jcb', '14': 'jcb',
+  '15': 'unionpay', '16': 'unionpay',
+};
+
+// Card-network Registered Application Provider IDs (RID = first 10 chars of AID),
+// used to classify the generic merchant-template range 26-51 by its sub-tag 00.
+const CARD_RID = {
+  A000000003: 'visa', A000000004: 'mastercard', A000000025: 'amex',
+  A000000065: 'jcb', A000000152: 'discover', A000000333: 'unionpay',
+};
+
+/**
+ * Detect which payment rails a QR advertises. KShop (and other merchant QRs)
+ * include a separate template per enrolled rail, so an omitted template means
+ * that channel is not offered — e.g. a merchant not configured to accept cards
+ * has no card templates.
+ *
+ * Note: this reflects what the merchant has ENROLLED (capability advertised by
+ * the QR). Whether a given card actually authorizes is still the acquirer's
+ * decision at settlement.
+ *
+ * @param {string|object} qr A payload string or a prior decode() result.
+ * @returns {{
+ *   promptpay: boolean, creditCard: boolean,
+ *   networks: string[],
+ *   promptpayTemplates: string[], cardTemplates: string[]
+ * }}
+ */
+function channels(qr) {
+  const d = typeof qr === 'string' ? decode(qr) : qr;
+  const networks = new Set();
+  const promptpayTemplates = [];
+  const cardTemplates = [];
+
+  for (const { id } of d.tags) {
+    if (PROMPTPAY_TAG[id]) {
+      promptpayTemplates.push(id);
+      continue;
+    }
+    if (CARD_NETWORK_BY_TAG[id]) {
+      networks.add(CARD_NETWORK_BY_TAG[id]);
+      cardTemplates.push(id);
+      continue;
+    }
+    // Generic merchant-template range 26-51: classify by AID/RID in sub-tag 00.
+    const n = parseInt(id, 10);
+    if (n >= 26 && n <= 51 && typeof d.fields[id] === 'object') {
+      const aid = d.fields[id]['00'] || '';
+      if (aid.startsWith('A000000677')) {
+        // A PromptPay template living in the 26-51 range (rare); count it too.
+        if (!promptpayTemplates.includes(id)) promptpayTemplates.push(id);
+      } else if (CARD_RID[aid.slice(0, 10)]) {
+        networks.add(CARD_RID[aid.slice(0, 10)]);
+        cardTemplates.push(id);
+      }
+    }
+  }
+
+  return {
+    promptpay: promptpayTemplates.length > 0,
+    creditCard: networks.size > 0,
+    networks: [...networks],
+    promptpayTemplates,
+    cardTemplates,
+  };
+}
+
+/**
+ * Detach a master QR into its reusable account info and its per-transaction
+ * values. Works for all three types (auto-detected):
+ *
+ *   - promptpay  : account { mobile | nationalId | ewallet }, transaction { amount, dynamic }
+ *   - billpayment: account { billerId, merchantName?, merchantCity? },
+ *                  transaction { ref1, ref2?, amount, dynamic }
+ *   - kshop      : account = kshopParamsFrom(qr), transaction { amount, reference }
+ *
+ * Regenerate a fresh QR from the parts:
+ *   promptpay   -> generatePromptPay({ ...account, ...transaction })
+ *   billpayment -> generateBillPayment({ ...account, ...transaction })
+ *   kshop       -> generateKShopQR(transaction.amount, transaction.reference, account)
+ *
+ * @param {string|object} qr A payload string or a prior decode() result.
+ * @returns {{ type: string, account: object, transaction: object, channels: object, decoded: object }}
+ */
+function detach(qr) {
+  const d = typeof qr === 'string' ? decode(qr) : qr;
+  const f = d.fields;
+  const type = detectType(f);
+
+  let account = {};
+  let transaction = {};
+
+  if (type === 'promptpay') {
+    const t29 = f['29'] || {};
+    if (t29['01'] != null) account.mobile = proxyToMobile(t29['01']);
+    else if (t29['02'] != null) account.nationalId = t29['02'];
+    else if (t29['03'] != null) account.ewallet = t29['03'];
+    transaction = { amount: d.amount, dynamic: d.poiMethod === '12' };
+  } else if (type === 'kshop') {
+    account = kshopParamsFrom(d); // includes dynamic + all merchant/card fields
+    // The order reference lives in 30/03 (mirrored in 31/04).
+    const ref = (f['30'] || {})['03'];
+    transaction = { amount: d.amount, reference: ref != null ? ref : undefined };
+  } else if (type === 'billpayment') {
+    const t30 = f['30'] || {};
+    if (t30['01'] != null) account.billerId = t30['01'];
+    if (f['59'] != null) account.merchantName = f['59'];
+    if (f['60'] != null) account.merchantCity = f['60'];
+    transaction = {
+      ref1: t30['02'],
+      ref2: t30['03'] != null ? t30['03'] : undefined,
+      amount: d.amount,
+      dynamic: d.poiMethod === '12',
+    };
+  } else {
+    // Unknown layout: hand back the raw decoded fields so nothing is lost.
+    account = { fields: f };
+    transaction = { amount: d.amount };
+  }
+
+  return { type, account, transaction, channels: channels(d), decoded: d };
+}
+
+module.exports = { decode, parseTLV, kshopParamsFrom, detach, detectType, channels };

package/docs/promptpay-qr-structure.md

@@ -67,14 +67,23 @@ Example: `000201` = ID `00`, LEN `02`, VALUE `01`.
 
 ## 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) |
+PromptPay merchant-account templates begin with sub-tag `00` = the AID. The
+values below are from the **Bank of Thailand "Policy Guideline: Standardized
+Thai QR Code for Payment Transactions" (17 April 2019)** — see §11.
+
+| AID | Purpose | Template | Source |
+|-----|---------|----------|--------|
+| `A000000677010111` | Credit Transfer w/ PromptPay ID (merchant-presented) | tag `29` | BOT |
+| `A000000677010114` | Credit Transfer (customer-presented) | tag `29` | BOT |
+| `A000000677010112` | Bill Payment — **domestic** merchant | tag `30` | BOT |
+| `A000000677012006` | Bill Payment — **cross-border** merchant | tag `30` | BOT |
+| `A000000677012004` | Payment Innovation (API) | tag `31` | BOT |
+| `A000000677010113` | Payment Innovation (as seen in KBank/KShop QRs) | tag `31` | **vendor — not in BOT guideline** |
+
+> ⚠️ The original PHP and real KShop QRs use `A000000677010113` in tag `31`. That
+> value is **not** documented in the BOT guideline (which lists `A000000677012004`
+> for the Payment-Innovation API template). It appears to be a KBank/KShop-specific
+> usage; the library reproduces whatever the caller/config provides.
 
 ---
 
@@ -83,12 +92,17 @@ PromptPay merchant-account templates begin with sub-tag `00` = the AID.
 ```
 29 LL
    00 16 A000000677010111      ← AID
-   01 13 0066812345678         ← mobile  (one of 01/02/03)
+   01 13 0066812345678         ← mobile  (one of 01..05)
    02 13 1234567890123         ← national ID / tax ID
    03 15 123456789012345       ← e-wallet ID
+   04 .. <bankcode+accountno>  ← bank account (BOT: ans, up to 43)
+   05 10 <OTA>                 ← mandatory if AID = ...010114 (customer-presented)
 ```
 
-Provide **exactly one** of sub-tags `01`/`02`/`03`.
+Provide **exactly one** of the identifier sub-tags. Per the BOT guideline,
+tag 29 also defines `04` (bank account = 3-digit bank code + account no.) and
+`05` (OTA, mandatory for the customer-presented AID). This library generates
+`01`/`02`/`03` (the common cases).
 
 **Mobile normalization** (sub-tag `01`, always 13 chars):
 1. Strip non-digits.
@@ -113,12 +127,16 @@ E-wallet ID → sub-tag `03`, 15 digits as-is.
    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.
+Per the BOT guideline, tag 30 fields are: `00` AID (M), `01` Biller ID
+(N, **15**, M), `02` Reference 1 (ans, up to **20**, **M**), `03` Reference 2
+(ans, up to **20**, **O**).
+
+- **Biller ID**: "National ID / Tax ID + Suffix" — the merchant's 13-digit tax
+  ID plus a 2-digit suffix, so 15 chars. Bank-assigned.
+- **Reference 1 (`02`)**: **mandatory** (per BOT). Biller-defined meaning —
+  usually the customer/account/invoice identifier. Alphanumeric, ≤20.
+- **Reference 2 (`03`)**: **optional** (per BOT). Secondary reference (branch,
+  terminal, order id). Alphanumeric, ≤20. 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
@@ -166,14 +184,30 @@ payload += "6304" + crc16(payload + "6304").toString(16).toUpperCase().padStart(
 
 ## 8. Static vs Dynamic (tag 01)
 
-| Value | Meaning |
-|-------|---------|
-| `11` | **Static** — reusable; amount usually omitted, payer types it. |
-| `12` | **Dynamic** — single use; amount (`54`) present. |
+Per EMVCo, tag `01` signals **intent**, not a technical lock:
+
+| Value | EMVCo definition |
+|-------|------------------|
+| `11` | **Static** — use when *the same QR is shown for more than one transaction*. |
+| `12` | **Dynamic** — use when *a new QR is shown for each transaction* (usually carries amount/reference). |
 
-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.
+Important nuances:
+
+- **The payload does not enforce single use.** A `12` payload has no nonce,
+  counter, expiry, or session token — it is just static text with `01=12`. So a
+  "dynamic" QR is physically **reusable**: re-scanning yields the same valid
+  payload. Whether a second payment is *accepted* is decided by the bank /
+  issuer back-end, not by the QR. (Observed: SCB accepts repeat payments on a
+  `12` QR.)
+- **An amount can appear under either value.** Including tag `54` doesn't
+  require `12`; e.g. KShop-style QRs use `11` *with* an amount (see §9), and
+  that form has the widest bank-app acceptance — notably **K PLUS rejects `12`**
+  for that merchant family.
+- Common shorthand calls `12` "one-time", but that's a convention (POS shows a
+  fresh code per sale), not a property of the payload.
+
+Practical guidance: omit `54` ⇒ `11` (reusable, payer types amount); fixed
+amount ⇒ either works — choose based on the target apps' acceptance.
 
 ---
 
@@ -229,3 +263,22 @@ only when they are provided.
 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.
+
+---
+
+## 11. Official source
+
+The PromptPay-specific tags (29/30/31 AIDs and sub-tags, biller/reference
+definitions) in this document were verified against the **Bank of Thailand**
+primary source:
+
+> **"Policy Guideline: Standardized Thai QR Code for Payment Transactions"**,
+> Bank of Thailand, effective **17 April 2019 (B.E. 2562)**.
+> EN: <https://www.bot.or.th/content/dam/bot/fipcs/documents/FPG/2562/EngPDF/25620084.pdf>
+> TH: <https://www.bot.or.th/content/dam/bot/fipcs/documents/FPG/2562/ThaiPDF/25620084.pdf>
+
+All top-level tags not specific to PromptPay (52/53/54/58/59/60/62/63 and the
+Point of Initiation method `01`) are defined by **EMVCo "QR Code Specification
+for Payment Systems: Merchant-Presented Mode (MPM)"**, which the BOT guideline
+references rather than redefines. In particular, the BOT guideline does **not**
+add its own static/dynamic semantics for tag `01` — see §8.

package/index.js

@@ -2,8 +2,8 @@
 
 const { crc16Ccitt, crc16Hex } = require('./crc');
 const { generatePromptPay, generateBillPayment, formatMobile } = require('./promptpay');
-const { generateKShopQR, KSHOP_DEFAULTS } = require('./kshop');
-const { decode, parseTLV, kshopParamsFrom } = require('./decode');
+const { generateKShopQR, KSHOP_DEFAULTS, AID_PAYMENT_INNOVATION, AID_PAYMENT_INNOVATION_BOT } = require('./kshop');
+const { decode, parseTLV, kshopParamsFrom, detach, detectType, channels } = require('./decode');
 const image = require('./image');
 
 module.exports = {
@@ -14,10 +14,15 @@ module.exports = {
   formatMobile,
   generateKShopQR,
   KSHOP_DEFAULTS,
+  AID_PAYMENT_INNOVATION, // tag 31 AID — KBank/KShop (default)
+  AID_PAYMENT_INNOVATION_BOT, // tag 31 AID — Bank of Thailand guideline
   // Decoding / parsing.
   decode,
   parseTLV,
   kshopParamsFrom,
+  detach,
+  detectType,
+  channels,
   // Optional image helpers (require the `qrcode` package).
   image,
   toFile: image.toFile,

package/kshop.js

@@ -1,12 +1,18 @@
 'use strict';
 
 const { crc16Hex } = require('./crc');
+const { poiMethod } = require('./promptpay');
 
 // ---- 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 AID_MERCHANT_PRESENTED = 'A000000677010111'; // credit transfer -> tag 29 (BOT)
+const AID_DOMESTIC = 'A000000677010112'; // bill payment, domestic -> tag 30 (BOT)
+const AID_CUSTOMER_PRESENTED = 'A000000677010114'; // credit transfer, customer-presented (BOT)
+// Tag 31 (Payment Innovation) AID. The Bank of Thailand guideline documents
+// `A000000677012004`; KBank/KShop QRs in the wild use `A000000677010113`. The
+// KShop value is the default so real KShop QRs round-trip; pass
+// `innovationAid` to override (e.g. AID_PAYMENT_INNOVATION_BOT).
+const AID_PAYMENT_INNOVATION = 'A000000677010113'; // tag 31 — KBank/KShop (vendor)
+const AID_PAYMENT_INNOVATION_BOT = 'A000000677012004'; // tag 31 — BOT guideline
 const CURRENCY_THB = '764';
 const COUNTRY_CODE = 'TH';
 
@@ -54,7 +60,14 @@ function formatAmount(amount) {
 // 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)
+  // Point of initiation (tag 01) uses the shared poiMethod rule: the `dynamic`
+  // flag wins, else amount-driven. KShop defaults `dynamic` to FALSE (static,
+  // POI '11') for maximum bank-app compatibility — notably K PLUS rejects
+  // dynamic (POI '12') for this merchant QR family, while static-with-amount
+  // works in K PLUS, KShop, SCB, KTB, BBL and UOB. Pass dynamic:true to force
+  // POI '12' when targeting apps that accept it.
+  dynamic: false,
+  innovationAid: AID_PAYMENT_INNOVATION, // tag 31 / 00 (KShop default; see AID_PAYMENT_INNOVATION_BOT)
   innovationSubId: '004', // tag 31 / 01 (network sub-id used by the KShop format)
   currency: CURRENCY_THB, // tag 53
   countryCode: COUNTRY_CODE, // tag 58
@@ -77,7 +90,12 @@ const REQUIRED_FIELDS = ['billerId', 'merchantRef', 'merchantName', 'merchantCit
  * @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 {boolean} [config.dynamic]     tag 01: force true='12' / false='11'.
+ *                                        Auto if omitted (dynamic when amount present).
+ * @param {string} [config.innovationAid]   tag 31/00 AID. Default is the
+ *                                           KBank/KShop value; pass
+ *                                           `AID_PAYMENT_INNOVATION_BOT` for the
+ *                                           Bank of Thailand-documented AID.
  * @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').
@@ -100,9 +118,11 @@ function generateKShopQR(amount, reference, config = {}) {
     throw new Error('generateKShopQR: reference is required');
   }
 
+  const hasAmount = amount != null && amount !== '';
+
   let payload = '';
   payload += buildTagPayload('00', ['01']);
-  payload += buildTagPayload('01', [cfg.dynamic ? '12' : '11']);
+  payload += buildTagPayload('01', [poiMethod(cfg.dynamic, hasAmount)]);
   if (cfg.visaTemplate) payload += buildTagPayload('02', [cfg.visaTemplate]);
   if (cfg.mastercardTemplate) payload += buildTagPayload('04', [cfg.mastercardTemplate]);
   if (cfg.unionpayTemplate) payload += buildTagPayload('15', [cfg.unionpayTemplate]);
@@ -113,7 +133,7 @@ function generateKShopQR(amount, reference, config = {}) {
     '03': reference,
   });
   payload += buildTagPayload('31', {
-    '00': AID_PAYMENT_INNOVATION,
+    '00': cfg.innovationAid,
     '01': cfg.innovationSubId,
     '02': cfg.merchantRef,
     '04': reference,
@@ -123,7 +143,9 @@ function generateKShopQR(amount, reference, config = {}) {
   }
   if (cfg.mcc) payload += buildTagPayload('52', [cfg.mcc]);
   payload += buildTagPayload('53', [cfg.currency]);
-  payload += buildTagPayload('54', [formatAmount(amount)]);
+  // Tag 54 (amount) only when an amount is supplied — a no-amount KShop QR is a
+  // valid static "payer enters amount" master.
+  if (hasAmount) payload += buildTagPayload('54', [formatAmount(amount)]);
   payload += buildTagPayload('58', [cfg.countryCode]);
   payload += buildTagPayload('59', [cfg.merchantName]);
   payload += buildTagPayload('60', [cfg.merchantCity]);
@@ -139,10 +161,14 @@ module.exports = {
   buildTagPayload,
   KSHOP_DEFAULTS,
   REQUIRED_FIELDS,
+  // AIDs exported for callers who want to override tag 31 (e.g. BOT vs KShop).
+  AID_PAYMENT_INNOVATION,
+  AID_PAYMENT_INNOVATION_BOT,
   constants: {
     AID_MERCHANT_PRESENTED,
     AID_DOMESTIC,
     AID_PAYMENT_INNOVATION,
+    AID_PAYMENT_INNOVATION_BOT,
     AID_CUSTOMER_PRESENTED,
     CURRENCY_THB,
     COUNTRY_CODE,

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "promptpay-qrcode",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Zero-dependency PromptPay QR payload generator (PromptPay P2P, Tag 30 bill payment / Mae Manee, and KShop)",
   "main": "index.js",
   "type": "commonjs",
+  "bin": {
+    "promptpay-qr": "cli.js"
+  },
   "files": [
     "crc.js",
     "promptpay.js",
@@ -11,6 +14,7 @@
     "decode.js",
     "image.js",
     "index.js",
+    "cli.js",
     "docs/promptpay-qr-structure.md",
     "README.md",
     "LICENSE"
@@ -18,7 +22,8 @@
   "scripts": {
     "test": "node test.js",
     "example": "node example.js",
-    "example:image": "node example-image.js"
+    "example:image": "node example-image.js",
+    "decode": "node cli.js"
   },
   "peerDependencies": {
     "qrcode": "^1.5.0"

package/promptpay.js

@@ -23,6 +23,12 @@ function tlv(id, value) {
 /**
  * Resolve the Point of Initiation Method value (tag 01).
  *
+ * Per EMVCo, '11' (static) = the same QR is shown for more than one
+ * transaction; '12' (dynamic) = a new QR is shown for each transaction. This is
+ * an intent marker only — the payload does not enforce single use, so a '12' QR
+ * is still physically reusable; whether a repeat payment is accepted is up to
+ * the bank back-end. An amount may appear under either value.
+ *
  * `dynamic` overrides when set (`true` -> '12', `false` -> '11'). When left
  * undefined it defaults to dynamic if an amount is present, static otherwise.
  *
@@ -138,4 +144,4 @@ function generateBillPayment({ billerId, ref1, ref2, amount, dynamic, merchantNa
   return payload;
 }
 
-module.exports = { generatePromptPay, generateBillPayment, formatMobile, tlv };
+module.exports = { generatePromptPay, generateBillPayment, formatMobile, tlv, poiMethod };