Accepting QR code payments. 7 chapters and a final quiz.

Chapter 1. Identifying the rail before you sign.

A merchant never signs with a QR standard. It signs with a licensed participant (a bank, a payment institution or an e-money issuer) that enrolls it on that standard. So the first step of the project is to pin down what the participant is really selling you: not the code, but the rail that settles. That rail determines irrevocability, your customer's recourse, when funds are credited, and your largest cost item.

Eight questions to ask the participant, in this order

• Which rail settles this QR code? Instant credit transfer, card, e-money or mobile money. Everything else follows from the answer.
• Is the payment revocable? On an A2A rail, no. Your customer service team will have to live with that answer.
• When are the funds available? With some participants, an instant credit and availability are two different things.
• Which fee schedule applies, and who sets it? Regulated, banned, capped or free? The answer changes the whole negotiation.
• Is the reconciliation reference carried end to end? From the QR generator to the settlement file and the bank statement.
• How are refunds executed? From the original transaction, or by keying in the recipient's alias by hand?
• Which limits apply? The regulatory per-transaction limit, the participant's own limits, and the limits set by the payer's app.
• Are inbound foreign QR payments accepted? From which markets, through which corridor, and who sets the exchange rate?

Chapter 2. Testing an EMV QRCPS payload.

The code in your window is a human-readable character string that you must be able to decode, check and archive. The reference is the EMV® QR Code Specification for Payment Systems, published by EMVCo in two volumes, both version 1.1, dated November 27, 2020. Merchant-presented mode encodes a positional TLV: a two-digit ID, a two-digit length, then the value. There is no secret and no signature, so all the checking falls to you.

def tlv(payload: str):
    """Split positional TLV: 2-digit ID, 2-digit length, then the value."""
    i, fields = 0, []
    while i < len(payload):
        tag = payload[i:i + 2]
        length = int(payload[i + 2:i + 4])
        fields.append((tag, payload[i + 4:i + 4 + length]))
        i += 4 + length
    return fields


def crc16(data: str) -> str:
    """CRC-16/CCITT-FALSE: init 0xFFFF, polynomial 0x1021, no reflection."""
    crc = 0xFFFF
    for byte in data.encode("ascii"):
        crc ^= byte << 8
        for _ in range(8):
            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
    return format(crc, "04X")


# The CRC covers the WHOLE payload, "6304" included, the 4 value characters excluded.
assert crc16(payload[:-4]) == payload[-4:].upper(), "Invalid CRC: no app will read this code"

fields = dict(tlv(payload))
assert fields["01"] in ("11", "12")        # 11 = static, 12 = dynamic
assert len(fields["59"]) <= 25             # merchant name
assert len(fields["60"]) <= 15             # merchant city

Checks to run before printing

One last habit is often missing from projects: version the code generator and, for every display issued, keep the exact string and its hash. That string is how you prove a disputed display. Without it, you cannot show that the code in your window was actually yours.

Chapter 3. Choosing static or dynamic, by the numbers.

The choice isn't made company-wide but store by store, and it is recalculated when the sales profile changes. The same chain can run printed counter stands in its kiosks and register-generated codes in its stores perfectly well. The useful comparison is the volume above which manual reconciliation costs more than integration.

The deciding calculation

Monthly cost of manual reconciliation
  = QR payments per day
  x share not matched automatically
  x minutes of handling per discrepancy
  x loaded hourly cost / 60
  x business days per month

Workshop — assumptions to REPLACE with your own measurements:
  420 payments/day x 22% unmatched      = 92 discrepancies/day
  92 discrepancies x 3 min              = 276 min/day, i.e., 4 h 36 min
  4.6 h x 26 business days              = 120 h/month, for ONE store

Compare with:
  register integration cost (one-time, amortized over the contract term)
  + any per-transaction fee for dynamic QR
  - discrepancies avoided (one-to-one matching from day one)
  - losses avoided on underpayments and swapped displays

• A sealed backup counter stand for each store, numbered, kept out of sight and brought out only on the manager's call
• An amount limit in fallback mode, above which the sale waits or moves to another payment method
• A time-stamped paper log: time, amount, name shown in the customer's app, employee's initials
• A cross-check at the end of the shift between the log and the notifications received
• A formal return to service: stand put away, seal recorded, normal mode resumed

Roll out the switch gradually, starting with high-ticket stores, where an underpayment costs the most. Keep static where it genuinely wins: low volume, uniform ticket size, owner on site. Doing it the other way around wears teams out without improving reconciliation at all.

Chapter 4. Displaying the code in store.

The physical display, which exposes your payee address openly and within reach, is part of the payment system. Two properties are at stake at once: legibility, which drives conversion, and integrity, which decides who gets paid. A poorly designed display fails on both.

The display itself

• A quiet zone of four modules around the symbol, required by ISO/IEC 18004. A decorative frame that eats into it makes the code unreadable
• Error correction level: the same standard defines L, M, Q and H, which recover roughly 7%, 15%, 25% and 30% of damaged data
• Center logo: it uses up the error correction budget; if marketing insists on one, go up one level and retest
• Dark on light, with no inversion and no glossy laminate. A reflection off the window defeats a perfectly printed code
• Sealed or behind glass, with a numbered seal that both customers and staff can see
• Inventory number printed outside the symbol, to link this specific display to your store registry

Check usability from where the customer stands, never from behind the register. Height, angle, lighting and scanning distance can all be checked with an ordinary phone in 30 seconds. A perfectly printed symbol becomes unreadable as soon as a window reflects the late-afternoon sun onto it. Repeat this check every day at opening, on every display.

• Scan your own code from the customer's position, with a company phone
• Compare the payee name and ID shown with the store record
• Check the seal and its number, then the display's physical condition
• Log the time, the display number and the employee's initials. That record is what will date an incident

Chapter 5. Reconciling QR payments.

On a free or near-free A2A rail, the cost of QR acceptance lies not in the fee but in reconciliation. A credit received carries the payer's name, an amount and a time stamp, but rarely your order number. The whole job is to keep a matching key intact across four hops: the displayed code, the notification, the settlement file and the account statement.

When the reference is not carried through

Some national implementations make the field optional and some aggregators don't pass it on, so matching falls back on a triplet: amount, minute, and the tail of the payer's alias. That fallback fails exactly where volume is high, since two identical sales paid in the same minute can't be told apart. So measure your automatic match rate before you roll out widely, over a full week that includes a peak day.

CREATE TABLE qr_payment (
  reference        TEXT PRIMARY KEY,     -- tag 62-05, issued by the register
  store            TEXT        NOT NULL,
  display          TEXT,                 -- seal number of the counter stand; NULL if dynamic
  payload_sha256   TEXT        NOT NULL, -- hash of the code actually displayed
  expected_amount  BIGINT,               -- minor units; NULL if static QR
  currency         CHAR(3)     NOT NULL, -- ISO 4217 alphabetic
  issued_at        TIMESTAMPTZ NOT NULL,
  credit_id        TEXT,                 -- credit ID at the participant
  credited_amount  BIGINT,
  credited_at      TIMESTAMPTZ,
  accounting_day   DATE,                 -- derived from credited_at and the declared cutoff
  applied_rate     NUMERIC(18, 8),       -- filled in only for cross-border payments
  status           TEXT        NOT NULL DEFAULT 'expected'
);

CREATE INDEX ON qr_payment (status, issued_at);
CREATE INDEX ON qr_payment (store, accounting_day);

Chapter 6. Accepting foreign QR codes.

Cross-border acceptance changes neither your code, nor your contract, nor your equipment. A traveler scans it with their home-country app. Their country's switch recognizes a foreign payee and routes the transaction to the corridor. You receive a domestic credit in your own currency, so everything comes down to one item at your participant: FX.

• From which markets are inbound QR payments accepted today, and since when for each one?
• Through which corridor does the transaction run, and which switch acts as the gateway?
• Who sets the exchange rate, and is that rate shown to the payer before approval?
• What margin is taken, and how does it appear in the settlement file?
• Is the credit domestic, in the same currency and on the same timeline as a local sale?
• How do you refund a sale paid through a corridor, and how long does it take?

Chapter 7. Stopping QR code swap fraud.

When a third party sticks its own code over yours, your customers pay as usual, their apps confirm the payment and your staff see nothing wrong. The money goes elsewhere. What sets this fraud apart is its signature. It produces no error at all, only missing credits, so an alerting system built on failures will never catch it.

The response, step by step

• A numbered seal on every display, recorded in the store registry
• A reference photo of the display in place, dated and kept with the payload hash
• A daily check scan at opening, comparing the payee name and ID
• An inventory of issued codes: store, date, distribution channel, planned validity period
• A revocation procedure for when a store closes or you change participants
• Codes printed on documents treated as displays in their own right: they last for years