The summary.
NEVER USE FLOATING POINT FOR MONEY
Use integers in the smallest unit or a decimal type, always store the currency alongside, and never assume two decimal places.
NEVER STORE A BALANCE AS A MUTABLE NUMBER
Derive it from immutable double-entry records. A stored balance cannot be audited, and a concurrency error corrupts it invisibly.
Run a daily check that the ledger sums to zero, and stop if it does not.
NO RESPONSE IS INDISTINGUISHABLE FROM SUCCESS, FAILURE AND SLOWNESS
Never assume failure and retry. Record as pending, query by your own reference, and tell the customer the payment is being confirmed — not that it failed.
GENERATE IDEMPOTENCY KEYS FROM THE BUSINESS INTENT, NOT PER ATTEMPT
A new key each attempt defeats the purpose. Enforce uniqueness at the database, which is the only place a race cannot bypass.
RECONCILE THREE SOURCES, NOT TWO
Your records, the provider's, and the bank. Investigate first what the provider has and you do not — that is money received against no order.
Never adjust records to force agreement.
