Designing A Payment & OTP Verification Gateway (Idempotency + Fraud Detection)

1) Problem Clarification / Làm rõ bài toán

EN

We need to design a system that:

issues OTP codes
verifies them
processes payments
prevents duplicate payment processing
identifies suspect/fraud behavior

VI

Thiết kế hệ thống:

sinh OTP
verify OTP
xử lý thanh toán
đảm bảo không xử lý trùng (idempotency)
phát hiện fraud

2) Requirements Definition / Yêu cầu hệ thống

EN – Functional Requirements

✔ Generate OTP
✔ Validate OTP with expiration
✔ Process payment safely
✔ Strong idempotency guarantee
✔ Retry-safe handling
✔ Fraud monitoring and rule engine
✔ Audit trail

VI – Chức năng

✔ sinh OTP
✔ verify OTP + thời hạn
✔ xử lý thanh toán an toàn
✔ idempotency mạnh
✔ retry không gây double-charge
✔ phát hiện fraud
✔ audit logging

EN – Non-functional

✔ low latency (<250ms)
✔ extremely high reliability
✔ ACID behavior for financial data
✔ defense against brute-force attacks

VI – Phi chức năng

✔ latency thấp (<250ms)
✔ reliability cao
✔ hành vi ACID cho tiền
✔ chống brute-force OTP

3) High-Level Architecture / Kiến trúc tổng quan

Client → API Gateway → OTP Service → Payment Service → Ledger DB
                         ↓                  ↓
                   Redis Store         Fraud Engine

4) OTP Generation & Storage / Sinh OTP & lưu trữ

EN

We generate:

random numeric/alpha code
hashed using HMAC or bcrypt
stored with TTL in Redis

Schema:

otp:<user> {
   hashed_value,
   expire_at,
   failed_attempts
}

VI

OTP được sinh:

số hoặc ký tự ngẫu nhiên
hash (HMAC/bcrypt)
lưu Redis có TTL

5) OTP Validation / Verify OTP

EN

Validation steps:

retrieve hashed OTP
compare hash
increment failed attempts
lockout rule if exceed attempts
success clears key

VI

Luồng verify:

lấy hash OTP từ Redis
so sánh hash
tăng failed attempts
khóa nếu vượt số lần sai
thành công thì xoá key

6) Payment Processing Model / Mô hình xử lý thanh toán

EN

Must satisfy:

exactly-once execution
idempotency

=> Use request idempotency key

payment_idempotency:<txn_id> = status + result

If repeated request arrives → return stored result instead of charging again.

VI

Thanh toán cần:

thực thi đúng 1 lần
idempotency

→ Dùng idempotency key theo transaction:

payment_idempotency:<txn_id>

Nếu request lặp lại → trả về kết quả cũ, không thực thi nữa.

7) Ledger-Based Accounting / Sổ cái kế toán

EN

Financial systems need double-entry ledger:

account A - debit 100
account B - credit 100

Ledger table ensures atomicity & reversibility.

VI

Thanh toán phải có ledger (ghi nợ / ghi có) đảm bảo:

tính đúng
rollback được

8) Fraud Detection Engine / Phát hiện gian lận

EN

Inputs:

failed OTP attempts
unusual payment velocity
device fingerprint mismatch
geo anomalies
blacklists

Technique:

rules engine
scoring model
queue to manual review

VI

Fraud dựa trên:

OTP sai nhiều lần
tốc độ thanh toán bất thường
mismatch thiết bị
anomaly vị trí
blacklist

Giải pháp:

rule engine
scoring
queue để manual review

9) Retry & Failure Handling / Retry và xử lý lỗi

EN

Payment must be retry-safe:

client retry request → return last result based on idempotency key
background retries on gateway failures
compensation transaction on double debit scenario

VI

Retry phải an toàn:

client gửi lại → trả kết quả cũ
retry ngầm nếu call gateway fail
có transaction bù (compensation) nếu sai

10) Secure Design / Thiết kế bảo mật

EN

OTP hashing (never store plaintext)
rate limiting OTP verify
token-binding for device
encryption in DB (pan masking)

VI

hash OTP (không store plain)
giới hạn verify OTP
token bind device
mã hóa dữ liệu nhạy cảm

11) Observability / Giám sát

EN

Metrics:

OTP failure rate
fraud suspicion rate
idempotency hit ratio
payment latency
ledger reconciliation mismatch

VI