promptpay-qrcode 1.1.0 → 1.2.1

package/README.md

@@ -65,9 +65,17 @@ generateBillPayment({
   dynamic: true,               // optional; force POI (true='12', false='11')
   merchantName: 'MY SHOP',     // optional (tag 59)
   merchantCity: 'BANGKOK',     // optional (tag 60)
+  additionalData: '07160000…', // optional raw tag 62 (e.g. terminal label sub-TLV)
+  countryCode: 'TH',           // optional (tag 58, default 'TH')
 });
 ```
 
+Tag order matches real Thai bill-payment QRs (`00,01,30,58,53,…,62,63` — note
+`58` before `53`), so a decoded bill-payment QR round-trips **byte-for-byte**:
+`generateBillPayment({ ...account, ...transaction })` from a `detach()` of an
+SCB/Mae Manee QR reproduces the original exactly (including its tag-62 terminal
+label).
+
 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.
 
@@ -142,6 +150,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
@@ -270,14 +306,15 @@ The second `options` argument is passed straight through to `qrcode`
 | Function | Returns |
 | --- | --- |
 | `generatePromptPay({ mobile \| nationalId \| ewallet, amount?, dynamic? })` | payload string |
-| `generateBillPayment({ billerId, ref1, ref2?, amount?, dynamic?, merchantName?, merchantCity? })` | payload string |
+| `generateBillPayment({ billerId, ref1, ref2?, amount?, dynamic?, merchantName?, merchantCity?, additionalData?, countryCode? })` | 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 |
-| `detach(qr)` | `{ type, account, transaction, decoded }` for any QR type |
+| `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`)* |

package/cli.js

@@ -61,15 +61,21 @@ function main() {
   }
 
   if (json) {
-    console.log(JSON.stringify({ type: r.type, account: r.account, transaction: r.transaction, crc: d.crc }, null, 2));
+    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));

package/decode.js

@@ -174,6 +174,82 @@ function detectType(fields) {
   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):
@@ -189,7 +265,7 @@ function detectType(fields) {
  *   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, decoded: object }}
+ * @returns {{ type: string, account: object, transaction: object, channels: object, decoded: object }}
  */
 function detach(qr) {
   const d = typeof qr === 'string' ? decode(qr) : qr;
@@ -215,6 +291,10 @@ function detach(qr) {
     if (t30['01'] != null) account.billerId = t30['01'];
     if (f['59'] != null) account.merchantName = f['59'];
     if (f['60'] != null) account.merchantCity = f['60'];
+    if (f['58'] != null) account.countryCode = f['58'];
+    // Tag 62 (Additional Data) — keep the raw inner string so it round-trips.
+    const raw62 = flattenTag62(d.tags);
+    if (raw62 != null) account.additionalData = raw62;
     transaction = {
       ref1: t30['02'],
       ref2: t30['03'] != null ? t30['03'] : undefined,
@@ -227,7 +307,7 @@ function detach(qr) {
     transaction = { amount: d.amount };
   }
 
-  return { type, account, transaction, decoded: d };
+  return { type, account, transaction, channels: channels(d), decoded: d };
 }
 
-module.exports = { decode, parseTLV, kshopParamsFrom, detach, detectType };
+module.exports = { decode, parseTLV, kshopParamsFrom, detach, detectType, channels };

package/index.js

@@ -3,7 +3,7 @@
 const { crc16Ccitt, crc16Hex } = require('./crc');
 const { generatePromptPay, generateBillPayment, formatMobile } = require('./promptpay');
 const { generateKShopQR, KSHOP_DEFAULTS, AID_PAYMENT_INNOVATION, AID_PAYMENT_INNOVATION_BOT } = require('./kshop');
-const { decode, parseTLV, kshopParamsFrom, detach, detectType } = require('./decode');
+const { decode, parseTLV, kshopParamsFrom, detach, detectType, channels } = require('./decode');
 const image = require('./image');
 
 module.exports = {
@@ -22,6 +22,7 @@ module.exports = {
   kshopParamsFrom,
   detach,
   detectType,
+  channels,
   // Optional image helpers (require the `qrcode` package).
   image,
   toFile: image.toFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptpay-qrcode",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Zero-dependency PromptPay QR payload generator (PromptPay P2P, Tag 30 bill payment / Mae Manee, and KShop)",
   "main": "index.js",
   "type": "commonjs",

package/promptpay.js

@@ -115,9 +115,18 @@ function generatePromptPay({ mobile, nationalId, ewallet, amount, dynamic } = {}
  * @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).
+ * @param {string} [opts.additionalData] Raw Additional Data Field (tag 62) value,
+ *                                       e.g. terminal label sub-TLV "0716...".
+ * @param {string} [opts.countryCode]  Country code (tag 58). Default 'TH'.
  * @returns {string} The EMVCo QR payload including CRC.
+ *
+ * Tag order follows the layout used by real Thai bill-payment QRs (SCB / Mae
+ * Manee): `00,01,30,58,53,[54],[59],[60],[62],63` — note `58` precedes `53`.
+ * This lets a decoded bill-payment QR round-trip byte-for-byte.
  */
-function generateBillPayment({ billerId, ref1, ref2, amount, dynamic, merchantName, merchantCity } = {}) {
+function generateBillPayment({
+  billerId, ref1, ref2, amount, dynamic, merchantName, merchantCity, additionalData, countryCode,
+} = {}) {
   if (!billerId) throw new Error('billerId is required');
   if (!ref1) throw new Error('ref1 is required');
 
@@ -132,13 +141,14 @@ function generateBillPayment({ billerId, ref1, ref2, amount, dynamic, merchantNa
   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('58', countryCode || COUNTRY_TH); // country (before currency, per Thai QR layout)
   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);
+  if (additionalData) payload += tlv('62', String(additionalData));
 
   payload += '6304' + crc16Hex(payload + '6304');
   return payload;