The authorisation-to-settlement gap is where card balances go wrong
An auth and a settlement are different events with different amounts. Compute the balance from either one alone and the customer pays for it.
If you are issuing cards on top of a wallet, the hardest thing in the system is not the card network integration. It is deciding what number to show the customer.
An authorisation is a hold: the merchant asks whether the money is there, and the network freezes it. A settlement is the actual movement, and it lands days later. The two are not the same amount and sometimes the second one never arrives at all.
- A restaurant authorises the bill, then settles with a tip added.
- A fuel pump authorises a flat amount - often far more than the fill - then settles the real figure.
- A merchant authorises, then abandons the transaction. Nothing ever settles.
- A foreign purchase settles at a different conversion rate than the one quoted.
The two ways to get it wrong
Balance from settlements only. The auth is invisible, so the customer can spend money that is already spoken for. You find out when something declines that should not have.
Balance from authorisations only. Funds stay locked behind holds that silently expired weeks ago. The customer complains that their money is missing, and they are right.
The shape that holds up
Treat them as separate entry types against the same wallet:
- An authorisation posts a hold with an explicit expiry, taken from the network's rules for that transaction class rather than a number someone guessed.
- A settlement posts a movement and releases the matching hold in the same transaction.
- A sweeper expires stale holds on schedule. Not on a cron that someone disabled during an incident - on the network's timetable, with alerting if the queue grows.
- Available balance is derived: cleared balance minus live holds. It is never stored.
The case nobody plans for
A settlement arrives with no matching authorisation. It happens - force captures, offline transactions, and occasionally fraud.
The tempting thing is to apply it anyway, because the money genuinely moved. Do not. Send it to an exceptions queue with the raw network message attached, and have a human look. An unmatched settlement is a signal, and force-applying it destroys the only evidence you had.