Payments fail in ordinary ways: a timeout after the money moved, a retry that arrives twice, a webhook that never came. A ledger that only records successful intent will mislead you. A ledger built for these realities — idempotent writes, compensating entries and clean reconciliation — will not.

Idempotency keys

Every instruction should carry a key that identifies it. If the same instruction arrives twice, the system should recognise the second as a repeat and return the original outcome rather than creating a new entry. This protects against the most common source of duplicates: a caller who did not receive a response and tried again.

The key belongs to the intent, not the attempt. Retries reuse it; a genuinely new payment gets a new one.

Reversals as new entries

Double-entry accounting does not erase history. A reversal is not a deletion of the original entry — it is a compensating entry that moves the balances back. This keeps the record complete: what happened remains visible, and the correction is visible beside it. For audit purposes, an erased entry is worse than a wrong one.

Reconciliation

Reconciliation compares what your ledger says with what actually moved. Because balances sit with licensed partners before a banking licence, the ledger and the partner statements are two views that must be brought into agreement. Signed, verifiable documents and per-unit reporting make that comparison a routine check rather than an investigation.

One structural convenience is netting. Approved operations enter a single order book, where offsetting flows cancel internally and only the remainder is routed outward. For reconciliation this means the outward movement is smaller than the gross activity, and the internal entries still have to balance.

Good reconciliation rests on a few habits:

  • one immutable record per operation, attributed to principal, agent and policy version
  • a clear status model — proposed, executed, settled, reversed
  • differences surfaced as exceptions, not buried in aggregates

In short

  • Use idempotency keys tied to intent, reused across retries.
  • Reverse with compensating entries; never delete history.
  • Reconcile your ledger against partner statements as a normal routine.
  • Attribute every entry to principal, agent and policy version.

Read the architecture notes before you build: developers.