All entries
Chapter VIII
Journal · 15 Nov 2026 · 14 min read

EMV QR Code Format: Pix vs PromptPay vs UPI

EMV QR code format for developers: TLV tags, the CRC-16 rule most guides skip, and how Pix, PromptPay, DuitNow, PayNow and UPI payloads differ.

The sample payload in EMVCo's own QR specification is 248 characters long and 260 bytes, and its length fields only add up if you count characters. Go's len() counts bytes, so the obvious Go implementation breaks the moment a merchant name leaves ASCII. JavaScript's .length counts UTF-16 code units, which holds up until an emoji or a decomposed accent arrives.

The pages ranking for "EMV QR code format" skip that, along with a CRC check value, the ways Pix, PromptPay and DuitNow bend the spec, and the fact that India's UPI QR is not an EMV payload at all. This guide covers each of those, plus what Stripe, Adyen and Mercado Pago actually hand back.

What Is an EMV QR Code?

An EMV QR code, in the sense payment engineers mean, follows EMVCo's QR Code Specification for Payment Systems: Merchant-Presented Mode (MPM), currently version 1.1 from November 2020. The merchant displays the code and the customer's banking or wallet app scans it.

MPM is an envelope, not a payment scheme. It defines a flat string of tag-length-value objects, a checksum and some merchant metadata. It does not say how money moves. That is decided by whichever network's template sits inside the envelope, which is why two codes that both pass the CRC can route to completely different rails. Brazil's Pix, Thailand's PromptPay, Malaysia's DuitNow, Singapore's SGQR and Indonesia's QRIS all use the envelope. India's UPI does not.

EMV QR Code Format: Tag-by-Tag Reference

Every data object is a two-digit ID, a two-digit length and a value. 5303986 reads as ID 53, length 03, value 986 (Brazilian real). Lengths run from 01 to 99, which means no single object and no template can exceed 99 characters. Each ID may appear only once at the root and once within any template. Only two positions are fixed: 00 must come first and 63 must come last (§4.6.1). Everything else can appear in any order, so a parser that assumes the order of a sample payload will break on real ones.

IDFieldFormat and max lengthNotes
00Payload Format IndicatorN, 2Always 01
01Point of Initiation MethodN, 2, optional11 static, 12 dynamic
02–25Card network accountsvariesVisa 02–03, Mastercard 04–05, Discover 09–10, Amex 11–12, JCB 13–14, UnionPay 15–16, rest EMVCo
26–51Other payment networkstemplate, ≤99Sub-ID 00 is the network identifier: an AID, a UUID or a reverse domain, ≤32 chars
52Merchant Category CodeN, 4ISO 18245
53Transaction currencyN, 3ISO 4217 numeric, so 986, not BRL
54Transaction amountans, ≤13Digits and one .; omit to make the app ask
55–57Tip or convenience fee01 prompt, 02 fixed fee in 56, 03 percentage in 57
58Country codeans, 2ISO 3166-1 alpha-2
59Merchant nameans, ≤25Mandatory
60Merchant cityans, ≤15Mandatory
61Postal codeans, ≤10Optional
62Additional data templateS, ≤9901 bill number, 05 reference label, 07 terminal label, 08 purpose, among others
63CRCans, 4Mandatory, last
64Merchant info, alternate languageS, ≤99Name and city in another script
65–79Reserved for EMVCo
80–99Unreserved templatesSub-ID 00 identifier mandatory

Three rows in that table cause most of the bugs I've seen.

Tag 54 is a decimal string in major units. The spec lists 98.73, 98 and 98. as valid amounts and 98,73 as invalid, and the amount must not be zero. Most PSP APIs use integer minor units (Stripe's amount: 1000 is R$10.00), so you convert at the QR boundary; the ISO 4217 minor units guide covers that side. The Pix API behind the QR is stricter than the QR itself: its valor.original must match \d{1,10}\.\d{2}, so "98." is valid in tag 54 and rejected by the API. Tag 52 is often a placeholder. BCB's own Pix examples use 0000, because Pix routing does not depend on it. If your analytics read MCCs from QR payloads, expect junk. The MCC guide explains who actually assigns the code. Tag 62 sub-fields accept . A value of with length 03 in sub-fields 01 to 08 tells the payer's app to prompt the customer for that value (§4.8.1.2).

There is also a parser rule worth coding for on day one: a generator must not include reserved IDs, but the scanning app "must ignore" them if present (§1.4.4). Skip unknown tags; do not throw.

How to Calculate the EMV QR CRC

Tag 63 is a CRC-16 per ISO/IEC 13239 with polynomial 0x1021 and initial value 0xFFFF, no input or output reflection and no final XOR. In the CRC catalogue that is CRC-16/CCITT-FALSE, and its check value for the ASCII string 123456789 is 29B1. The common mistake is CRC-16/XMODEM, which uses the same polynomial with an initial value of 0x0000 and returns 31C3 for the same input.

Two details trip people up. First, the checksum covers every object in order including the ID and length of the CRC itself, so you append 6304 before hashing and the CRC value after. Second, the output is four uppercase hex characters, zero-padded: a result of 0x7B is written 007B.

function emvCrc(payloadEndingIn6304: string): string {
  let crc = 0xffff;
  for (const byte of new TextEncoder().encode(payloadEndingIn6304)) {
    crc ^= byte << 8;
    for (let i = 0; i < 8; i++) {
      crc = crc & 0x8000 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
    }
  }
  return crc.toString(16).toUpperCase().padStart(4, "0");
}

Banco Central do Brasil's static Pix example makes a good test vector, because the manual states the expected result. Split into objects:

00 02 01
26 58 0014br.gov.bcb.pix 0136123e4567-e12b-12d1-a456-426655440000
52 04 0000
53 03 986
58 02 BR
59 13 Fulano de Tal
60 08 BRASILIA
62 07 0503*
63 04 1D3D

Hashing the string up to and including 6304 gives 1D3D, which matches BCB. Leave 6304 off and you get 4AAD. Use the XMODEM initial value and you get 4AC0. If your implementation returns either of those, you have found your bug.

EMV QR Length: Characters or Bytes?

Characters. Section 4.4.1.1 says the length "shall be equal to the number of characters in the value field", while the payload itself is UTF-8 and the CRC runs over the UTF-8 bytes. So lengths count characters and the checksum hashes bytes. The spec's Annex B.7 example proves the point: its alternate-language merchant name 最佳运输 carries length 04 while occupying 12 bytes.

The root merchant name and city (tags 59 and 60) are format ans, the EMV Common Character Set, so strictly a São Paulo merchant should appear as SAO PAULO there, with the accented or non-Latin form in template 64. Format S, used by tags 62 and 64, allows any precomposed Unicode character. That word "precomposed" matters: São from some systems arrives with the ã split into a plus a combining tilde, four code points instead of three. Normalise to NFC, then count code points ([...s].length in JavaScript, utf8.RuneCountInString in Go).

Two more limits sit around the edges. The 512-character payload cap in §4.1 is a "should", reduced proportionally when multi-byte characters appear. And §4.12 requires the QR symbol itself to be encoded in byte mode, with Alphanumeric mode explicitly forbidden, plus an ECI designator of 000026 when anything outside the Common Character Set is present. Most general-purpose QR libraries pick the most compact mode automatically. A payload made only of digits, capitals and spaces qualifies for Alphanumeric mode, so unless you force byte mode your library may produce a symbol the spec does not allow. Most scanners read it anyway, but it is not conformant.

Static vs Dynamic QR Codes: What Tag 01 Means

EMVCo makes tag 01 optional. 11 means the same code is shown for more than one transaction and 12 means a new code is generated for each one. That is all it says. The common library behaviour of treating 12 as "an amount is present" comes from PromptPay and QRIS implementations, not from EMVCo.

Pix gives 12 real teeth. The BR Code manual says a code marked 12 can only be used once, and a dynamic Pix code changes the structure of the template entirely, which brings us to Brazil.

Pix QR Code Payload in Brazil: Static Key vs Dynamic URL

BCB's Manual de Padrões para Iniciação do Pix (version 2.10.0, with a 2.11.0 release candidate already linked) defines two layouts for the merchant account template. The GUI br.gov.bcb.pix can legally sit anywhere in 26 to 51, though in practice everyone uses 26.

Static Pix QRDynamic Pix QR
Template 26 contents00 GUI, 01 key, 02 free text, 03 Pix Saque ISPB00 GUI, 25 URL
Pix key in the QRYes, 1–77 charsNo
Amount (tag 54)OptionalMust not be filled; payer ignores it
txid (tag 62-05)≤25 alphanumeric, or * for noneIgnored; txid is 26–35 alphanumeric, in the signed payload
Where the amount comes fromTag 54valor.original in a JWS-signed JSON payload

The 77-character key limit is just arithmetic on the 99-character template cap: the GUI object takes 18 characters and the key's own ID and length take 4, leaving 77. Keys come in five shapes: CPF (11 digits), CNPJ (14, and the manual now includes the alphanumeric CNPJ format), phone in +55 form, email, or an EVP random key, which is a UUID with hyphens.

A dynamic code's sub-tag 25 holds a URL with no protocol prefix, HTTPS implied, capped at 77 characters, laid out as {psp-host}/{endpoint}/{token}. The payer's app fetches it, receives an application/jose JWS, and only proceeds if the signature verifies against the receiving PSP's key. On the PSP side, the open API Pix specification creates the charge:

PUT /cob/{txid}
{
  "calendario": { "expiracao": 3600 },
  "valor": { "original": "10.00" },
  "chave": "123e4567-e12b-12d1-a456-426655440000",
  "solicitacaoPagador": "Pedido 1234"
}
expiracao is an integer number of seconds and defaults to 86,400. The response carries location and pixCopiaECola, the full EMV string you render as a QR or show as copy-and-paste text. The txid validator differs by layout: [a-zA-Z0-9]{26,35} for dynamic charges, up to 25 characters for static. One validator for both will reject valid codes in one direction or the other.

The most useful line in the whole manual, from a security point of view, is a footnote: the payer ignores tag 59. The app shows the account holder's name from the DICT directory instead.

Pix vs PromptPay vs DuitNow vs PayNow: National EMV QR Templates

SchemeTagIdentifierDeviation worth coding forSpec
Pix (Brazil)26 (any 26–51)br.gov.bcb.pixDynamic code holds a URL, not a key; tag 59 ignoredPublic, BCB
PromptPay transfer (Thailand)29A000000677010111Mobile as 13 digits, 0066 + number without leading 0; tags 52 and 60 optional; 55–57 not allowed; tag 59 must not be displayedPublic, Bank of Thailand, 2019
PromptPay bill payment30A00000067701011215-digit biller ID; Ref 1 (≤20) mandatorySame
DuitNow (Malaysia)26A0000006150001Acquirer ID sub-tag mandatory; postal code exactly 5 digits; tax ID ≤15 (EMVCo: 20); tag 82 hashPayNet developer docs
PayNow (Singapore)usually 26SG.PAYNOWProxy type 0 mobile or 2 UEN; editable-amount flag; expiry date sub-tagNot published; known from open-source implementations
QRIS (Indonesia)PSPs in 26–45, national in 51ID.CO.QRIS.WWWNational merchant ID in the 51 templateIssued only to licensed applicants

A static PromptPay code to the mobile number 081-234-5678 comes out as:

00020101021129370016A0000006770101110113006681234567853037645802TH5912EXAMPLE SHOP6304658F

Put that next to the Pix example and the scheme differences jump out. A different template tag, an AID instead of a reverse domain, a phone number in a scheme-specific format, and no MCC or city, both of which Bank of Thailand makes optional for PromptPay. Tag 59 is still there because EMVCo requires it, but the guideline forbids the payer's app from showing it: the name displayed must be looked up from PromptPay. That string also happens to contain only digits, capitals and spaces, which is exactly the case where an auto-detecting QR library slips into the forbidden Alphanumeric mode.

India's Bharat QR, the interoperable code launched on 20 February 2017 by NPCI, Mastercard and Visa on the EMV tag layout, has its own quirk. Mastercard's developer documentation says Bharat QR may carry the Mastercard merchant ID in tag 62 sub-field 11, which EMVCo v1.1 assigns to Merchant Channel. A strict v1.1 validator will misread it.

Is a UPI QR Code an EMV QR Code?

No. A UPI QR is a URL encoded as a QR symbol. NPCI's linking specification tells implementers to build the URL and then QR-encode it:

upi://pay?pa=shop@examplebank&pn=Example%20Shop&mc=5411&tr=ORD1234&am=250.00&cu=INR&mode=01
ParameterMeaningRule
paPayee VPAMandatory
pnPayee nameMandatory
trTransaction referenceMandatory for merchant and dynamic codes
amAmountMandatory on dynamic codes; editable if absent
mamMinimum amountIf absent, a supplied am is not editable
cuCurrencyOnly INR
modeInitiation mode01 QR, 02 secure QR, 04 intent
signSignatureBase64, computed over everything before &sign=, must be last

The publicly mirrored text is a November 2017 draft (v1.6), so check your acquirer's spec before relying on optional fields. The trade-off against EMV is still clear. UPI's URI is readable and easy to debug, and it has no checksum of its own, relying on the QR symbol's built-in error correction. EMV's TLV has a CRC, but a CRC is not a signature: anyone who swaps the payee can recompute it in a microsecond. In both formats a static code authenticates nothing. The only places these schemes put a real signature are UPI's signed QR and Pix's JWS payload behind a dynamic code.

Stripe vs Adyen vs Mercado Pago: QR Payment API Fields

StripeAdyenMercado Pago
Pix actionnext_action.pix_display_qr_codeaction with type: "qrCode"point_of_interaction.transaction_data
EMV stringdataqrCodeDataqr_code
Rendered imageimage_url_png, image_url_svgNone, render it yourselfqr_code_base64
Expiry in responseexpires_at (Unix seconds)additionalData["pix.expirationDate"]date_of_expiration
Default Pix expiry4 hours1 hour (API v71 and earlier), 24 hours (v72+)24 hours
Pix expiry range60 seconds to 14 daysup to 1 year30 minutes to 30 days
PromptPay refundsYesNon/a

Stripe's PayNow and PromptPay actions (paynow_display_qr_code, promptpay_display_qr_code) return data and image URLs with no expires_at, and Stripe documents PayNow codes as valid for one hour. Stripe's UPI action documents only image URLs and an expiry inside qr_code, with no raw string field, so plan on displaying Stripe's image rather than rendering your own UPI QR.

Two traps sit in that table. Stripe warns that the expires_at returned for Pix echoes your input and the real expiry may differ, and it tells you to rely on the payment_intent.payment_failed event instead. And moving Adyen's Checkout API from v71 to v72 changes the default Pix expiry from one hour to 24 without any change to your code. If your order-hold logic assumes an hour, a version bump quietly breaks it.

Should You Generate EMV QR Payloads Yourself?

My view: write the TLV codec yourself, because it is 40 lines and you need it for tests, but only generate static codes for accounts you hold. For anything carrying an amount, take the PSP's string and render it byte for byte. Never parse and rebuild it. BCB requires Copia e Cola text to be copied as exactly the same character sequence, and the dynamic-Pix layout shows why: the amount you would extract from tag 54 is not the amount the payer sees.

I'd also avoid any library that claims to handle "EMV QR" generically across countries. The envelope is common; the validation is not. One codec plus a small validator per scheme (Pix key formats, PromptPay's 0066 rule, DuitNow's five-digit postcode) is easier to keep correct than a single configurable generator.

A prediction, and it is opinion: schemes that still let payer apps show tag 59 will move to directory-resolved names. Pix and PromptPay already have, because a sticker pasted over the real QR at a till is about the cheapest fraud going and a CRC does nothing to stop it. Showing the name the scheme has verified is the only defence that does not need a signature on every static code.

What This Means for Developers Building QR Payments in 2026

1. Test your CRC with two vectors. 123456789 must give 29B1, and BCB's static example must give 1D3D. If you get 31C3, you are running XMODEM. 2. Count lengths in code points after NFC normalisation, and hash UTF-8 bytes. Add a test with a non-ASCII value in tag 62 or 64. 3. Force byte mode in your QR renderer and add ECI 26 when the payload leaves the Common Character Set. 4. Validate amounts twice. EMV's loose decimal string in tag 54, and the PSP's own format (Pix wants exactly two decimals) in the API call. 5. Keep separate txid validators for static Pix (≤25) and dynamic Pix (26–35). 6. Drive order state from webhooks, not from expires_at. Verify those webhooks properly too; the webhook signature guide covers each PSP's scheme. 7. Pin your Adyen Checkout API version and read the Pix expiry change before moving to v72. 8. Do not route UPI through an EMV parser. It is a URI with its own signature rules.

I'm Tom Wang, and I write about the engineering underneath payment rails. National QR specs get revised more often than EMVCo's, so check the scheme operator's current version before you hard-code any rule from this page.