Cheat sheet · Business processes
Payment gateway
The problem
A payer pays for an order through a gateway, and the gateway calls your shop four times. What each call means and where money or goods get lost.
What you learn
- The four calls: check, create, perform, cancel
- Why a repeated
CreateTransactionmust get the same answer - The transaction states
1,2,-1and-2 - Why goods leave only after
state: 2
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_payer(("Payer"))
n_gateway>"Gateway"]
n_api["Shop API"]
n_orders[("Orders DB")]
n_warehouse("Warehouse")
n_payer -->|"call"| n_gateway
n_gateway -->|"call"| n_api
n_api -->|"call"| n_orders
n_api -->|"call"| n_warehouseMermaid: request sequence
sequenceDiagram
participant n_gateway as Gateway
participant n_api as Shop API
participant n_orders as Orders DB
participant n_warehouse as Warehouse
Note over n_gateway,n_api: Check: can this order be paid?
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OK
Note over n_gateway,n_api: Create: a transaction is opened
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OK
Note over n_gateway,n_api: The same create arrives twice
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OK
Note over n_api,n_orders: A repeat gets the same answer
n_api->>n_orders: SELECT id, state, create_time FROM transactions
n_orders-->>n_api: tx_77 #124; 1 #124; 1795392843512
Note over n_gateway,n_api: Perform: the money is yours
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OK
Note over n_gateway,n_api: Goods left before the money
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OK
Note over n_api,n_warehouse: Ship only after state: 2
n_api->>n_warehouse: POST /shipments HTTP/1.1
n_warehouse-->>n_api: HTTP/1.1 201 Created
Note over n_gateway,n_api: Cancelling a paid transaction
n_gateway->>n_api: POST /merchant/rpc HTTP/1.1
n_api-->>n_gateway: HTTP/1.1 200 OKD2
direction: right
n_payer: "Payer" {
shape: person
}
n_gateway: "Gateway" {
shape: cloud
}
n_api: "Shop API" {
shape: rectangle
}
n_orders: "Orders DB" {
shape: cylinder
}
n_warehouse: "Warehouse" {
shape: rectangle
style.multiple: true
}
n_payer -> n_gateway: "call"
n_gateway -> n_api: "call"
n_api -> n_orders: "call"
n_api -> n_warehouse: "call"PlantUML: request sequence
@startuml
boundary "Gateway" as n_gateway
participant "Shop API" as n_api
database "Orders DB" as n_orders
participant "Warehouse" as n_warehouse
note over n_gateway, n_api : Check: can this order be paid?
n_gateway -> n_api : POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
note over n_gateway, n_api : Create: a transaction is opened
n_gateway -> n_api : POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
note over n_gateway, n_api : The same create arrives twice
n_gateway -> n_api : [duplicate] POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
note over n_api, n_orders : A repeat gets the same answer
n_api -> n_orders : SELECT id, state, create_time FROM transactions
n_orders --> n_api : tx_77 | 1 | 1795392843512
note over n_gateway, n_api : Perform: the money is yours
n_gateway -> n_api : POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
note over n_gateway, n_api : Goods left before the money
n_gateway -> n_api : POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
note over n_api, n_warehouse : Ship only after state: 2
n_api -> n_warehouse : POST /shipments HTTP/1.1
n_warehouse --> n_api : HTTP/1.1 201 Created
note over n_gateway, n_api : Cancelling a paid transaction
n_gateway -> n_api : POST /merchant/rpc HTTP/1.1
n_api --> n_gateway : HTTP/1.1 200 OK
@endumlPlantUML: components
@startuml
left to right direction
actor "Payer" as n_payer
cloud "Gateway" as n_gateway
component "Shop API" as n_api
database "Orders DB" as n_orders
collections "Warehouse" as n_warehouse
n_payer --> n_gateway : call
n_gateway --> n_api : call
n_api --> n_orders : call
n_api --> n_warehouse : call
@endumlRecap
Four rules for a payment gateway.
1) Amounts in the smallest unit, never floats. 2) Every call can repeat: look up the gateway ID and return the same answer. 3) Goods leave only after state: 2. 4) Cancel has two cases: -1 before the money, -2 after it.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Reply p95 | 120 ms | 140 ms |
| Double charges | 0/day | 0/day |
| Shipped unpaid | 0/day | 0/day |
Steps
- Case Check: can this order be paid?
The payer enters a card in the gateway.
- Case Create: a transaction is opened
The gateway now holds the money and tells your shop to open a transaction for the order.
- Problem The same create arrives twice
The API was slow, the gateway hit its timeout and sent
CreateTransactionagain with the sameid. - Fix A repeat gets the same answer
Before creating, the API looks up the gateway ID.
- Case Perform: the money is yours
The gateway charges the card and tells your shop to perform the transaction.
- Problem Goods left before the money
The shop handed the order to the warehouse as soon as the transaction was created.
- Fix Ship only after
state: 2The warehouse now gets an order only after
PerformTransaction. - Case Cancelling a paid transaction
The payer asks for a refund.
- Recap Recap
Four rules for a payment gateway.