Giving authorized staff a safe way to correct financial records without bypassing the ledger.
Automated payment systems still need operational tools. External balances can differ from local ledgers, a transaction may require manual confirmation, or a historical integration issue may need a controlled correction.
The dangerous response is direct database editing. It changes the current value while destroying the explanation of how and why it changed.
Reconciliation should be a first-class financial workflow.
Represent the adjustment as a transaction
A reconciliation entry should capture:
- entity type and identifier;
- wallet or account affected;
- currency and amount;
- credit or debit direction;
- reason and supporting note;
- staff actor;
- approval or execution status;
- balance before and after; and
- creation and execution timestamps.
The adjustment reference must be unique so retries cannot apply it twice.
Separate preparation from execution
For sensitive adjustments, one action can create a pending reconciliation entry and another authorized action can execute it.
Execution should lock both the reconciliation record and affected wallet, re-check that the entry has not already run, apply the ledger mutation, record before-and-after balances, and mark the entry completed atomically.
Use permissions by action
Viewing financial records, creating an adjustment, approving it, and executing it are different capabilities. Staff access should reflect that distinction.
The user interface should communicate when an action is unavailable because of permissions rather than hiding the transaction’s history.
Preserve linked effects
When staff complete a stuck transaction, the service must perform the same linked effects as the normal path: settle holds, update associated records, close operational tasks, and notify the customer once.
Staff tools should call domain services. They should not implement alternate financial logic in dashboard endpoints.
Make balance differences visible
For externally backed virtual accounts, show local ledger balance beside the latest provider-reported balance and synchronization time. A difference becomes an observable item to investigate rather than an invisible overwrite.
Keep evidence optional where appropriate
Some manual actions may include a receipt or document. If policy allows completion without an image, the backend should treat evidence as optional while still requiring the actor, reason, and audit record.
The design principle
Operational access should increase control, not bypass it.
Safe reconciliation tools use the same row locks, idempotency guarantees, ledgers, and state transitions as automated flows. The difference is that an authorized human supplies the decision and reason, both of which become part of the permanent audit trail.
Top comments (0)