This is reconciliation, and it's widely misunderstood as a boring back-office matching task — tick off the rows, flag the mismatches, done. That framing misses what's actually going on. Reconciliation is a distributed-systems problem: you and the bank are two independent replicas of the same financial reality, communicating over lossy channels (webhooks, batch files, APIs), and the question "do our records agree?" is the question "have my replica and the source-of-truth replica converged?" Seen that way, reconciliation isn't matching — it's eventual consistency with money on the line.

Having built reconciliation for a payments system, I want to reframe it properly: why your ledger and the bank inevitably diverge, why that's expected rather than a bug, how to build an engine that detects and classifies the drift, and how to converge — automatically where safe, with a human where not.

Reconciliation Is Not Matching — It's Convergence

The matching framing assumes the two systems should always agree and a mismatch is an error. But in a distributed system, temporary divergence is the normal, healthy state. A transfer happens at the bank at 14:00:00. The webhook telling you about it arrives at 14:00:03 — or 14:05, or after a retry at 14:30, or, if the webhook was dropped, never (until reconciliation finds it). Between the event and your learning of it, your replica is correctly behind. You are not wrong; you are eventually consistent.

So the goal isn't "always match." It's:

Given two replicas that drift, detect the divergence, classify why, and converge — bringing your ledger into agreement with the source of truth.

This is the same shape as any eventual-consistency system (DNS, replicated databases, CRDTs): independent copies, asynchronous propagation, a convergence process that reconciles them. Reconciliation is that convergence process, and money is just the payload.

The Sources of Drift

Before building the engine, name why the replicas diverge. Each cause needs different handling:

• Timing (benign). The bank has an event you haven't received yet. Given more time, it arrives and you converge on your own. Reconciliation should not panic over these — only over divergence that persists.

• Lost events. A webhook was dropped and never retried successfully. The bank has it; you never will, unless reconciliation surfaces it. This is the main thing recon recovers.

• Your bugs. You recorded a credit that never happened, or recorded the wrong amount (a currency-unit error, a parsing slip). Your replica is genuinely wrong.

• Their corrections. Banks reverse, adjust, and post fees you didn't initiate. Real changes on their side you must absorb.

• Fraud / unexpected events. Money moved that no part of your system initiated. The scariest class — recon is often how you first learn of it.

A mature reconciliation engine doesn't just find discrepancies; it tells you which kind each one is, because the response to "timing" (wait) is the opposite of the response to "fraud" (alarm).

Building a Reconciliation Engine

The core loop: pull the source of truth (the bank statement for a period), pull your ledger for the same period, and compare them by a shared key — the bank's transaction ID, which you stored when you ingested each event.

async function reconcile(period: DateRange) {
  const statement = await bankApi.getStatement(period) // source of truth
  const ledger = await db.ledgerEntry.findMany({ where: { period } })

  const byBankId = new Map(ledger.map(e => [e.bankTransactionId, e]))
  const discrepancies: Discrepancy[] = []

  // 1. Every bank line should have a matching ledger entry
  for (const line of statement.lines) {
    const entry = byBankId.get(line.transactionId)
    if (!entry) {
      discrepancies.push({ type: 'MISSING_IN_LEDGER', line }) // we never recorded it
    } else if (entry.amount !== line.amount) {
      discrepancies.push({ type: 'AMOUNT_MISMATCH', line, entry })
    }
    byBankId.delete(line.transactionId)
  }

  // 2. Anything left in our ledger has no bank counterpart
  for (const orphan of byBankId.values()) {
    discrepancies.push({ type: 'MISSING_AT_BANK', entry: orphan })
  }

  return discrepancies
}

Two design properties matter as much as the comparison itself:

• Idempotent and resumable. A reconciliation run over a busy day processes a lot; it must be safe to re-run (it computes the same discrepancies) and able to resume if interrupted — the same idempotency discipline the rest of the money pipeline relies on.

• Run continuously, not once. Because timing divergence resolves itself, a discrepancy that's 30 seconds old is probably benign; one that's 24 hours old is real. Re-running reconciliation lets benign drift age out and surfaces only what persists.

Classifying Discrepancies

The three structural outcomes map directly to the drift causes, and each implies an action:

• Missing in ledger (bank has it, you don't) — typical cause: lost or late webhook. Action: ingest it to recover; if it persists past your redelivery window, it's a genuine lost event.

• Missing at bank (you have it, bank doesn't) — typical cause: your bug, or a not-yet-settled entry. Action: investigate hard — you may have invented money.

• Amount mismatch (same transaction, different number) — typical cause: currency-unit or parsing bug. Action: almost always your side; fix and correct.

The art is layering time on top of structure. A "missing in ledger" that's seconds old is the benign timing case — wait. The same discrepancy still present after your retry/redelivery window has elapsed is a genuine lost event — recover it. Encoding that age threshold is what separates a noisy reconciliation system (screaming about every in-flight transfer) from a useful one (alerting only on true, settled divergence).

Converging: Auto-Heal vs Escalate

Detection is half the job; convergence is the other half. Split discrepancies by how safe automatic resolution is:

• Auto-heal the safe, well-understood cases. A "missing in ledger" that exactly matches a known bank transaction format can be ingested automatically — it's the lost-webhook recovery path, and re-ingesting through your normal idempotent pipeline is safe. The system converges itself.

• Escalate the dangerous cases to a human. "Missing at bank" (you may have credited phantom money) and anything resembling fraud must go to a person with an audit trail. Never let software silently invent or destroy money to "fix" a mismatch — that's how a reconciliation bug becomes a financial loss.

The guiding principle: automation handles the cases where the correct convergence is unambiguous; humans handle the cases where converging the wrong way would move real money incorrectly.

The Eventual-Consistency Mindset

Reframing reconciliation as eventual consistency changes how you build the whole system:

• You stop treating divergence as failure. It's the expected steady state of two asynchronously-communicating replicas. Failure is persistent divergence, not divergence itself.

• The bank is authoritative; your ledger is a replica to keep honest. When they disagree, you converge toward the bank, not the other way around.

• Real-time ingestion and reconciliation are complementary, not redundant. Webhooks give you low latency; reconciliation gives you a correctness backstop that catches everything the real-time path drops. You need both — fast and eventually correct.

Pitfalls

• Treating every real-time mismatch as an incident. Without a time threshold, in-flight transfers look like errors and you drown in false alarms.

• Auto-correcting "missing at bank." Deleting or reversing a ledger entry because the bank "doesn't have it" may erase a legitimate not-yet-settled transaction. Investigate, don't auto-heal.

• Reconciling on a key that isn't stable. If you match on amount+timestamp instead of the bank's transaction ID, coincidental collisions and rounding will wreck you. Always reconcile on the stable, unique identifier.

• Running reconciliation only at end-of-day. Daily batch was the old world; continuous reconciliation catches drift while it's still cheap to fix.

• No audit trail on convergence. Every auto-heal and every manual correction must be recorded — reconciliation that quietly changes balances is itself unauditable.

Conclusion

Reconciliation looks like bookkeeping but it's really distributed-systems convergence wearing an accountant's coat. You and the bank are two replicas of one financial truth, drifting apart constantly as events propagate asynchronously and occasionally get lost. The engine's job is to detect that drift, classify it by structure and age, converge the safe cases automatically, and escalate the dangerous ones — all while treating temporary divergence as normal and only persistent divergence as a problem.

Internalising this reframes the whole money pipeline: idempotent processing keeps ingestion clean, the outbox pattern keeps events from being lost internally, careful concurrency control keeps the ledger self-consistent, and reconciliation is the final safety net proving your replica still agrees with reality. Build all four and you can say the thing every fintech system must be able to say: the books are correct, and here's the proof.

What looks like magic is actually a precise, well-documented string format. There's no proprietary API you have to call to generate one — a VietQR code is just a structured text payload, encoded as a QR image, that any bank app knows how to read. Once you understand the structure you can generate them yourself — which is exactly what I built at qrbank. This post is the breakdown: what VietQR is built on, how the payload is structured field by field, the CRC checksum everyone gets wrong, and how to turn it all into a scannable code.

What VietQR Actually Is

VietQR isn't a from-scratch invention. It's a national profile layered on top of the EMVCo QR Code Specification for Payment Systems — the same global standard behind merchant QR payments in many countries — operated in Vietnam through Napas, the national payment switch. That means two things:

• The payload follows the EMVCo TLV (Tag–Length–Value) format, so the structure is standardised and parseable.

• The Vietnam-specific bits — which bank, which account — live inside a Napas-defined section identified by Napas's application ID.

So generating a VietQR code is really: build an EMVCo TLV string, fill in the Napas merchant section with the bank and account, append a checksum, and render it as a QR image.

The EMVCo TLV Structure

Every field in the payload is encoded as three parts concatenated together:

• Tag — a 2-digit ID saying what the field is (00, 38, 54, …).

• Length — a 2-digit count of how many characters the value has.

• Value — the actual content.

So the very first field, the payload format indicator, is 00 (tag) + 02 (length) + 01 (value) = 000201. A parser walks the whole string this way. A tiny helper makes building them painless:

// Tag–Length–Value: 2-digit tag, 2-digit zero-padded length, then the value
function tlv(tag: string, value: string): string {
  const length = value.length.toString().padStart(2, '0')
  return `${tag}${length}${value}`
}

tlv('00', '01')  // → "000201"
tlv('53', '704') // → "5303704"  (currency VND)

Some tags are templates — their value is itself a sequence of nested TLV fields. The Napas merchant-account section (tag 38) is the important one.

Building the Payload Field by Field

Here are the fields a VietQR transfer payload uses, in order:

• 00 — Payload format indicator: 01

• 01 — Point of initiation method: 11 (static) or 12 (dynamic)

• 38 — Merchant account info (Napas template, nested)

• 53 — Currency: VND = ISO 4217 704

• 54 — Transaction amount (optional)

• 58 — Country code: VN

• 62 — Additional data (optional, e.g. message)

• 63 — CRC checksum (computed last)

The nested tag 38 is the heart of it: 00 = Napas GUID A000000727, 01 = beneficiary (bank BIN + account number), 02 = service code QRIBFTTA (transfer to account).

function buildVietQR(opts: {
  bankBin: string      // e.g. "970415" for Vietinbank
  accountNumber: string
  amount?: number
  message?: string
}): string {
  const beneficiary = tlv('00', opts.bankBin) + tlv('01', opts.accountNumber)
  const merchantInfo =
    tlv('00', 'A000000727') +
    tlv('01', beneficiary) +
    tlv('02', 'QRIBFTTA')

  let payload =
    tlv('00', '01') +
    tlv('01', opts.amount ? '12' : '11') +
    tlv('38', merchantInfo) +
    tlv('53', '704') +
    (opts.amount ? tlv('54', String(opts.amount)) : '') +
    tlv('58', 'VN')

  if (opts.message) {
    payload += tlv('62', tlv('08', opts.message))
  }

  payload += '6304'
  return payload + crc16(payload)
}

The CRC-16 Checksum (the Part Everyone Gets Wrong)

Tag 63 is a 4-character CRC-16 checksum that lets a scanner verify the code wasn't corrupted. The subtle rule everyone misses: the CRC is calculated over the entire payload including the CRC field's tag and length (6304), but not the checksum value itself.

The algorithm is CRC-16/CCITT-FALSE: polynomial 0x1021, initial value 0xFFFF, no reflection.

function crc16(data: string): string {
  let crc = 0xffff
  for (let i = 0; i < data.length; i++) {
    crc ^= data.charCodeAt(i) << 8
    for (let j = 0; j < 8; j++) {
      crc = crc & 0x8000 ? (crc << 1) ^ 0x1021 : crc << 1
      crc &= 0xffff
    }
  }
  return crc.toString(16).toUpperCase().padStart(4, '0')
}

Get any parameter wrong — wrong polynomial, forgetting to include 6304, reflecting the bits — and the string still looks like a valid VietQR code but every banking app rejects it. It's the single most common bug, invisible until you scan with a real app.

Generating the QR Image

Once you have the payload string, feed it to any QR library at error-correction level M. You can try the whole thing live at qrbank.tienng21.com.

import QRCode from 'qrcode'

const payload = buildVietQR({
  bankBin: '970415',
  accountNumber: '113366668888',
  amount: 50000,
  message: 'Thanh toan',
})

await QRCode.toFile('vietqr.png', payload, {
  errorCorrectionLevel: 'M',
  margin: 2,
})

Static vs Dynamic Codes

The point-of-initiation method (tag 01) is a small field with a big UX impact:

• 11 — static: no amount baked in. The payer enters the amount. Print once, stick on the wall, reuse forever. Perfect for a shop or donation jar.

• 12 — dynamic: amount fixed in the code. One code per transaction. Perfect for checkout and invoices.

The only structural difference is whether you include tag 54, but choosing correctly is the difference between a reusable poster and a per-order checkout flow.

Testing and Pitfalls

• Always verify with a real banking app, not just a QR decoder. Only a bank app confirms the payment fields are valid.

• Use the correct Napas BIN, not the bank's SWIFT or hotline number. The wrong 6-digit ID routes nowhere.

• Lengths must match exactly. An off-by-one shifts the entire parse and silently corrupts everything after it.

• Compute the CRC last, over …6304. It's always the CRC.

Conclusion

VietQR feels like infrastructure magic, but under the hood it's a disciplined, fully open format: EMVCo TLV fields, a Napas merchant section carrying the bank and account, and a CRC-16 checksum stitching it together. There's no secret API — once you can build the TLV string and compute the checksum correctly, you can generate a valid, scannable transfer code entirely on your own. Try it live at qrbank.tienng21.com.

The next time you scan a QR at a street stall, you'll know precisely what those black squares are saying.

If you're building on top of VietQR and need to handle what happens after the money arrives — routing, attribution, and reconciliation — my post on Virtual Accounts in Fintech covers exactly that infrastructure layer.

This is the problem virtual accounts solve, and it’s one of the most useful patterns in fintech that most engineers have never had to think about. I don’t ever heard about that before I spent a chunk of my time at a personal-finance startup deep in virtual-account infrastructure — provisioning them, routing transactions through them, and reconciling the results — and it reshaped how I think about money movement. This post is what I learned: what a virtual account actually is, how you provision them at scale, how transactions route through them, and why reconciliation is the whole point.

The Problem Virtual Accounts Solve

The core issue is attribution. A traditional company bank account is a single destination. Every incoming transfer lands in the same place, and the only thing distinguishing one payment from another is whatever the sender typed in the memo. Free-text memos are a catastrophe for automation:

• Users mistype reference codes, so your matching logic fails.

• Two users can coincidentally use the same memo (very big issue - from the architecture aspect).

• Refunds, partial payments, and overpayments have no clean linkage.

• Reconciliation becomes a manual, error-prone, end-of-day chore.

What you actually want is for the destination account number itself to identify the payer — so attribution happens automatically the instant money arrives, with no memo parsing and no guessing. That’s exactly what a virtual account gives you.

What a Virtual Account Actually Is

A virtual account (VA) is a unique account number that maps to a single real “master” settlement account at a partner bank. The bank issues you a range of account numbers; each one looks and behaves like a normal account number to the sender, but all the money actually pools into one physical account you control.

                       ┌────────────────────────────┐
  User A → VA 9988001 →│                            │
  User B → VA 9988002 →│   Master settlement acct   │ → your ledger
  User C → VA 9988003 →│        (one real acct)     │
                       └────────────────────────────┘

The magic is the 1:1 mapping between a VA number and a user (or an invoice, or an order). When a transfer arrives at 9988002, you don’t need to read the memo — the destination number is the identity. Attribution is structural, not textual.

There are two common provisioning models:

• Per-user VAs — each user gets one permanent VA. Good for wallets, recurring deposits, personal finance.

• Per-transaction VAs — a fresh VA is minted for each invoice or order, often with an expiry. Good for one-off checkouts where you want a payment to map to exactly one order.

Provisioning: Minting Accounts at Scale

Provisioning is where the engineering starts. You’re typically issued a BIN-prefixed number range by the bank — say, every account starting 9988 followed by your suffix. Your job is to allocate suffixes uniquely and durably.

async function provisionVirtualAccount(userId: string): Promise<VirtualAccount> {
  // Reuse if this user already has one (per-user model)
  const existing = await db.virtualAccount.findUnique({ where: { userId } })
  if (existing) return existing

  // Allocate the next suffix atomically — no two users may collide
  const suffix = await allocateNextSuffix() // DB sequence or counter, transactional
  const accountNumber = `${BANK_BIN_PREFIX}${suffix.padStart(7, '0')}`

  // Register it with the partner bank so transfers to it are accepted
  await bankApi.registerVirtualAccount({ accountNumber, userId })

  return db.virtualAccount.create({
    data: { userId, accountNumber, status: 'ACTIVE' },
  })
}

The non-negotiables here:

• Uniqueness must be guaranteed at the database level — a sequence or a unique constraint, never an application-side “find max + 1” that races under load. A duplicated VA means two users’ money becomes indistinguishable, which is the exact failure mode you set out to prevent.

• Registration with the bank is a side effect that can fail — wrap provisioning so a half-created VA (allocated locally but not registered) is retried or rolled back, not left dangling.

Transaction Routing: From VA to Ledger

When money hits a VA, the bank notifies you — almost always by webhook. The payload says “account 9988002 received 500,000 VND.” Routing is the act of turning that raw event into a ledger entry attributed to the right user:

async function handleIncomingTransfer(event: BankWebhookEvent) {
  const va = await db.virtualAccount.findUnique({
    where: { accountNumber: event.accountNumber },
  })
  if (!va) {
    // Money arrived at a VA we don't recognise — quarantine, don't drop
    return quarantineUnmatchedPayment(event)
  }

  await db.ledgerEntry.create({
    data: {
      userId: va.userId,
      type: 'CREDIT',
      amount: event.amount,
      reference: event.bankTransactionId, // idempotency key
    },
  })
}

Two things make or break this:

• Never drop an unmatched payment. If a transfer arrives for an account you can’t resolve, quarantine it for investigation. Money must never silently vanish — that’s a regulatory and trust failure, not just a bug.

• The bank’s transaction ID is your idempotency key. Banks retry webhooks. Without idempotency you’ll double-credit a user every time a webhook is redelivered.

Reconciliation: The Real Payoff

Here’s the part people underestimate. Your system has its own record of what should have happened (your ledger). The bank has its own record of what actually happened (the settlement account statement). Reconciliation is proving those two agree — every credit in your ledger corresponds to a real transfer in the bank’s statement, and vice versa.

VAs make this tractable because every payment is pre-attributed. A daily reconciliation job pulls the bank statement and matches each line against your ledger by transaction ID:

async function reconcileDay(date: string) {
  const statement = await bankApi.getStatement(date) // source of truth: the bank
  const ledger = await db.ledgerEntry.findMany({ where: { date } })

  const byBankId = new Map(ledger.map(e => [e.reference, e]))

  for (const line of statement.lines) {
    const entry = byBankId.get(line.transactionId)
    if (!entry)
      flagMissingInLedger(line) // bank has it, we don't
    else if (entry.amount !== line.amount) flagMismatch(entry, line)
    byBankId.delete(line.transactionId)
  }
  for (const orphan of byBankId.values()) flagMissingAtBank(orphan) // we have it, bank doesn't
}

Three failure classes fall out of this, and naming them is half the job:

• Missing in ledger — the bank received money you never recorded (a dropped webhook). Recover it.

• Missing at bank — you recorded a credit the bank has no record of. A bug or a fraudulent event; investigate hard.

• Amount mismatch — same transaction, different number. Almost always a parsing or currency-unit error on your side.

A clean reconciliation run — zero discrepancies — is the daily proof that your money movement is correct. That report is what lets finance, auditors, and regulators trust the system.

Webhooks, Idempotency, and Eventual Consistency

Money systems are distributed systems, and the bank is a partner you don’t control. Internalise three things:

• Webhooks are at-least-once. Design every handler to be idempotent on the bank’s transaction ID. Re-processing the same event must produce the same ledger, not a second credit.

• The bank is the source of truth, your ledger is a replica. When they disagree, the statement wins. Your reconciliation job exists precisely to detect and resolve that drift.

• Embrace eventual consistency. A transfer may show in a webhook seconds after it lands, or minutes. Build for the gap — pending states, retries, and a reconciliation backstop that catches anything the real-time path missed.

Edge Cases That Bite

The happy path is easy; the money is in the edges:

• Overpayment / underpayment — for per-transaction VAs, decide up front whether a wrong amount is accepted, refunded, or held.

• Late payment after expiry — money can arrive at an expired per-transaction VA. You still received it; you still must handle it.

• Refunds and reversals — a credit can be clawed back. Your ledger needs the inverse entry, reconciled like any other.

• Currency and minor units — store amounts in the smallest unit (e.g. integer VND/cents). Floating-point money is a bug waiting to happen.

Conclusion

Virtual accounts are a small idea with an outsized payoff: make the destination account number carry identity, and attribution stops being a memo-parsing guessing game. Provisioning gives every user or invoice a unique, bank-registered number; routing turns incoming transfers into attributed ledger entries idempotently; and reconciliation proves, every single day, that your records and the bank’s records tell the same story.

What stuck with me most is the mindset shift. In most software a dropped event is an inconvenience; in money movement it’s an unreconciled discrepancy that someone will notice. Building with virtual accounts taught me to treat the bank as the source of truth, my ledger as a replica to keep honest, and reconciliation as the non-negotiable safety net underneath it all.