Payment system basics

Imagine an ecommerce site. A customer sees a product that costs $100 and clicks Buy now.

Behind that one click, the request has to travel all the way to the customer's bank:

A large application like Amazon is split into many services, each with one job:

The payment service handles everything related to payments, for example:

• Create a payment
• Confirm a payment
• Track a payment
• Refund a payment
• Handle responses from the payment provider
• Store payment history
• Prevent duplicate charges

A payment service does not necessarily move money itself. Usually it talks to another company that processes the card, such as Stripe, PayPal or Braintree.

These companies go by several names: payment processor, payment service provider (PSP) or payment gateway. This note uses Stripe as the example.

Before the architecture, it helps to know who takes part. Imagine Nithin buys a laptop for $1,000. Several parties are involved:

The request travels from the customer to the issuing bank, and the answer travels back the same way:

Suppose a customer buys headphones for $100, enters their card details and clicks Pay. The frontend might send a request like this:

{
  "orderId": "123",
  "amount": 10000,
  "currency": "usd"
}

Notice the amount is 10000, not 100. Money is stored in the currency's smallest unit, and for USD that's cents: $100 = 10,000 cents. The last section explains why.

payment_id: "pay_123"
order_id:   "123"
amount:     10000
currency:   "usd"
status:     CREATED

A state machine is an object that can be in one of a fixed set of states, and moves between those states according to rules. It works much like a value held in React's useState, except only certain changes are allowed.

Think of a food delivery:

An order can't jump from Placed to Delivered, or go from Delivered back to Preparing. A payment works the same way. In its simplest form:

Real payment systems usually have more states:

Stripe already knows about the payment, so why store it again? When Stripe reports “Payment succeeded”, the application needs that fact itself so it can:

• Mark the order as paid
• Start shipping
• Send a receipt
• Show payment history
• Allow refunds
• Handle customer support
• Perform accounting

So the payment service keeps its own payment records, for example in a payments table:

id                   pay_123
order_id             order_456
user_id              user_789
amount               10000
currency             USD
status               SUCCEEDED
provider             STRIPE
provider_payment_id  pi_abc123
created_at           ...
updated_at           ...

Now the system knows what happened, even when customer support or reporting needs it later.

The short answer: avoid storing money as decimal (floating-point) numbers like 100.00. Store whole numbers of cents instead.

0.1 + 0.2          // 0.30000000000000004
0.1 + 0.2 === 0.3  // false

10000 + 5000 = 15000   // $100 + $50 = $150