11 Aug 2026 · 16 min read
Set Up Invoice-Specific PayNow QR Payments for Xero
The complete Codex setup runbook and portable Aspire PayNow QR implementation guide: trusted merchant configuration, invoice inputs, TLV fields, CRC, rendering and layered verification.
Updated 15 October 2026: the complete Codex setup runbook and portable implementation guide follow. The implementation guide describes an inspected Aspire VPA profile, not a universal PayNow specification or proof of payment receipt.
Set up PayNow QR payments for Xero with Codex
Use this runbook as a prompt for a Codex agent. The agent should build and verify the integration with you; it must not assume that every PayNow merchant uses a UEN proxy.
Choose your route
- Codex-led setup: use the prompt below with the canonical repository.
- Build in your own stack: read Generate invoice-specific Aspire PayNow QR payloads for the configurable merchant profile, input contract, TLV/CRC pseudocode and layered verification checks.
Both routes require the intended merchant's current provider-issued QR. Neither confirms payment receipt or automatically reconciles Xero.
Canonical repository
This repository is designed for agent-led setup. It includes AGENTS.md, official-QR decoding, VPA-aware dynamic payload generation, tests, Docker and Netlify configuration, and public-release safety controls.
Prompt for Codex
Help me set up an invoice-specific PayNow QR payment page for Xero.
Use this repository as the canonical implementation:
- https://github.com/oruenboi/xero-paynow-vpa-qr
Read and follow AGENTS.md before changing or deploying anything.
Work with me until the result is verified from a real banking app. Follow these controls:
0. Audit prerequisites before making changes:
- activated PayNow service and official provider-issued QR
- Node.js 20.20+, npm and Git
- access to the intended Xero organisation
- intended HTTPS hostname and DNS authority when using a custom domain
- exactly one hosting route:
- Netlify: account/site access and either Git deployment or authenticated Netlify CLI
- VPS: authorised SSH, Docker/Compose, reverse proxy, DNS and TLS
Make clear that Netlify and VPS are alternatives, not cumulative requirements. Report missing access instead of assuming it.
1. Ask me for the official PayNow QR issued by my bank or payment provider. Do not infer a receiving proxy from a UEN alone.
2. Decode the official QR locally and report its EMV/PayNow fields, including:
- point-of-initiation method
- PayNow proxy type
- exact proxy value
- editable-amount indicator
- merchant category
- currency and country
- QR merchant name
- city and postal code
3. Treat those decoded merchant fields as authoritative. A common proxy mapping is UEN type 2 and VPA type 3, but verify this from the supplied QR rather than guessing.
4. Preserve the official QR byte-for-byte as a fallback asset. Never publish my live QR, payment address, logo, domain, tokens, or customer information to a public repository without my explicit approval.
5. Generate an invoice-specific dynamic QR by changing only the transaction fields that are required:
- dynamic point-of-initiation method
- fixed invoice amount
- invoice number as payment reference
- editable-amount indicator when required
- recalculated CRC-16/CCITT-FALSE checksum
Keep the provider-issued proxy type and merchant metadata unchanged.
6. Validate currency, amount and invoice reference before rendering. Do not accept a merchant proxy or recipient from public URL parameters.
7. Add a provider-approved manual-payment fallback. It must show the complete payment address and the provider's instructions exactly.
8. Build a static, responsive page. Use plain PayNow text unless I provide an authorised brand asset.
9. Add automated tests covering the decoded merchant profile, proxy type, amount, reference, checksum and preservation hash of the official QR.
10. Deploy using the smallest reversible release process. For Netlify, verify a draft deploy before production. For VPS, preserve the previous release until the new container is healthy. Verify build, tests, service health, HTTPS and the live page.
11. Give me a test URL and ask me to scan it with a Singapore banking app. Do not call the payment path usable until the app resolves the expected recipient and displays the correct amount and reference.
12. The page must not claim that payment succeeded. Bank evidence and accounting reconciliation remain the source of truth.
13. Before changing Xero, show me the proposed custom payment URL and obtain explicit approval. Use a URL shaped like:
https://pay.example.com/?invoiceNo=[INVOICENUMBER]¤cy=[CURRENCY]&amount=[AMOUNTDUE]&shortCode=[SHORTCODE]
14. Do not create Xero payments, alter invoices, or change branding-theme payment services without explicit approval for that exact action.
Start by inspecting the repository and its AGENTS.md, then ask me for the official provider-issued QR and intended hosting domain.
What this does not provide
- PayNow registration or activation
- Confirmation that a payment was received
- Automatic Xero reconciliation
- Guaranteed compatibility with every banking application
- Permission to use PayNow or provider trademarks
The merchant must activate PayNow with its bank or payment provider and complete a real low-value banking-app test before customer rollout.
Generate invoice-specific Aspire PayNow QR payloads in your own stack
An invoice-specific QR carries a payment amount and invoice reference so the payer does not have to enter both manually. This guide explains how to construct the text payload in your own language or application. A QR library renders the text; the payer's banking app resolves the recipient and asks the payer to approve the transfer.
For a Codex-led setup using the reference application, use the setup runbook and canonical repository.
This is a portable description of the Aspire VPA profile inspected in Daisy's application version 1.1.1 on 5 October 2026. It is not a complete PayNow or SGQR specification, provider certification, or a replacement for current official requirements. The configurable pseudocode below is an adaptation, not the unchanged deployed Daisy generator.
1. Separate the responsibilities
Keep these parts independently testable:
- Trusted merchant configuration.
- Invoice-input parsing and validation.
- Payload construction and checksum.
- QR rendering and download.
- Bank-app acceptance and, separately, payment-receipt reconciliation.
No Xero API or bank API call is needed merely to generate this payload. Generation does not confirm that the invoice exists, its amount is still due, the account is active, or payment has arrived.
A CRC catches corruption; it does not authenticate an invoice or its recipient.
2. Obtain the complete merchant profile
Start with the current QR issued to the intended merchant by its bank or payment provider. Decode it locally and record the source and capture date. Confirm the receiving service is active and the banking app resolves the expected recipient.
Do not infer the proxy type from a UEN-looking string. Aspire distinguishes a VPA from a plain UEN receiving address. Aspire receiving guidance
For this profile, keep the following in trusted configuration—not public URL parameters:
| Configuration | Source |
|---|---|
| Payment-system identifier | Decoded merchant account field; expected SG.PAYNOW for this profile |
| Proxy type | Decoded nested field 01; the inspected Aspire VPA uses 3 |
| Complete proxy value | Decoded nested field 02; preserve the entire provider-issued value |
| Merchant category | Decoded root field 52 |
| QR merchant name | Decoded root field 59 |
| Country and city | Decoded root fields 58 and 60 |
| Postal code, if present | Decoded root field 61 |
| Recipient display name | Merchant's receiving profile, confirmed by bank-app scan |
| Original fallback QR | Provider-issued image, preserved byte-for-byte with a hash |
These receiving fields are typically exposed in the QR, but they are not credentials. Tokens and passwords never belong in browser configuration.
The original Daisy-specific reference builder hardcodes Daisy's category, name, city and postal code. Replacing only its VPA is not a correct port for another merchant. Replace the complete trusted profile and test it.
Fail closed if required configuration is absent. Placeholder values must never produce a customer-facing QR. Do not assume optional fields can be invented. If the issued profile differs from this field map, return to the provider's requirements rather than forcing it into this template. Reject unsupported profile variants; do not silently drop additional issued fields.
3. Define the invoice input
Use a query encoder, not string concatenation. An example transaction URL is:
https://pay.example.com/?invoiceNo=INV-1234¤cy=SGD&amount=100.00
For Xero's custom payment link, the existing runbook documents:
https://pay.example.com/?invoiceNo=[INVOICENUMBER]¤cy=[CURRENCY]&amount=[AMOUNTDUE]&shortCode=[SHORTCODE]
Confirm current Xero placeholder support and actual substitution in the intended organisation before changing its configuration. Show the exact payment-service and branding-theme changes for approval.
| Full name | Compatibility alias | Rule |
|---|---|---|
invoiceNo | i | Required reference |
currency | c | Trim, uppercase, require SGD |
amount | a | Positive validated amount |
shortCode | None | Ignored by the inspected QR implementation; not an authentication credential |
In the inspected parser, a present full-name parameter wins even if empty; the alias is used only when that name is absent. Standard URLSearchParams takes the first occurrence, decodes percent escapes and interprets literal + as a space. Encode a plus in a reference as %2B.
For a new implementation, consider rejecting duplicate parameters instead of silently taking the first. Record this as a deliberate compatibility difference.
A query URL is an unauthenticated request to display supplied transaction details. It does not prove invoice identity, customer identity or current balance. If that assurance is required, add an authenticated or server-verified invoice route as a separate design. Keep invoice query data out of unnecessary analytics and access logs.
4. Validate without changing the payment meaning
Validate currency, reference and amount before rendering. On failure, show an error and render no QR; remove any stale QR left from previous inputs.
Amount: choose a documented policy
For a new parser, a simple strict policy is:
- Trim outer whitespace.
- Accept only digits with an optional decimal point followed by one or two digits.
- Reject internal whitespace, commas, signs, symbols, exponents and excess decimal places.
- Use integer cents or decimal arithmetic, not binary floating-point rounding.
- Require a positive value within your explicitly configured maximum.
- Format exactly two decimal places.
Examples under this policy:
| Input | Result |
|---|---|
" 100 " | 100.00 |
"0001.2" | 1.20 |
"0.01" | 0.01 |
"1,234.50", "1,2,3", "1 2" | Reject |
"0", "-1", "1.234", "1e2", ".50", "1." | Reject |
If grouping separators are needed, validate their exact grouping before removing them.
The legacy Daisy parser instead removes every comma and whitespace character before validation. It accepts " 1,234.5 " as 1234.50, but also "1,2,3" as 123.00 and "1 2" as 12.00. These are compatibility observations, not recommended amount interpretation.
Its application maximum is 999999999.99. That is not a bank or provider transfer limit. A port must enforce its own operational limit and current account/provider limits separately.
Invoice reference
For compatibility with the inspected profile, trim outer whitespace, require a nonempty value of at most 25 UTF-8 bytes, and allow only:
^[A-Za-z0-9 .+?/_-]+$
Preserve case and internal spaces. Reject unsupported characters and overlong references; do not silently truncate them. A download filename may be sanitized separately without changing the payment reference.
Receiving VPA
Validate the configured address against the current issued profile. The legacy builder trims and uppercases it, then applies:
^UEN[A-Z0-9]{9,13}#[A-Z]{4}$
with a 25-byte maximum. This is an Aspire-style compatibility check, not a universal PayNow validator. Passing it proves neither registration nor activation.
5. Construct the TLV payload
Encode each field as a two-digit tag, a two-digit decimal UTF-8 byte length, and its value. No separators are inserted.
TLV(tag, value) =
tag + twoDigitDecimal(length(UTF8(value))) + value
TLV("53", "702") = "5303702"
TLV("54", "100.00") = "5406100.00"
TLV("62", TLV("01", "INV-1234")) = "62120108INV-1234"
Reject invalid tags and values whose encoded length exceeds 99 bytes. Encode nested fields first, then count the full nested string as the outer field's value. Never substitute Unicode character counts for byte counts.
The inspected profile uses this root order:
| Tag | Value |
|---|---|
00 | 01, payload format |
01 | 12, dynamic initiation |
26 | Nested PayNow account template below |
52 | Configured merchant category |
53 | 702, SGD |
54 | Validated amount with two decimal places |
58 | Configured country; this guide requires SG |
59 | Configured QR merchant name |
60 | Configured merchant city |
61 | Configured postal code when present in the supported profile |
62 | Nested tag 01 with the invoice reference |
63 | Four uppercase hexadecimal CRC digits |
Inside 26:
| Tag | Value |
|---|---|
00 | SG.PAYNOW |
01 | Configured proxy type, verified as 3 for this Aspire VPA profile |
02 | Complete trusted VPA |
03 | 0, fixed-amount profile |
The amount-editing flag is a payload value, not proof that every banking app prevents editing. Inspect the actual supported app behaviour.
6. Calculate CRC-16/CCITT-FALSE
Parameters: polynomial 0x1021, initial value 0xFFFF, width 16 bits, no reflection and no final XOR. The standard check input 123456789 produces 29B1.
Construct the body without tag 63, append literal 6304, calculate the CRC over those UTF-8 bytes, then append four uppercase hex digits. Include 6304 in the calculation; exclude the checksum digits themselves.
crc = 0xFFFF
for byte in UTF8(body + "6304"):
crc = crc XOR (byte << 8)
repeat 8 times:
if (crc AND 0x8000) != 0:
crc = ((crc << 1) XOR 0x1021) AND 0xFFFF
else:
crc = (crc << 1) AND 0xFFFF
payload = body + "6304" + uppercaseHex(crc).padLeft(4, "0")
Recompute after every field change.
7. Language-independent construction
profile = loadTrustedMerchantProfile()
requireSupportedAspireVpaProfile(profile)
transaction = parseAndValidateInvoiceInputs(query, chosenAmountPolicy)
account = TLV("00", "SG.PAYNOW")
+ TLV("01", profile.proxyType)
+ TLV("02", profile.completeVpa)
+ TLV("03", "0")
body = TLV("00", "01") + TLV("01", "12")
+ TLV("26", account)
+ TLV("52", profile.merchantCategory)
+ TLV("53", "702")
+ TLV("54", transaction.amount)
+ TLV("58", profile.country)
+ TLV("59", profile.qrMerchantName)
+ TLV("60", profile.city)
if profile.postalCode is present:
body = body + TLV("61", profile.postalCode)
body = body + TLV("62", TLV("01", transaction.reference))
input = body + "6304"
payload = input + CRC16_CCITT_FALSE(input)
image = renderQr(payload)
Do not render the payment-page URL as the payment QR. Render the constructed payload. Do not derive merchant identity from invoice parameters.
8. Render, display and download
Use a maintained QR encoder. The inspected application used error correction M, 320-pixel output and a three-module margin; these are historical rendering choices, not a requirement for a port. Use an appropriate unobstructed quiet zone—normally at least four modules for a standard QR—and no logo over data modules.
Different encoders can choose different masks, versions and segmentation. Compare decoded text, not image hashes or QR matrices. Decode both the displayed image and the actual downloaded file and require exact payload equality.
Display recipient name, complete VPA, amount and reference beside the QR using safe text rendering. Do not label a download, scan or page visit as a completed payment.
Export the same rendered image as a nonempty PNG or another explicitly supported format. A browser implementation can use a temporary object URL and revoke it after the download has been initiated. Sanitize the filename independently; never rewrite the embedded invoice reference to make a filename.
Preserve the merchant's original provider QR as a fallback. If it has no amount/reference, explain what the payer must enter manually. Use current provider/bank instructions for manual VPA entry; banking apps may present their fields differently.
9. Test in layers
| Layer | Required evidence |
|---|---|
| Input validation | Positive cases plus missing/invalid currency, amount, reference and configuration; no QR on rejection |
| Structure | Root/nested TLV parsing, exact trusted merchant values, amount/reference and CRC; include 123456789 -> 29B1 |
| Rendering | Displayed and downloaded images decode to exactly the intended payload |
| Banking app | Expected resolved recipient, amount and reference in each supported app |
| Payment receipt | Separately authorised test transfer, receiving-account evidence and accounting reconciliation |
Add tests for empty full-name parameters versus aliases, duplicates under your chosen policy, %2B handling, UTF-8 byte lengths, maximum bounds, stale-QR removal, and attempted recipient overrides. Alter a field without recomputing CRC and require the validator to reject it.
Build complete synthetic merchant fixtures for offline tests. Do not scan or pay to an invented VPA. Keep any real-recipient acceptance test separate and explicitly authorised.
Daisy's private export contains 58 compatibility vectors and seven complete real-recipient payloads. On 14 October 2026, the supplied offline verifier passed those vectors and all 15 listed file hashes matched. The export separately records source/compiled-code comparisons and an independent Python check from 5 October. Those historical checks were not repeated here.
This public guide does not bundle that real-recipient pack or claim its fixtures are in the public repository. Its configurable pseudocode and stricter amount policy are not newly executed production code. No fresh image decode, bank scan, recipient activation check, payment, or Xero configuration inspection was performed for this publication.
10. Release without confusing generation with collection
Choose a reversible hosting release and inspect its HTTPS page. Do not change Xero payment services, branding themes, invoices or accounting records without approval for the exact action. Test invoice-level and repeating-template selections as well as defaults; do not assume a default setting overrides saved choices.
Approve bank tests separately from code tests. A recipient can become inactive or receive replacement details; refresh the official profile when required. Verify receipt in the receiving account, not from the payer's screenshot. Aspire receiving guidance
If the application needs current invoice balances, payment status or automatic reconciliation, build and review those integrations separately. They are not provided by this QR-generation contract.
Primary references
- Reference application and Codex setup.
- Aspire PayNow receiving guidance.
- Aspire incoming-transfer troubleshooting.
- EMVCo QR code specifications.
- Association of Banks in Singapore: PayNow.
Prepared 14 October 2026 from the inspected implementation pack. Verify current provider, bank and Xero requirements before customer use.
Share and save
Living source
This post is the stable site version. The source gist may be updated as the working pattern develops.
Read both guides on GitHub GistOpen the canonical implementation repositoryRead the portable implementation source