A simple payment architecture

1.Why the amount isn't in the request

Never trust the client. Anything the browser sends can be edited before it leaves the customer's computer. If the request carried the amount, a malicious user could change it:

So the payment service gets the trusted amount from the order service, or other trusted backend data:

1.The order is created

The order service creates the order:

order_id: order_555
amount:   150000
currency: USD
status:   PENDING_PAYMENT

2.The customer clicks Pay

The frontend sends only the order ID:

{
  "orderId": "order_555"
}

3.Verify the order

The payment service asks the order service for order_555, and gets back the trusted amount:

{
  "id": "order_555",
  "amount": 150000,
  "currency": "USD",
  "status": "PENDING_PAYMENT"
}

4.Create the payment

The payment service saves a new payment:

payment_id: pay_999
order_id:   order_555
amount:     150000
currency:   USD
status:     CREATED

5.Charge through Stripe

The status moves to PROCESSING, and the payment service asks Stripe to process the payment. Stripe returns success.

6.Mark it paid

The payment service updates the status to SUCCEEDED, and the order service marks the order PAID.

1.A crash after the charge

Consider this sequence:

1. The customer clicks Pay.
2. The payment service sends the request to Stripe.
3. Stripe charges the card successfully.
4. Stripe sends back a success response.
5. The payment service crashes before saving SUCCEEDED.

Now the two sides disagree:

This is an inconsistent state, and it's a fundamental distributed systems problem. Charging through Stripe and updating the database are two separate operations, and there's no way to make them one.

2.Why a database transaction doesn't help

If everything lived inside PostgreSQL, a transaction would make both updates happen together, or neither:

BEGIN;
UPDATE payments ...;
UPDATE orders ...;
COMMIT;

But Stripe is an external service, outside the database. There is no ordinary transaction like this:

BEGIN;
Charge the card through Stripe and Visa
UPDATE payments ...;
COMMIT;

That's why distributed systems are hard:

• Network calls can fail
• Servers can crash
• Responses can be lost
• Requests can be repeated

3.Duplicate clicks

The customer clicks Pay, and nothing happens for two seconds. Thinking it didn't work, they click again. The frontend sends two requests for the same $100 order:

Preventing this leads to one of the most important concepts in payment system design: idempotency.

1.Idempotency keys

A common solution is an idempotency key. The frontend creates a unique identifier for the checkout attempt, like checkout_order_123_attempt_1, or more commonly a UUID, and sends it with the request:

POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

The payment service saves the key with the payment:

payment_id:      pay_123
idempotency_key: 550e8400...
status:          SUCCEEDED

If a request arrives with the same key, the payment service finds it in the database: this was already processed. Instead of charging again, it returns the previous result.

2.The flow

1.The fix: a unique constraint

Let the database enforce it. A unique constraint on the key means only one row with abc123 can ever exist:

UNIQUE (idempotency_key)

Now the insert itself is the check, and the database lets only one request win: