Idempotency keys and double-entry ledgers for payments
Updated Nov 10, 2026 · 3 min read
Most systems can shrug off a request that runs twice. A payment system can’t. Charge someone twice and you have an angry customer. Lose track of a charge and finance can’t close the books. Payments are built on a few ideas that make retries safe and every cent traceable.
Idempotency keys
An operation is idempotent when doing it twice has the same effect as doing it once. Reading is idempotent. Charging a card is not, unless you make it so. The tool is an idempotency key, a unique string the client makes once per attempt to pay and sends with every retry of that attempt.
- Look up the key. If it has a stored result, return that result and stop.
- Claim the key as in progress, with a unique constraint so only one copy wins. A second copy arriving now gets “try again shortly”.
- Do the work. Pass the same key to the payment provider, so your own retries are safe too.
- Save the ledger entries and the result under the key in one database transaction.
- Reply.
Store a hash of the request with the key. If the same key arrives with a different amount, that’s a bug in the client, so reject it rather than return the old result. Keep keys for at least a day, longer than any client will keep retrying. Stripe, for example, keeps them for 24 hours.
A timeout means “unknown”
When a call to the provider times out, three things may have happened. The request never arrived, it arrived and failed, or it arrived and succeeded and the reply was lost. You can’t tell which, so don’t guess. Treating it as failed risks a double charge if the customer pays again. Treating it as paid risks shipping for free.
- Mark the payment as unknown, and show the customer “processing”.
- Retry with the same idempotency key. The provider returns the first result if there was one.
- Or ask the provider for the payment’s status by your reference.
- Have a background job sweep anything still unknown after a few minutes.
The double-entry ledger
Accountants solved “where did the money go” centuries ago. Every movement of money is recorded as entries in at least two accounts, and each transaction’s debits equal its credits. Money never appears or vanishes, it only moves between accounts.
| Account | Debit | Credit |
|---|---|---|
| Cash held at the provider | $100 | |
| Owed to the seller | $90 | |
| Commission revenue | $10 | |
| Total | $100 | $100 |
- Append only. Entries are never edited or deleted. A refund is a new transaction going the other way.
- Balances are sums of entries. Cache them if you like, but the entries are the truth.
- Store money as whole cents in integers, never as floating point.
- If a transaction’s entries don’t sum to zero, refuse to write it. That one check catches a whole class of bugs.
Reconciliation
Your ledger is your story. The provider’s settlement file, sent every day, is theirs. A nightly job matches the two, payment by payment, using your reference on each charge, and flags anything that doesn’t line up.
| Mismatch | Likely cause | What to do |
|---|---|---|
| Provider has a charge you don’t | A timeout hid a success | Record it, or refund it if the order was cancelled |
| You have a payment they never settled | Declined, or still pending | Hold the seller’s payout until it settles |
| One order charged twice | A retry went out with a new key | Refund one, and fix the client |
| Amount a little short | The provider’s fee | Record the fee as its own entry |
Keeping card numbers off your servers
Any server that receives, processes or stores card numbers falls under PCI DSS, the card industry’s security standard, with its long list of controls and audits. The way out is tokenization. Your checkout shows the provider’s card form, usually in an iframe. It sends the card number straight to the provider, which returns a token like tok_1Nv…. You store and charge the token. It’s useless to anyone but you and the provider.
Encrypting or hashing card numbers yourself doesn’t get you out, because the numbers still reach your servers first. With the provider’s form, your PCI work shrinks to a short self-assessment questionnaire.