mufassall

Cheat sheet · Business processes

Payment gateway

14 min · Intermediate · mufassall.dtwin.uz/en/l/payments/

← Open the lesson

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 CreateTransaction must get the same answer
  • The transaction states 1, 2, -1 and -2
  • Why goods leave only after state: 2
Final scene

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_warehouse

Mermaid: 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 OK

D2

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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Reply p95120 ms140 ms
Double charges0/day0/day
Shipped unpaid0/day0/day

Steps

  1. Case Check: can this order be paid?

    The payer enters a card in the gateway.

  2. Case Create: a transaction is opened

    The gateway now holds the money and tells your shop to open a transaction for the order.

  3. Problem The same create arrives twice

    The API was slow, the gateway hit its timeout and sent CreateTransaction again with the same id.

  4. Fix A repeat gets the same answer

    Before creating, the API looks up the gateway ID.

  5. Case Perform: the money is yours

    The gateway charges the card and tells your shop to perform the transaction.

  6. Problem Goods left before the money

    The shop handed the order to the warehouse as soon as the transaction was created.

  7. Fix Ship only after state: 2

    The warehouse now gets an order only after PerformTransaction.

  8. Case Cancelling a paid transaction

    The payer asks for a refund.

  9. Recap Recap

    Four rules for a payment gateway.