← All articles

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.

  1. Look up the key. If it has a stored result, return that result and stop.
  2. Claim the key as in progress, with a unique constraint so only one copy wins. A second copy arriving now gets “try again shortly”.
  3. Do the work. Pass the same key to the payment provider, so your own retries are safe too.
  4. Save the ledger entries and the result under the key in one database transaction.
  5. Reply.
Pay + keylook up, claimsame keyentriesCheckout appPaymentsIdempotencyProviderLedger
Every retry carries the same key, so the work happens once and every copy gets the same 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.

AccountDebitCredit
Cash held at the provider$100
Owed to the seller$90
Commission revenue$10
Total$100$100
A $100 order that pays the seller $90 and keeps a $10 commission.
  • 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.

MismatchLikely causeWhat to do
Provider has a charge you don’tA timeout hid a successRecord it, or refund it if the order was cancelled
You have a payment they never settledDeclined, or still pendingHold the seller’s payout until it settles
One order charged twiceA retry went out with a new keyRefund one, and fix the client
Amount a little shortThe provider’s feeRecord 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.