Enter git commit --fixup — a powerful flag that, combined with git rebase --autosquash, lets Git automatically arrange and squash your messy commits into a clean history. Here's how to use it.

What is git commit --fixup?

git commit --fixup creates a new commit that is explicitly marked as a fixup for an earlier commit. The key difference from --amend:

• git commit --amend: rewrites the most recent commit in place (changes its hash).

• git commit --fixup: creates a new commit prefixed with fixup!, which rebase --autosquash will later merge into its target automatically.

When combined with git rebase -i --autosquash, you can:

• Add forgotten files to an earlier commit

• Fix typos or bugs that belong to a previous commit

• Squash multiple related commits into one — automatically, without manual reordering

The Traditional Problem

Consider this common scenario:

git commit -m "wip: add authentication"
git commit -m "fix: typo in auth"
git commit -m "add tests for auth"
git commit -m "update auth logic"
git commit -m "fix off-by-one error"
git commit -m "wip: add authorization"
git commit -m "refactor auth module"

Seven commits for what should be one cohesive "Add authentication" feature. Without --fixup, you'd open git rebase -i and manually mark each commit as squash or fixup — repetitive and easy to get wrong.

The Basic Fixup Workflow

Here's the pattern:

# 1. Make your original commit
git commit -m "feat: add user authentication"

# 2. Later, realise you forgot something — add it as a fixup
git add password-reset.ts
git commit --fixup=HEAD

# 3. When ready to clean up, run autosquash
git rebase -i --autosquash HEAD~2

The --fixup=HEAD flag creates a commit named fixup! feat: add user authentication. When you run rebase --autosquash, Git automatically moves that commit directly after its target and marks it fixup in the interactive editor — you just save and close.

Step-by-Step: Fixup with autosquash

Say your log looks like this:

abc1234 feat: implement login
def5678 fixup! feat: implement login
ghi9012 wip: update docs
jkl3456 fixup! feat: implement login

Run:

git rebase -i --autosquash HEAD~4

Git automatically opens the editor pre-arranged as:

pick abc1234 feat: implement login
fixup def5678 fixup! feat: implement login
fixup jkl3456 fixup! feat: implement login
pick ghi9012 wip: update docs

Save and close — Git squashes all three login commits into one and leaves the docs commit untouched. No manual reordering needed.

Real-World Example: Bug Fix with Multiple Passes

# Initial fix
git commit -m "fix: handle null pointer in user service"

# Test reveals another case
vim user.service.ts
git add user.service.ts
git commit --fixup=HEAD

# Add a regression test
git add user.test.ts
git commit --fixup=HEAD

# Log now shows:
# abc1234 fix: handle null pointer in user service
# def5678 fixup! fix: handle null pointer in user service
# ghi9012 fixup! fix: handle null pointer in user service

# Clean up
git rebase -i --autosquash HEAD~3
# All three combined into one clean commit automatically

Real-World Example: Multi-Step Feature

You want this final history:

• feat: add authentication system

• refactor: clean up auth flow

But your current log is:

f47ac8 refactor: clean up auth flow
ba3d92 wip: add logout
8c7e1a wip: add token refresh
4a5b6c fix: handle edge case
9c8d7e wip: add login form
2a3b4c wip: setup auth context

Run git rebase -i HEAD~6 and arrange:

pick   2a3b4c wip: setup auth context
squash 9c8d7e wip: add login form
fixup  4a5b6c fix: handle edge case
fixup  8c7e1a wip: add token refresh
squash ba3d92 wip: add logout
pick   f47ac8 refactor: clean up auth flow

Git squashes the first five into one, opens the editor so you can write a clean message like feat: add authentication system, then keeps the refactor commit separate.

Best Practices

Set autosquash globally

Save yourself from typing --autosquash every time:

git config --global rebase.autoSquash true

Now git rebase -i HEAD~N automatically honours fixup! commits.

Write good original messages

Since fixup commits inherit the target's message, a descriptive original message means you won't need to edit anything when squashing:

# Bad — you'll need to rewrite this during squash
git commit -m "fix"

# Good — already describes the final state
git commit -m "fix: handle null pointer in auth service when user not found"

Test after rebasing

git rebase -i --autosquash HEAD~5
npm test
# If tests fail, recover from reflog:
git reflog
git reset --hard HEAD@{1}

Back up before large rebases

git branch backup-before-cleanup
git rebase -i HEAD~10
# If something goes wrong:
git reset --hard backup-before-cleanup

Common Pitfalls

• Don't rebase public history. If commits are already on a shared branch, use merge instead. Check first: git log origin/main..HEAD. If the output is empty, don't rebase.

• Force-push safely. After rebasing a feature branch, use git push --force-with-lease instead of --force to avoid overwriting a teammate's push.

• Don't squash too aggressively. Three focused commits reviewable on their own are better than one giant commit that's impossible to review.

• Resolve conflicts carefully. If a conflict arises mid-rebase, edit the file, stage it with git add, then git rebase --continue. If it gets messy, git rebase --abort returns you to where you started.

Troubleshooting

Git doesn't recognise --fixup: ensure you're on Git 2.24 or later (git --version).

Squashed commit has the wrong message:

git commit --amend   # if it's the most recent commit
# or
git rebase -i HEAD~2  # to edit an earlier commit interactively

Unexpected conflicts during rebase: abort, review what changed between the commits you're squashing, and try again with a tighter range.

Summary

git commit --fixup combined with rebase --autosquash is the fastest way to keep your commit history clean without the manual overhead of interactive rebase every time. The workflow is simple: commit normally, mark corrections with --fixup as you go, then run one rebase --autosquash command before opening your PR. Git does the reordering and squashing for you.

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.

Understanding Git’s DAG structure transforms Git from a set of memorized commands into a predictable, powerful tool. Instead of asking “what command do I run?” you’ll ask “what structure do I want to create?” This mental model helps you reason about complex situations, debug issues, and perform advanced operations with confidence.

In this guide, we’ll explore Git’s internal graph structure from first principles. You’ll learn how commits, branches, and references fit together, how to visualize the DAG, and how to manipulate it safely.

What Is Git’s DAG?

Git stores your project’s history as a Directed Acyclic Graph where commits are nodes and parent relationships are edges. Let’s break down what this actually means and why it matters.

What Makes It a DAG?

A Directed Acyclic Graph has three defining properties: direction (edges point from child to parent), no cycles (you can’t follow parent pointers back to a commit you’ve already visited), and connectivity (every commit except the initial one has at least one parent). These aren’t just mathematical trivia — they fundamentally shape how Git works.

The direction of edges means there’s always a clear “backward” path from any commit to the beginning of history. When you run git log, Git follows these parent pointers backward, showing you increasingly older commits. The absence of cycles guarantees this process terminates. And connectivity ensures every commit is traceable back to the project’s origin.

Consider what happens when you create a merge commit with two parents. Git stores this as a single node with two edges pointing backward, one to each parent. The graph structure makes parallel development natural and explicit.

Git’s Object Storage

Git implements this DAG using four core object types: blobs (file contents), trees (directory listings), commits (snapshots with metadata), and tags (pointers to commits). Each commit object contains a SHA-1 hash, the tree hash, parent commit hashes, timestamps, and the commit message.

The hash uniquely identifies the commit based on its content — if anything changes, the hash changes. This content-addressable storage means Git can detect corruption and guarantee integrity. Here’s what a commit object looks like internally:

tree 3a4b5c6d7e8f0g1h2i3j4k5l6m7n8o9p0q1r2s
parent 9z8y7x6w5v4u3t2s1r0q9o8n7m6l5k4j3i2h1g
author Jane Developer <jane@example.com> 1735689600 +0000
committer Jane Developer <jane@example.com> 1735689600 +0000

Add user authentication feature

The parent reference creates the edge in our DAG. This is why Git’s history is immutable — you can’t change a commit’s parent without changing its hash, which would require updating all descendant commits.

References, Branches, and HEAD

References are human-readable names that point to commits. The most common reference is a branch, which is simply a movable pointer to a commit. When you create a branch with git branch feature-x, Git creates a file at .git/refs/heads/feature-x containing the SHA-1 hash of the current commit.

HEAD is a special reference that points to the branch you’re currently working on. When you make a new commit, Git updates the branch HEAD points to, moving the branch reference forward. This design explains why branching in Git is instant and cheap — creating a branch just means writing a 41-byte file containing a commit hash.

Other important references include:

• Remote-tracking branches (refs/remotes/origin/main) track remote branches

• Tags point to specific commits and don’t move

• The reflog records every position HEAD has occupied

• Stashes are commits pointed to by special refs

When you delete a branch with git branch -d, Git checks whether the branch’s commits are reachable from another reference. If not, it warns you. These commits still exist in the object database until garbage collection, but they’re no longer accessible through normal references.

Visualizing the Graph

The most basic visualization is git log --graph --oneline --all, which shows commits as nodes with lines connecting them:

* a1b2c3d (HEAD -> main) Fix critical bug
| * e5f6g7h (feature-x) Add new feature
|/
* d4e5f6g Initial commit

When reading the graph, look for important patterns:

• Linear chains represent sequential development

• Merge commits have multiple parents (two lines converging)

• Branch points occur where divergent commits share a parent

• Orphaned commits with no path from HEAD will be garbage collected

More sophisticated tools like gitk, tig, or GitKraken make these patterns even more explicit.

Safe vs. Dangerous Operations

The key to working confidently with Git is understanding which operations rewrite history and which only add new commits.

Safe Operations (Add New Commits)

Any operation that adds new commits without changing existing ones is safe, even for shared history. Merging is the canonical example:

git checkout main
git merge feature-branch

This creates a new commit with two parents. No existing commits are modified, so this is safe even if others have based work on main.

Cherry-picking also creates new commits rather than modifying existing ones:

git cherry-pick abc1234

Git creates a new commit containing the same changes but with a different hash (different parent, different timestamp). The original commit remains untouched.

Dangerous Operations (Rewrite History)

Rebasing rewrites history by creating new commits and abandoning old ones. This is powerful but dangerous for shared history:

git checkout feature-branch
git rebase main

This finds the merge base between feature-branch and main, then recreates each commit with main as the new parent. Anyone who built work on the original commits will need to reconcile — the old commits still exist in the reflog, but they’re no longer referenced by a branch name.

Interactive rebasing gives you surgical control:

git rebase -i HEAD~5

This opens an editor showing the last five commits, letting you reorder, squash, edit, or drop them. Each action rewrites history.

Recovery: The Reflog Is Your Safety Net

When things go wrong, the reflog records every position HEAD has occupied — including commits you’ve “lost” through rebasing or branch deletion:

# Show everywhere HEAD has been
git reflog

# Restore to a previous state
git reset --hard HEAD@{5}

Git garbage collection won’t remove commits still in the reflog, giving you a window to recover mistakes. Before panicking about lost work, always check the reflog first.

Detached HEAD state occurs when HEAD points directly to a commit rather than a branch reference. Any commits you create in this state aren’t referenced by a branch name and can be lost if you switch away. To preserve them:

git checkout -b rescue-branch

Key Takeaways

• Git stores history as a DAG where commits are nodes and parent references are directed edges. This structure provides integrity, enables efficient operations, and makes parallel development explicit.

• References are movable pointers to commits. Branches are simply references, and HEAD is a special reference pointing to your current location. Understanding this clarifies branch operations and detached HEAD.

• Safe operations add new commits without modifying existing ones. Merging, cherry-picking, and branching are safe even for shared history because they only extend the graph.

• Rebasing rewrites history by creating new commits. Use rebase on local feature branches; avoid it on public branches others have based work on.

• The reflog provides recovery from mistakes. Every position HEAD occupies is recorded. Before panicking about lost work, check the reflog.

Git’s DAG structure isn’t just an implementation detail — it’s the foundation for everything Git does. Next time you encounter a merge conflict, a confusing rebase, or an unexpected Git state, visualize the graph. Ask yourself: what does the graph look like right now? What references point where? What operation will produce the structure I want? This mental model will serve you through every Git challenge you face.

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.

Love technology, building helpful tool, so firstly I’m creating tool to support my own demand. Currently is for learning English and Japanese, some other tool for productivity so I'll share about it as well.

Let’s start!!