CSE Roadmap

Core tier · about 5 hours · 8 parts

Part 3 of 8 · 2 min read

Pay-in

Parts and steps.

Parts.

  • Payment service: accepts payment events and coordinates everything. It first calls a risk check, which looks for fraud and breaks of anti-money-laundering rules. This is usually a third-party service.
  • Payment executor: executes one payment order through a PSP. One checkout may hold several orders, for example when items come from several sellers.
  • PSP: moves the money, and the card networks such as Visa and Mastercard are behind it.
  • Ledger: a permanent record of each transaction.
  • Wallet: the balance owed to each seller.

Steps.

  1. The user clicks "place order". A payment event goes to the payment service.
  2. The service saves the event.
  3. For each payment order inside the event, it calls the executor.
  4. The executor saves the order.
  5. The executor calls the PSP.
  6. When the PSP confirms, the payment service updates the seller's wallet.
  7. The wallet service saves the new balance.
  8. The payment service calls the ledger.
  9. The ledger appends a new entry.

API. POST /v1/payments carries a checkout id, a buyer reference, and a list of payment orders, each with a seller account, an amount, a currency and a payment order id that is globally unique. That id is also used as the idempotency key towards the PSP. GET /v1/payments/{id} returns the order's status.

Money is never a floating-point number. Computers store decimals like 0.1 in binary with small errors. In many languages, 0.1 + 0.2 gives 0.30000000000000004. Over millions of payments, small errors become real gaps. Different systems also round differently. So amounts are sent as strings and stored as whole integers of the smallest unit, such as cents, and parsed only when a calculation is needed.

Storage. Speed is not the main need. Pick a store with proven stability in finance, good tools, and a pool of experienced administrators. That points to a traditional relational database with ACID transactions (Level 5), not a newer NoSQL store.

Order status. A payment order moves through NOT_STARTED, EXECUTING, then SUCCESS or FAILED. After success, a wallet-updated flag and a ledger-updated flag are set. A scheduled job watches orders stuck in EXECUTING for too long and raises an alert.

A worked example (made up). A buyer pays $30 for items from two sellers: $20 and $10. That is one checkout with two payment orders. Each has its own id, so each is charged, tracked and retried on its own.

Common mistake

Storing money in a double or float. Rounding drift is silent and cannot be fixed afterwards. Use integer cents or a decimal type.

Check yourself: 1. What does the executor do that the payment service does not? 2. Why is the payment order id important? 3. Why not use floating-point for amounts?