// In a Cloudflare Worker return new Response(svg, { headers: { 'content-type': 'image/svg+xml; charset=utf-8' }, }); ``` ## Why assets are opt-in from the umbrella `import { ... } from 'thai-qr-payment'` (the default umbrella entry) does **not** include the brand SVGs — that keeps the surface lean (~3 KB for payload-only callers). The renderer helpers (`renderThaiQRPayment`, `renderCard`) still reach for the assets internally; they're only excluded from the top-level re-export. To get the asset map at the top level: ```ts import { COLOR_LOGOS, colorLogo } from 'thai-qr-payment/assets'; ``` ## Brand compliance The marks belong to their respective rights-holders: - **Thai QR Payment** logo — Bank of Thailand / Thai Bankers' Association - **PromptPay** logo — Bank of Thailand / National ITMX This package redistributes the raster → vector conversion of publicly distributed artwork. **Downstream apps must comply with the official Thai QR Payment Brand Guidelines.** If a rights-holder requests removal, open a [GitHub issue](https://github.com/uunw/thai-qr-payment/issues) and the mark will be pulled from the next published version within 7 days. # BOT barcode > Build + parse the Bank of Thailand 1D bill-payment barcode. ## Why The **Bank of Thailand 1D bill-payment barcode** is the one-dimensional ASCII string printed on Thai utility bills, scanned at bank tellers, 7-Eleven counters, and kiosk machines for over-the-counter bill payments. It is **not** EMVCo, **not** a QR, **not** TLV — the wire format is a `|`-led `\r`-delimited string with no checksum. It lives in the same `@thai-qr-payment/payload` package because the `billerId` / `ref1` / `ref2` vocabulary matches the Thai bill-payment merchant template (EMVCo tag 30), but the on-wire bytes are unrelated. The module sits behind its own export so callers who only need the QR path can tree-shake it away. ```ts import { buildBOTBarcode, parseBOTBarcode } from 'thai-qr-payment'; ``` ## Build `buildBOTBarcode({ billerId, ref1, ref2?, amount? })`. `billerId` is the 15-char cross-bank biller id (Tax ID + suffix); shorter inputs are zero-padded on the left, longer ones throw. `ref1` is required; `ref2` defaults to the empty string on the wire when omitted. ```ts buildBOTBarcode({ billerId: '099400016550100', ref1: '123456789012', ref2: '670429', amount: 3649.22, }); // '|099400016550100\r123456789012\r670429\r364922' ``` The trailing amount is stored as **integer satang** (baht × 100, rounded). Omit it (or pass `0`) for a counter-keyed total — the literal `'0'` sentinel is written and the cashier types the amount in by hand: ```ts buildBOTBarcode({ billerId: '099999999999990', ref1: '111222333444' }); // '|099999999999990\r111222333444\r\r0' ``` Throws on malformed input — negative / non-finite amounts, over-long biller ids, CR characters inside any field, empty `ref1`. The caller never silently produces an unscannable barcode. ## Parse `parseBOTBarcode(barcode)` returns the decoded fields, or `null` on any structural issue (missing prefix, wrong field count, biller id too short). Amount comes back as a decimal baht number; the `'0'` sentinel surfaces as `undefined`. ```ts parseBOTBarcode('|099400016550100\r123456789012\r670429\r364922'); // { // billerId: '099400016550100', // ref1: '123456789012', // ref2: '670429', // amount: 3649.22, // } parseBOTBarcode('|099999999999990\r111222333444\r\r0'); // { billerId: '099999999999990', ref1: '111222333444' } ``` `null` instead of an exception lets you branch without `try / catch` — useful when consuming arbitrary scanner input that may or may not be a BOT barcode. ## Sample wires | Wire (escaped) | Decoded | | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `\|099999999999990\r111222333444\r\r0` | `{ billerId: '099999999999990', ref1: '111222333444' }` | | `\|099400016550100\r123456789012\r670429\r364922` | `{ billerId: '099400016550100', ref1: '123456789012', ref2: '670429', amount: 3649.22 }` | Wire bytes: `\|` is a literal pipe (0x7C, the sentinel); each `\r` is a single carriage return (0x0D); no terminator at the end. The string is always exactly one pipe + three `\r` separators regardless of which optional fields are populated — empty slots are zero-width on the wire. # CLI > thai-qr-payment / tqp command-line tool for one-off QR generation.  ```bash # Zero-install — npx (umbrella package, single tarball) npx thai-qr-payment 0812345678 --amount 50 -o qr.svg npx tqp 0812345678 --amount 50 -o qr.svg # Global install pnpm add -g thai-qr-payment thai-qr-payment 0812345678 --amount 50 --merchant "Acme Coffee" -o qr.svg tqp 0812345678 --format payload ``` ### npx + scoped CLI package `@thai-qr-payment/cli` exposes the same two binaries (`thai-qr-payment` and `tqp`), but the **binary names don't match the package name**. npx can't auto-resolve `@thai-qr-payment/cli` to a binary called `thai-qr-payment`, so `npx @thai-qr-payment/cli 0812345678` fails with `command not found`. Pass the binary name explicitly via `--package`: ```bash # Wrong — npx looks for a `@thai-qr-payment/cli` binary, finds none npx @thai-qr-payment/cli 0812345678 --amount 50 # → sh: thai-qr-payment: command not found # Right — use the umbrella (recommended, single tarball) npx thai-qr-payment 0812345678 --amount 50 # Right — scoped CLI with --package npx --package=@thai-qr-payment/cli thai-qr-payment 0812345678 --amount 50 npx --package=@thai-qr-payment/cli tqp 0812345678 --amount 50 ``` The umbrella is preferred (one tarball, all deps inlined). Reach for the scoped CLI only if you're pinning specific package versions in an automation script. ## Modes ### Card (default) ```bash thai-qr-payment 0812345678 --amount 50 --merchant "Acme Coffee" -o qr.svg ``` Full SVG card with Thai QR Payment + PromptPay headers, merchant name, and amount label. ### Matrix ```bash thai-qr-payment 0812345678 --amount 50 --format matrix --size 512 -o qr.svg ``` Just the QR matrix as a square SVG. Caller-controlled size. ### Payload ```bash thai-qr-payment 0812345678 --amount 50 --format payload # 00020101021229370016A00000067701011101130066812345678530376454065000.005802TH63041234 ``` Raw EMVCo wire string. Useful for piping into another tool. ## Flags | Flag | Short | Notes | | ------------------- | ----- | ----------------------------------------------------------- | | `--recipient ` | `-r` | phone, nationalId, eWallet | | `--amount ` | `-a` | omit for static QR | | `--satang` | — | treat `--amount` as integer satang | | `--type ` | — | `mobile` / `nationalId` / `eWallet` — overrides auto-detect | | `--ecc ` | — | `L` / `M` / `Q` / `H` (default `M`) | | `--format ` | `-f` | `card` (default) / `matrix` / `payload` | | `--theme ` | — | `color` (default) / `silhouette` | | `--merchant ` | `-m` | rendered above the QR (card mode) | | `--size ` | — | matrix mode output size | | `--output ` | `-o` | write to file (default stdout) | | `--help` | `-h` | show help | | `--version` | `-v` | show CLI version | ## Examples ```bash # Dynamic 50 THB card written to file thai-qr-payment 0812345678 --amount 50 --merchant "Acme" -o qr.svg # Bare 512 px QR matrix with high error correction thai-qr-payment 0812345678 --amount 50 --format matrix --size 512 --ecc H -o qr.svg # Print just the payload (for piping) thai-qr-payment 0812345678 --amount 50 --format payload | tee payload.txt # Pay 50.50 from satang thai-qr-payment 0812345678 --amount 5050 --satang -o qr.svg # Silhouette theme (monochrome brand artwork) thai-qr-payment 0812345678 --amount 50 --theme silhouette -o qr.svg # National ID recipient thai-qr-payment 1234567890123 --type nationalId --amount 100 -o qr.svg # e-Wallet recipient thai-qr-payment 123456789012345 --type eWallet --amount 200 -o qr.svg ``` # Payload (EMVCo TLV) > Build + parse Thai QR Payment wire payloads with @thai-qr-payment/payload.  `@thai-qr-payment/payload` implements the **EMVCo Merchant-Presented-Mode v1.1** TLV grammar plus the **Bank of Thailand Thai QR Payment supplement** (PromptPay, BillPayment, TrueMoney, OTA, VAT TQRC, cross-border ASEAN remittance). Zero dependencies, every JS runtime. ## One-shot helper ```ts import { payloadFor } from 'thai-qr-payment'; const wire = payloadFor({ recipient: '0812345678', amount: 50 }); // 00020101021229370016A000000677010111011300668123456785303764540550.005802TH6304XXXX ``` Reach for `ThaiQRPaymentBuilder` when you need merchant info, references, OTA, bank-account credit transfer, TrueMoney, VAT TQRC, or cross-border. ## Builder ```ts import { ThaiQRPaymentBuilder } from 'thai-qr-payment'; ``` Three terminal methods regardless of what you configure: `.build()` returns the wire string, `.buildWithChecksum()` splits the body / CRC for inspection, `.toBytes()` returns a `Uint8Array` for hashing or transport. ### `.promptpay(recipient, type?)` Mobile, national ID, or e-wallet recipient. Type is inferred from digit length when omitted: 9–12 → `mobile`, 13 → `nationalId`, 15 → `eWallet`. The override exists for the (rare) ambiguous case. ```ts new ThaiQRPaymentBuilder().promptpay('0812345678').amount(50).build(); new ThaiQRPaymentBuilder().promptpay('1234567890123', 'nationalId').amount(50).build(); new ThaiQRPaymentBuilder().promptpay('123456789012345', 'eWallet').amount(50).build(); ``` Mobile recipients are zero-padded to the 13-char `0066xxxxxxxxxx` wire form before encoding. ### `.bankAccount(bankCode, accountNo)` PromptPay credit transfer to a bank account (sub-tag 04 under tag 29). `bankCode` is the 3-digit BoT bank identifier (`'002'` Bangkok Bank, `'014'` SCB, …); `accountNo` is the variable-length numeric account. Combined wire value is capped at 43 chars per the EMVCo sub-tag limit. ```ts new ThaiQRPaymentBuilder().bankAccount('014', '1234567890').amount(100).build(); // 00020101021229370016A0000006770101110413014123456789053037645406100.005802TH6304901D ``` This method exists separately from `.promptpay(..., 'bankAccount')` because the wire value needs the (bankCode, accountNo) split a single string can't carry — calling `.promptpay(x, 'bankAccount')` throws. ### `.ota(otaCode)` Attach a **One-Time Authorization** code (sub-tag 05, exactly 10 chars). The AID swap is the whole point: the builder flips tag 29's GUID from `A000000677010111` (standard PromptPay) to `A000000677010114` (PromptPay OTA) so the receiving bank routes the payload through the single-use credit-transfer flow instead of the repeatable PromptPay merchant flow. ```ts new ThaiQRPaymentBuilder().promptpay('0812345678').ota('1234567890').amount(50).build(); // 00020101021229510016A00000067701011401130066812345678051012345678905303764540550.005802TH63048856 ``` Combines cleanly with `.bankAccount()` for an OTA bank-account transfer. ### `.trueMoney(mobileNo, { amount?, message? })` TrueMoney Wallet QR. Same merchant template tag as PromptPay (29) but with the literal `'14'` prefix on sub-tag 03 — that prefix is how the TrueMoney app discriminates its own payloads from a plain e-wallet QR. Mobile is zero-padded left to 13 digits, then prefixed; final sub-tag 03 value is always 15 chars. ```ts new ThaiQRPaymentBuilder().trueMoney('0801111111').build(); // 00020101021129390016A000000677010111031514000080111111153037645802TH63047C0F new ThaiQRPaymentBuilder().trueMoney('0801111111', { amount: 10, message: 'Hello World!' }).build(); // includes tag 81: '814800480065006C006C006F00200057006F0072006C00640021' ``` The optional `message` is carried in tag 81 as **UTF-16BE** hex (each Unicode code unit becomes 4 uppercase hex chars). It surfaces only inside the TrueMoney app — other wallets ignore it. See [personal message codec](#personal-message-codec) below for the raw encoder. ### `.billPayment({ billerId, reference1?, reference2?, crossBorder? })` BillPayment merchant template (tag 30). `billerId` is the cross-bank biller identifier (15 chars on the wire); references are application-defined. ```ts new ThaiQRPaymentBuilder() .billPayment({ billerId: '123456789012345', reference1: 'INV001', reference2: 'CUST42', }) .amount(250.5) .build(); ``` Pass `crossBorder: true` to emit the **ASEAN-region remittance AID** (`A000000677012006`) instead of the domestic one (`A000000677010112`) — same sub-tag layout, but receivers route the payment through the ASEAN PayNow / DuitNow / QRIS interop rails instead of the local PromptPay biller switch. ```ts new ThaiQRPaymentBuilder() .billPayment({ billerId: '099400016550100', reference1: '123456789012', crossBorder: true }) .amount(100) .build(); // 00020101021230550016A0000006770120060115099400016550100021212345678901253037645406100.005802TH63049D1C ``` Cross-border payloads pair with the `purposeOfTransaction` additional-data sub-field (tag 62 sub-tag 08), which carries an 18-char triple: currency code (3 digits) + local amount (13 digits) + country code (2 chars). The builder treats that triple opaquely — compose and parse it at the call site. ### `.amount(value, opts?)` THB amount. Two-decimal output, integer-math rounding (no `0.30000000000000004` surprises). Omit / pass `undefined` for a static QR — the consumer's banking app then prompts for the amount. ```ts .amount(50) // 50.00 .amount(99.5) // 99.50 .amount(12345, { fromSatang: true }) // 123.45 — integer satang input .amount(12345n, { fromSatang: true }) // BigInt also works .amount(undefined) // static QR (no tag 54) .amount(0) // same — zero collapses to static ``` Max wire value: 9,999,999,999.99 THB. Negative, `NaN`, or `Infinity` throws. Setting any non-zero amount flips the point-of-initiation tag from `11` (static) to `12` (dynamic) automatically. Override with `.pointOfInitiation('static' | 'dynamic')` if you need to force one. ### `.merchant({ name?, city?, postalCode?, categoryCode? })` Display fields. `name` is truncated to 25 chars, `city` to 15. `categoryCode` is the 4-digit ISO 18245 MCC. ```ts .merchant({ name: 'Acme Coffee', city: 'BANGKOK', postalCode: '10310', categoryCode: '5814', // Fast Food Restaurants }) ``` ### `.additionalData({...})` Sub-fields of tag 62. All nine slots: ```ts .additionalData({ billNumber: 'INV-2026-001', // sub-tag 01 mobileNumber: '02-123-4567', // sub-tag 02 storeLabel: 'STR01', // sub-tag 03 loyaltyNumber: 'LOY42', // sub-tag 04 referenceLabel: 'REF99', // sub-tag 05 customerLabel: 'CUST42', // sub-tag 06 terminalLabel: 'T01', // sub-tag 07 purposeOfTransaction: 'PURCHASE', // sub-tag 08 (or cross-border triple) consumerDataRequest: 'EMAIL', // sub-tag 09 }) ``` Multiple `.additionalData()` calls merge — later keys overwrite earlier ones for the same slot. ### `.tipPolicy({...})` Tags 55–57. ```ts .tipPolicy({ mode: 'prompt' }) // app asks the payer .tipPolicy({ mode: 'fixed', value: 10 }) // 10.00 THB .tipPolicy({ mode: 'fixed', value: 1000, fromSatang: true }) .tipPolicy({ mode: 'percentage', value: 5 }) // 5.00 % .tipPolicy(undefined) // clear ``` A zero fixed tip throws — pass `undefined` instead. ### `.vatTqrc({ sellerTaxBranchId, vatRate?, vatAmount })` Bank of Thailand **VAT TQRC** extension (top-level tag 80). Promotes a regular PromptPay payment QR into a **Tax-Qualified-QR-Code** source for Thai e-tax-receipt integrations — the receiving system reads the VAT split off the QR and emits a compliant electronic receipt without a separate API call. ```ts new ThaiQRPaymentBuilder() .promptpay('0812345678') .amount(107) .vatTqrc({ sellerTaxBranchId: '0001', vatRate: '7', vatAmount: '7.00' }) .build(); // …8021000400010101702047.00 6304XXXX ``` Field-length rules from the BoT extension spec: - `sellerTaxBranchId` — exactly 4 chars - `vatRate` — 1–5 chars when present (e.g. `'7'` or `'7.00'`); omit for VAT-inclusive receipts that don't display a rate - `vatAmount` — 1–13 chars, required Pass `undefined` to clear. ### `.build()` / `.buildWithChecksum()` / `.toBytes()` ```ts const wire = builder.build(); // "00020101…6304XXXX" const { body, checksum, payload } = builder.buildWithChecksum(); // body ends with "6304" (the CRC tag header is part of the hashed input) // checksum is the 4-char uppercase hex CRC // payload === body + checksum const bytes = builder.toBytes(); // Uint8Array — one byte per ASCII char in payload ``` CRC is **CRC-16/CCITT-FALSE** (poly `0x1021`, init `0xFFFF`, no reflect, no XOR out), computed over the body **plus** the `6304` tag header. Missing that header in your verifier is the classic off-by-spec mistake. ## Parser ```ts import { parsePayload } from 'thai-qr-payment'; ``` ### `parsePayload(payload, { strict? })` ```ts const parsed = parsePayload(wire); // { // payloadFormat: '01', // pointOfInitiation: 'dynamic', // merchant: { kind: 'promptpay', recipientType: 'mobile', recipient: '0812345678' }, // amount: 50, // currency: '764', // country: 'TH', // merchantName: 'Acme Coffee', // crc: { value: '901D', valid: true, truncated: false }, // rawTags: [...], // getTag(id), getTagValue(id, subId?), // ... // } ``` Default behaviour: - Verifies the trailing CRC. If the 4-char tail matches the recomputed checksum, returns `crc: { valid: true, truncated: false }`. - If the tail is 1–3 chars (some Thai banking apps strip leading zeros when re-encoding), tries left-padding with `0` until the checksum matches. On success returns `crc: { valid: true, truncated: true }` — the parsed merchant data is correct; surface a warning to the user if you care about reporting the source app's bug. - On unrecoverable mismatch: throws. Pass `{ strict: true }` to refuse the truncated-CRC auto-fix and throw on missing / mismatched CRC immediately. Use strict for trust-boundary parses (slip OCR, payment-link inputs); leave it off when consuming the output of a known-buggy app. ### `ParsedPayload` shape The `merchant` field is a discriminated union — narrow on `.kind`: ```ts type Merchant = ParsedPromptPay | ParsedBillPayment | ParsedTrueMoney | null; interface ParsedPromptPay { kind: 'promptpay'; recipientType: 'mobile' | 'nationalId' | 'eWallet' | 'bankAccount'; recipient: string; bankCode?: string; // set when recipientType === 'bankAccount' accountNo?: string; // set when recipientType === 'bankAccount' ota?: string; // 10-char OTA code when present } interface ParsedBillPayment { kind: 'billPayment'; billerId: string; reference1?: string; reference2?: string; crossBorder: boolean; // true when AID is A000000677012006 } interface ParsedTrueMoney { kind: 'trueMoney'; mobileNo: string; message?: string; // decoded from tag 81 UTF-16BE hex } ``` `merchant` is `null` only for payloads that lack a recognised merchant template — every PromptPay / BillPayment / TrueMoney shape resolves to a concrete kind. VAT TQRC, when present, lands at the top level: ```ts parsed.vatTqrc; // { sellerTaxBranchId: '0001', vatRate: '7', vatAmount: '7.00' } ``` In strict mode, a tag 80 with a malformed sub-template throws; otherwise it silently degrades to `vatTqrc: undefined`. ### Raw tag accessors For unknown / future tags, drop down to the raw TLV view: ```ts parsed.rawTags; // readonly [{ tag: '00', value: '01' }, { tag: '01', value: '12' }, …] parsed.getTag('58'); // { tag: '58', value: 'TH' } parsed.getTagValue('29', '00'); // 'A000000677010111' — the AID inside the merchant template parsed.getTagValue('62', '01'); // 'INV-2026-001' — billNumber sub-field ``` `getTagValue(id, subId?)` descends one level — pass just `id` for a top-level value, `(id, subId)` for nested templates (tags 29–31, 62, 64, 80). ## Low-level TLV helpers For tools that need to introspect / synthesise raw TLV runs without the full builder: ```ts import { encodeField, // (tag, value) → 'IILLDDDD…' encodeFields, // ([tag, value][]) → concatenated, null/empty entries dropped parseFields, // (input) → Map iterateFields, // (input) → IterableIterator<{tag, value}> checksum, // (input) → 4-char uppercase hex CRC-16/CCITT-FALSE Tags, // namespace of every spec-defined tag id constant } from 'thai-qr-payment'; encodeField('58', 'TH'); // '5802TH' encodeFields([ ['00', '01'], ['01', null], ]); // '000201' parseFields('5802TH5303764').get('53'); // '764' checksum('00020101…6304'); // 'ABCD' Tags.TAG_TRANSACTION_AMOUNT; // '54' Tags.GUID_PROMPTPAY; // 'A000000677010111' ``` `encodeField` throws if the value exceeds 99 bytes (the EMVCo 2-digit length cap); split across multiple tags at the call site. ## Personal message codec Tag 81's wire format is the UTF-16BE encoding of the message expressed as uppercase hex. Each Unicode code unit produces 4 hex chars. ```ts import { encodePersonalMessage, decodePersonalMessage } from 'thai-qr-payment'; encodePersonalMessage('Hello'); // '00480065006C006C006F' decodePersonalMessage('00480065006C006C006F'); // 'Hello' ``` `.trueMoney(mobile, { message })` calls `encodePersonalMessage` internally; `parsePayload` calls `decodePersonalMessage` for any tag 81 attached to a TrueMoney merchant. The raw codec is exported for callers that want to put the message on a different envelope. ## Tag coverage See the [spec coverage reference](/reference/spec/) for the complete tag-by-tag implementation table. # QR encoder > ISO/IEC 18004 QR Code encoder — Reed-Solomon + Galois field, zero dependencies.  The `@thai-qr-payment/qr` package implements ISO/IEC 18004 Model-2 QR Code generation. Reed-Solomon error correction over GF(2^8) is hand-rolled — no `qrcode`, no native bindings. ## Quickstart ```ts import { encodeQR } from 'thai-qr-payment'; const { size, modules, version, mask, errorCorrectionLevel } = encodeQR( '00020101021229370016A000000677010111...6304ABCD', { errorCorrectionLevel: 'H' }, ); // modules: boolean[][] — modules[y][x] === true → dark module // size: number — matrix dimension in modules // version: 1..40 // mask: 0..7 ``` The output is a pure data structure. Pair with `@thai-qr-payment/render` for SVG. ## API ### `encodeQR(text, options?)` | Option | Default | Notes | | ---------------------- | ------- | ------------------------------------------------- | | `errorCorrectionLevel` | `'M'` | `'L'` / `'M'` / `'Q'` / `'H'` | | `minVersion` | `1` | floor for version selection | | `maxVersion` | `40` | ceiling — throws if input doesn't fit | | `forceMask` | auto | `0..7` — auto-selected by penalty score otherwise | ### `detectMode(text)` ```ts detectMode('1234567890'); // 'numeric' detectMode('HELLO WORLD'); // 'alphanumeric' detectMode('สวัสดี'); // 'byte' (UTF-8 fallback) ``` EMVCo payloads always fit in `alphanumeric` mode (`[0-9A-Z $%*+-./:]`). ## How it works 1. **Mode detection** — narrowest viable mode (numeric → alphanumeric → byte) 2. **Version selection** — smallest version that fits the bit budget at the requested ECC level 3. **Bit packing** — mode indicator + char-count + data bits → packed codewords + filler 4. **Reed-Solomon ECC** — appended per ISO/IEC 18004 §7.5, blocks interleaved per §7.6 5. **Module placement** — finder + alignment + timing + format-info + version-info + data zigzag 6. **Mask selection** — all 8 masks scored on the four spec penalty rules; lowest wins ## Property tests | Invariant | Status | | -------------------------------------------------------------------- | -------------------- | | RS linearity: `enc(a) ⊕ enc(b) === enc(a ⊕ b)` | ✓ verified | | GF(2^8) distributivity: `a · (b ⊕ c) === (a·b) ⊕ (a·c)` | ✓ verified | | CRC-16/CCITT-FALSE determinism over 200 random inputs | ✓ | | Alignment-pattern centres pinned to ISO/IEC 18004 Annex E for v2-v40 | ✓ 10 pinned versions | ## v0.1.0 → v0.1.1 fix The initial v0.1.0 release shipped a bug in `alignmentCentres()` — every QR at version ≥ 2 placed alignment patterns at the wrong coordinates, so scanners rejected the output as "invalid". Fixed in v0.1.1 (commit `e4af92f`) with regression tests pinning the Annex E positions. **Pin to ≥ 0.1.1 in production.** # React component > and for React 18+ apps.  `@thai-qr-payment/react` wires the renderer into a typed React component. Works in CSR + SSR (Next.js, Remix, TanStack Start, vanilla Vite) — no jsdom needed, no `useEffect` rigging. ## Install ```bash pnpm add @thai-qr-payment/react react ``` `react` is a **peer dependency** — bring whichever version you're already using (≥ 18). ## Full card ```tsx import { ThaiQRPayment } from '@thai-qr-payment/react'; export function PaymentScreen() { return ( ); } ``` ## Bare matrix ```tsx import { ThaiQRPaymentMatrix } from '@thai-qr-payment/react'; ; ``` ## SSR Both components serialize on the server via `react-dom/server.renderToStaticMarkup`. The SVG is embedded directly into the HTML — no hydration handshake required. ```tsx // Next.js app router — server component export default function Page() { return ; } ``` ## Accessibility The wrapper carries `role="img"` and a generated `aria-label` (`"Thai QR Payment for "`). Override with `ariaLabel`: ```tsx ``` ## All props | Prop | Type | Notes | | --------------------------------- | --------------------------------------- | --------------------------------------- | | `recipient` | `string` | phone / nationalId / eWallet — required | | `amount` | `number` | THB, omit for static QR | | `recipientType` | `'mobile' \| 'nationalId' \| 'eWallet'` | override auto-detection | | `fromSatang` | `boolean` | treat `amount` as integer satang | | `errorCorrectionLevel` | `'L' \| 'M' \| 'Q' \| 'H'` | default `'M'` | | `merchantName` | `string` | rendered above the QR (card mode only) | | `amountLabel` | `string` | rendered below the QR (card mode only) | | `theme` | `'color' \| 'silhouette'` | brand artwork flavor | | `className`, `style`, `ariaLabel` | DOM pass-through | | ## React 19 ready `@thai-qr-payment/react` declares `react@>=18` as peer dep. The component itself uses no APIs removed in React 19 — string refs, `propTypes`/`defaultProps` for function components, legacy context — so it runs unmodified on both major versions. # SVG renderer > Compose a Thai QR Payment SVG card or bare matrix from a wire payload.  `@thai-qr-payment/render` ties together the payload builder, QR encoder, and brand assets into a single SVG string. No DOM, no canvas — works in every runtime. ## One-shot card ```ts import { renderThaiQRPayment } from 'thai-qr-payment'; const svg = renderThaiQRPayment({ recipient: '0812345678', amount: 50, merchantName: 'Acme Coffee', amountLabel: '฿ 50.00', errorCorrectionLevel: 'H', }); ``` Returns a full SVG card: Thai QR Payment header band + PromptPay sub-mark + bordered QR + amount label. ## Bare matrix When you want to wrap the QR in your own design system: ```ts import { renderThaiQRPaymentMatrix } from 'thai-qr-payment'; const svg = renderThaiQRPaymentMatrix({ recipient: '0812345678', amount: 50, size: 320, quietZone: 4, }); ``` ## Card options | Option | Default | Notes | | --------------- | ------------------------- | ------------------------------------------------------ | | `theme` | `color` | `'silhouette'` swaps brand artwork to monochrome paths | | `merchantName` | — | rendered above the QR | | `amountLabel` | — | rendered below the QR | | `background` | `#fff` | card backdrop | | `accent` | `#0a2540` | text + silhouette fill colour | | `headerLogo` | `Thai_QR_Payment_Logo-01` | override via `@thai-qr-payment/assets` registry name | | `promptpayLogo` | `PromptPay1` | override | ## Low-level building blocks ```ts import { encodeQR } from 'thai-qr-payment'; import { renderCard, renderQRSvg, matrixToPath } from 'thai-qr-payment'; const matrix = encodeQR(wireString, { errorCorrectionLevel: 'H' }); const svg = renderCard(matrix, { merchantName: 'Acme', amountLabel: '฿ 50' }); // Or even lower: const justTheQr = renderQRSvg(matrix, { size: 512, quietZone: 4 }); const pathData = matrixToPath(matrix); ``` ## XSS-safe by construction Every interpolated string runs through `escapeXmlAttribute` before landing in the SVG markup, so values like `` in `merchantName` come out as the harmless escaped form. Verified by a dedicated test fixture in the render package. ## Server response ```ts return new Response(svg, { headers: { 'content-type': 'image/svg+xml; charset=utf-8' }, }); ``` Works directly from Cloudflare Workers, Vercel Edge, Bun, Deno, Node — no runtime-specific glue needed. # Slip Verify > Build + parse the Mini-QR printed on Thai bank transfer slips. ## Why A **Slip Verify Mini-QR** is the small square QR printed on a bank transfer slip (and shown inside the PromptPay app's slip-detail view). It is **not** a payment QR — its sole purpose is to feed a bank Open API the reference it needs to look the transaction up after the slip image is OCR'd or scanned. Use it to verify that a customer who claims to have paid actually did. The envelope shares the EMVCo TLV grammar but uses its own root tags — see the [wire format table](#wire-format) below. Two variants exist: the standard one defined by the **Bank of Thailand Thai QR Payment supplement**, and a TrueMoney variant emitted by the TrueMoney Wallet app. ```ts import { buildSlipVerify, parseSlipVerify, buildTrueMoneySlipVerify, parseTrueMoneySlipVerify, } from 'thai-qr-payment'; ``` ## Standard slip-verify `buildSlipVerify({ sendingBank, transRef })` emits the wire payload; `parseSlipVerify(payload)` recovers the two fields. `sendingBank` is the 3-digit BoT bank code (`'002'` Bangkok Bank, `'014'` SCB, etc.); `transRef` is the reference printed on the slip. ```ts const wire = buildSlipVerify({ sendingBank: '002', transRef: '0002123123121200011', }); // '004000060000010103002021900021231231212000115102TH91049C30' parseSlipVerify(wire); // { sendingBank: '002', transRef: '0002123123121200011' } ``` The parser returns `null` (not an exception) on any payload that isn't a valid slip-verify envelope — wrong root tag, wrong CRC tag, wrong API marker, or unrecoverable checksum mismatch. Callers can branch on the result without `try / catch`. Truncated-CRC auto-fix is on by default: some bank apps strip leading zeros from the tag-91 hex CRC when re-encoding, so a 1–3 char tail is left-padded with `0` and re-verified before giving up. ```ts // Bank app emitted "…91049C30" with the leading '0' dropped — still parses parseSlipVerify('…91049C3'); // → { sendingBank, transRef } (auto-fixed) ``` ## TrueMoney slip-verify TrueMoney's variant uses the same envelope (root tag 00, country tag 51, CRC tag 91) with a different sub-tag layout. `date` is a **`DDMMYYYY` 8-char string** — the builder throws if the length is wrong. ```ts const wire = buildTrueMoneySlipVerify({ eventType: 'P2P', transactionId: 'TXN0001234567', date: '25012024', }); // '00480002010102010203P2P0313TXN00012345670408250120249104b425' parseTrueMoneySlipVerify(wire); // { eventType: 'P2P', transactionId: 'TXN0001234567', date: '25012024' } ``` **Lowercase-CRC quirk:** the TrueMoney variant emits the tag-91 CRC as **lowercase** hex (`9104b425`), not the uppercase form everyone else uses. The parser accepts either case so you can re-hash, normalise, or store in any form — but if you're handing the wire bytes to another tool, preserve the case TrueMoney shipped or its own scanner may refuse. The two parsers are strict about which envelope they accept: `parseSlipVerify` returns `null` on a TrueMoney payload, and `parseTrueMoneySlipVerify` returns `null` on a standard one. Try both in order if you don't know which variant your input is. ## Wire format ### Standard slip-verify Root template at tag 00; country tag 51; CRC at tag 91 (uppercase hex). Tag 00's value is itself a TLV run: | Tag | Name | Length | Example value | | --- | -------------------- | ------ | ------------------ | | 00 | Root template | var | (nested TLV below) | | 51 | Country | 2 | `TH` | | 91 | CRC-16 / CCITT-FALSE | 4 | `9C30` | Sub-tags inside tag 00: | Sub-tag | Name | Length | Example value | | ------- | --------------- | ------ | --------------------- | | 00 | API type marker | 6 | `000001` | | 01 | Sending bank | var | `002` | | 02 | Transaction ref | var | `0002123123121200011` | ### TrueMoney slip-verify Same root tag / country tag / CRC tag, different sub-tag layout (and lowercase CRC): | Tag | Name | Length | Example value | | --- | -------------------- | ------ | ------------------ | | 00 | Root template | var | (nested TLV below) | | 91 | CRC-16 / CCITT-FALSE | 4 | `b425` | Sub-tags inside tag 00: | Sub-tag | Name | Length | Example value | | ------- | ----------------- | ------ | --------------- | | 00 | Marker A (`'01'`) | 2 | `01` | | 01 | Marker B (`'01'`) | 2 | `01` | | 02 | Event type | var | `P2P` | | 03 | Transaction id | var | `TXN0001234567` | | 04 | Date (`DDMMYYYY`) | 8 | `25012024` | The marker pair (sub-tags 00 + 01 both `'01'`) is the discriminator that distinguishes a TrueMoney envelope from the standard one — without it `parseTrueMoneySlipVerify` returns `null`. # Install > Add thai-qr-payment to your project — one umbrella install or scoped sub-packages. ## One package, everything included The umbrella `thai-qr-payment` carries the **payload builder, QR encoder, SVG renderer, brand assets, and CLI** in a single dependency. ```bash pnpm add thai-qr-payment # or npm install thai-qr-payment # or bun add thai-qr-payment ``` That's it — no peer dependencies, no transitive packages, no install scripts. `npm install thai-qr-payment` literally pulls one tarball. ## Scoped sub-packages (tighter dep graph) For consumers who want only one slice (e.g. payload-only on edge runtimes): | Need | Install | | -------------------------------- | -------------------------- | | Wire payload builder + parser | `@thai-qr-payment/payload` | | QR Code encoder | `@thai-qr-payment/qr` | | SVG renderer | `@thai-qr-payment/render` | | Thai QR Payment + PromptPay SVGs | `@thai-qr-payment/assets` | | CLI only | `@thai-qr-payment/cli` | | React component (peer-dep React) | `@thai-qr-payment/react` | Or import from the umbrella sub-paths — same bytes, same tree-shake: ```ts import { ThaiQRPaymentBuilder } from 'thai-qr-payment/payload'; import { encodeQR } from 'thai-qr-payment/qr'; import { renderCard } from 'thai-qr-payment/render'; import { COLOR_LOGOS } from 'thai-qr-payment/assets'; ``` ## CDN (skip the bundler) Every published `dist/*.js` ships pre-compressed `.br` + `.gz` siblings, so CDNs serve the smallest variant via `Accept-Encoding`: ```html ``` ## Engine requirements | Runtime | Minimum | | ------------- | ----------------------------------------------------------------------------- | | Node | ≥ 18 | | pnpm | ≥ 8 (10.x recommended) | | Browser | any module-supporting browser (Chrome 80+, Safari 14+, Firefox 78+, Edge 80+) | | Edge runtimes | tested on Cloudflare Workers, Vercel Edge | ## Verify the install ```ts import { payloadFor, parsePayload } from 'thai-qr-payment'; const wire = payloadFor({ recipient: '0812345678', amount: 50 }); console.log(wire); // 00020101021229370016A00000067701011101130066812345678530376454... const parsed = parsePayload(wire); console.log(parsed.amount); // 50 console.log(parsed.merchant); // { kind: 'promptpay', recipientType: 'mobile', recipient: '0812345678' } ``` Next: [try it in the live demo](/demo/) or jump into the [payload guide](/guide/payload/). # For LLMs > Plain-text dumps of every documentation page in formats designed for LLM ingestion. `thai-qr-payment` ships three plain-text mirrors of this documentation site for use by large language models. They follow the [llms.txt](https://llmstxt.org) proposal and are emitted on every docs build by [`starlight-llms-txt`](https://delucis.github.io/starlight-llms-txt/). | Endpoint | Purpose | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | [`/llms.txt`](/llms.txt) | Short index file. Links to the two longer dumps. Drop into an LLM's context to give it an entry-point to the rest. | | [`/llms-full.txt`](/llms-full.txt) | Full plain-text dump of every doc page. ~4.6k lines. Good when the model has a large context window. | | [`/llms-small.txt`](/llms-small.txt) | Abridged variant. Notes, tips, and the live demo page are stripped so the file fits in smaller context windows. | ## How to use Paste the URL into ChatGPT, Claude, or Gemini as a source. Or fetch programmatically: ```bash curl https://thai-qr-payment.js.org/llms.txt curl https://thai-qr-payment.js.org/llms-full.txt ``` The three files regenerate on every push to `main`, so they stay in sync with the published docs site. # CDN usage > Load thai-qr-payment straight from unpkg or JSDelivr — no bundler required. Every published `dist/*.js` ships with pre-compressed `.br` + `.gz` siblings. CDNs that honour `Accept-Encoding` (unpkg, JSDelivr) serve the smaller variant automatically — no runtime compression, no extra round-trip. ## unpkg ```html ``` Pinned version: ```html ``` ## JSDelivr ```html ``` ## Sub-paths over CDN The umbrella's sub-path exports (`payload`, `qr`, `render`, `assets`) work too: ```html ``` ## Pre-compressed file paths If you self-host, serve the variants directly with the right `Content-Encoding` header: | File | Content-Encoding | | ------------------ | ---------------- | | `dist/index.js` | identity | | `dist/index.js.br` | `br` | | `dist/index.js.gz` | `gzip` | A typical nginx config: ```nginx location ~ \.js$ { gzip_static on; brotli_static on; add_header Cache-Control "public, max-age=31536000, immutable"; } ``` Cloudflare Workers / Pages handle this automatically when the file is present. ## React from CDN The React adapter relies on a peer-dep React; for CDN use, mount it through ESM: ```html ``` # Edge runtimes > thai-qr-payment runs unchanged on Cloudflare Workers, Vercel Edge, Deno, Bun. The full umbrella (and every scoped package) avoids Node-only APIs. The only exception is `@thai-qr-payment/cli`, which is the CLI binary — that one uses `node:fs/promises` for file output. ## Compatibility matrix | Runtime | Status | Notes | | -------------------------------------------------------- | ------ | ----------------------------------------------- | | Browsers (Chrome 80+, Safari 14+, Firefox 78+, Edge 80+) | ✓ | ESM via `