Preventing retries, cancellations, and concurrent withdrawals from making reserved balances drift.
A payment system often needs to reserve money before the final debit occurs. A withdrawal may be awaiting provider acceptance, a bank transfer may require manual review, or a card authorization may remain unsettled for several days.
The tempting implementation is a mutable counter:
account.held_amount += requested_amount
account.save()
This looks efficient, but it hides the reason money is unavailable. It also makes correctness depend on every success, failure, cancellation, timeout, and retry updating the counter in exactly the opposite way.
A safer design treats each hold as an identifiable financial record:
hold key: withdrawal:{reference}
owner: wallet identifier
amount: 125.00
currency: USD
status: active
Available balance then has a precise definition:
available = posted balance - sum(active holds)
The important ordering is to claim the hold identity before changing any cached aggregate. Within one database transaction, insert the hold using a unique business key. If that key already exists, compare the canonical request payload. A matching retry returns the existing hold; a different amount or wallet is a hard conflict.
Only the request that successfully creates the hold may apply any associated cached balance update. This ordering prevents a retry from incrementing a counter before discovering that the hold already exists.
Treat the hold lifecycle as a state machine
A hold should move through explicit states such as active, captured, released, and expired. Terminal transitions must be idempotent. Releasing an already released hold should return the existing result instead of adding the amount back again.
Capturing a hold normally creates the final debit and marks the hold captured in the same transaction. Releasing it removes the reservation without creating a debit. Expiry should use the same release service as a manual cancellation so there is only one implementation of the financial rule.
Lock the wallet and hold together
Two withdrawals can arrive simultaneously. Both may observe enough available balance before either creates its hold. Lock the wallet row, calculate active holds inside the transaction, and create the new hold before releasing the lock.
A database uniqueness constraint on the hold key protects retries. Row locking protects competing requests for the same funds. They solve different concurrency problems.
Use aggregates as caches, not truth
For high-volume reads, summing holds repeatedly may be expensive. A cached held_amount is reasonable if the hold rows remain authoritative. Reconciliation should periodically compare the cached value with the sum of active records and repair or alert on differences.
The same rule applies to provider-side reservations. Local accounting needs to distinguish posted funds, reserved funds, pending outbound money, and externally settled money.
Test the failure boundaries
Useful tests include duplicate requests, two simultaneous withdrawals competing for the same balance, a crash after hold creation, repeated release commands, capture after expiry, and late provider success after a hold was released.
The goal is not merely to stop a negative balance. It is to retain an explainable record of why funds were unavailable and ensure every retry reaches the same result.
Implementation checklist
Give every hold an immutable owner, currency, amount, business reference, and payload fingerprint. Enforce uniqueness in the database. Define exactly which states contribute to reserved balance and which transitions create ledger entries. Lock the wallet during affordability checks, and use decimal arithmetic at the currency's supported precision.
Monitor active holds by age and reason. A growing population of old holds usually indicates a missing provider callback, failed release task, or incomplete operational workflow. Provide staff with a permission-controlled release action that records the actor and reason while still calling the standard hold service.
Top comments (1)
The point about treating the cached held amount as a cache rather than the source of truth is the part teams skip most often. One thing I'd add is a periodic reconciliation job that also records how long each hold has been active, because a slow rise in old holds is usually the first sign of a missing provider callback. Have you found a good default expiry for holds tied to bank transfers versus card authorizations?