Notes
Requirements
Fix the scope. A merchant charges an amount by card, UPI or net banking. We route the charge to a processor that supports the method and fail over if that processor is down. Merchants can refund fully or in parts and get a notification on every change. Two rules matter more than everything else: a retried request must never charge twice, and refunds must never exceed what was charged. Card verification and currency exchange are out of scope.
- merchant charges an amount
- by card, UPI or net banking
- route to a processor that
- supports the method
- fail over if a processor is down
- full and partial refunds
- tell the merchant on change
- a retry must never charge twice
- refunds never exceed the charge
- out of scope: 3-D Secure, FX
State machine
Start with the payment's life. Created moves to processing when we call a processor. Processing ends as succeeded or failed, and failed is final. A succeeded payment can be partially refunded, possibly several times, and finally fully refunded. Write these legal moves down as a table from each status to the set of next statuses. Any move not in the table throws, so a bug can never mark a failed payment as paid.
In code, the table is a map from status to an enum set, and one synchronized move method checks it before changing anything. The method also appends to a history list, so support staff can see exactly how a payment got where it is. Putting the rules in data instead of scattered if statements means adding a new state, like disputed, is one line in the table.
- CREATED -> PROCESSING
- PROCESSING -> SUCCEEDED
- -> FAILED (final)
- SUCCEEDED -> PARTIALLY_REFUNDED
- -> REFUNDED
- PARTIALLY_REFUNDED
- -> PARTIALLY_REFUNDED
- -> REFUNDED (final)
- anything else: throw
static final Map<Status, Set<Status>>
NEXT = Map.of(CREATED,
EnumSet.of(PROCESSING), ...);
synchronized void move(Status next) {
if (!NEXT.get(status).contains(next))
throw new IllegalStateException(..)
status = next;
history.add(next.name());
} Idempotency
Now the most important idea. A merchant sends a charge, we process it, and the network drops our reply. The merchant cannot tell whether it worked, so it retries. Without protection the customer pays twice. The fix is an idempotency key: the merchant sends its own unique id, like its order number, with every request. We remember the key with its result, and any retry with the same key gets the original result back instead of a new charge.
Retries can arrive at the same moment, so a plain check-then-insert is not enough. We store a future, not a result. Each request creates an empty future and calls put-if-absent on a concurrent map. Exactly one request wins and does the real work; the other nine find the winner's future and wait on it. When the work finishes, all ten return the same payment id, and the processor is called exactly once.
- merchant sends pay(order-2)
- network drops our response
- merchant retries pay(order-2)
- without a key: charged twice
- with a key: same payment back
- key = merchant + their order id
- stored with the result
- for 24 hours or more
var mine = new CompletableFuture<>();
var old = idem.putIfAbsent(
merchant + ":" + key, mine);
if (old != null) return old.join();
try {
mine.complete(process(...));
} catch (RuntimeException e) {
mine.completeExceptionally(e);
throw e;
}
return mine.join(); Strategy: routing
Which processor handles a payment is a business choice: the cheapest fee, the best success rate for this bank, a rule for a big merchant. So routing is a strategy that returns an ordered list of processors that support the method. The first is the primary, the rest are failovers. Each processor is behind a small interface with a name, the methods it supports and a charge call, which also makes them easy to fake in tests.
interface RoutingStrategy {
List<Processor> route(Payment p,
List<Processor> all);
}
PriorityRouting: supports method,
in priority order
later: cheapest fee, best success
rate per bank, per-merchant rules Flow: charge
Here is the rule that separates a good answer from a dangerous one. If a processor is unreachable, try the next one. But if the bank answers declined, stop: the customer's card said no, and retrying elsewhere looks like fraud and can annoy the customer. Mark the payment failed. And if a call times out after it may have reached the bank, do not blindly retry; ask the processor for the outcome later.
- processor unreachable or 5xx:
- try the next processor
- bank says declined:
- stop, mark FAILED
- another route would just
- annoy the customer or look
- like card testing
- unknown result after timeout:
- ask the processor later
Ledger
Every movement of money becomes an entry in an append-only ledger: plus the amount for a charge, minus for each refund. You never edit or delete an entry; a mistake is fixed with a new opposite entry. The balance of a payment is just the sum of its entries, so the status and the money can always be checked against each other. Amounts are whole paise in a long, never a double.
record Entry(String paymentId,
String kind, long cents)
charge 2,499.00 -> +249900
refund 1,000.00 -> -100000
refund 1,499.00 -> -149900
balance 0
append-only: the history is the
source of truth for money Refunds
Refunds have their own race. Two support agents refund the same order at the same moment, each for the full amount. If each checks the remaining amount and then subtracts, both pass and we pay back double. So the check, the update, the state change and the ledger entry happen together inside one lock on that payment. The second agent sees nothing left and gets a clear error.
synchronized (p) {
long left = p.amount - p.refunded;
if (cents <= 0 || cents > left)
throw: exceeds remaining
p.refunded += cents;
p.move(refunded == amount
? REFUNDED
: PARTIALLY_REFUNDED);
ledger.add(refund entry);
} Observer: webhooks
Merchants learn about changes through webhooks, which are just the Observer pattern over the network. After every status change we publish an event to each subscriber. In a real system the body is signed so the merchant knows it came from us, failed deliveries are retried with backoff for a day, and each event carries an id so the merchant can safely ignore duplicates. The merchant can also poll the payment at any time.
- observer list of Webhook
- sent after every status change
- real systems:
- sign the body (HMAC)
- retry with backoff for a day
- include an event id so the
- merchant can ignore repeats
- the merchant can always poll
- GET /payments/{id} too
Concurrency
Check every shared field. Idempotency is a concurrent map of futures. Status changes go through one synchronized method, and a refund does its check and update under the same payment lock. The ledger here is a copy-on-write list; in production it is a database table. Calls to processors happen with no lock held, because a slow bank must never block other payments.
- idempotency: ConcurrentHashMap
- of CompletableFuture
- payment state: synchronized move
- refund: check + update in one
- lock on the payment
- ledger: CopyOnWriteArrayList
- (a table in real life)
- processor calls: no lock held
- ids: AtomicLong
Extensibility
Now the follow-ups. Card verification adds a requires-action state between processing and success. Authorise now and capture later adds an authorised state. Chargebacks add a disputed state. A new payment method is a new processor class, and smarter routing is a new strategy. For durability, the idempotency record, the payment and the ledger entry are written in one database transaction, so a crash can never leave them disagreeing.
- 3-D Secure: REQUIRES_ACTION
- state between PROCESSING
- auth then capture: AUTHORIZED
- state, capture within 7 days
- disputes: DISPUTED state
- new method: a new Processor
- smart routing: a new strategy
- durability: idempotency keys and
- ledger in one DB transaction
Testing
The full code is below the player. The demo charges an order, then sends the same request ten times from ten threads and shows one payment id and one processor charge. It takes the first processor down and shows failover, sends an amount the bank declines and shows no retry, refunds in two parts while rejecting a refund that is too large, and prints the payment's full history.
order-1: pay_1 SUCCEEDED via alpha order-2 sent 10 times: [pay_2], charged 1 time alpha down: order-3 via beta order-4 over limit: FAILED refund 2,000.00: exceeds remaining refund the rest: REFUNDED, balance 0 illegal: cannot go FAILED->SUCCEEDED history: CREATED, PROCESSING, SUCCEEDED, PARTIALLY_REFUNDED, REFUNDED
Say it like this
Here is the short version to say out loud. A payment is a state machine with a table of legal moves. Every request carries an idempotency key, and one put-if-absent of a future means even a retry storm charges once. Routing fails over on timeouts but never on declines. Refunds lock the payment so they can never exceed the charge, and every movement of money is an entry in an append-only ledger.
- "A Payment is a state machine
- with a table of legal moves.
- Requests carry idempotency
- keys; one putIfAbsent of a
- Future means a retry storm
- charges once. Routing fails over
- on timeouts, never on declines.
- Refunds lock the payment, and
- every movement is in a ledger."