1) Mục tiêu thiết kế

  • Đa phương thức: thẻ (Visa/Master/JCB), chuyển khoản/QR, ví điện tử, COD, BNPL.
  • An toàn: tuân thủ PCI DSS, mã hóa end-to-end, tokenization, chống gian lận.
  • Tin cậy: idempotency, retry có kiểm soát, trạng thái thanh toán rõ ràng.
  • Mở rộng: cắm thêm cổng mới không ảnh hưởng nghiệp vụ cũ.
  • Hoàn tiền/đối soát: minh bạch, tự động, dễ tra soát.

2) Kiến trúc tổng quan

[Client: Web/App]
      ↓ (BFF)
[Checkout API]──┐
                ├──> [Payment Orchestrator] ──> [Gateway Adapters: Stripe/VNPay/MoMo/...] 
                │                                  │
                │                                  └─> [Acquirer/Bank/PSP]
                │
                ├──> [Fraud Service]  (risk scoring, rules, ML)
                ├──> [Order Service]  (đồng bộ trạng thái)
                └──> [Ledger/Settlement] (bút toán & đối soát)
                        │
                        └──> [Accounting/BI]
Ý tưởng chính
  • Payment Orchestrator: lớp điều phối trung tâm, giữ logic chung (create payment, authorize, capture, refund, void, webhook processing, retries, idempotency).
  • Gateway Adapters: mỗi cổng là 1 adapter theo interface thống nhất → thay/đổi cổng dễ dàng.
  • Fraud Service: chấm điểm rủi ro trước khi authorize/capture.
  • Ledger/Settlement: ghi bút toán nội bộ + job đối soát với sao kê nhà cung cấp.

3) Các khái niệm & trạng thái quan trọng

Luồng chuẩn thẻ/PSP (2-phase)
Authorization: ngân hàng chặn hạn mức (hold) nhưng chưa trừ tiền.
Capture: xác nhận thu tiền (toàn phần/1 phần).
Void: hủy lệnh đã authorize (khi chưa capture).
Refund: hoàn tiền (full/partial) sau khi capture.
Trạng thái Payment (nên chuẩn hóa)
created → pending → authorized → captured → refunded / voided / failed / expired
Idempotency
Mọi API ghi (/create, /capture, /refund) cần Idempotency-Key để chống double charge khi retry do mạng.

4) Thiết kế API/Domain

4.1 Payment API (gợi ý)

POST /payments → tạo payment intent (amount, currency, method, order_id)
POST /payments/{id}/authorize
POST /payments/{id}/capture (support partial)
POST /payments/{id}/void
POST /payments/{id}/refund (support partial)
POST /webhooks/{gateway} → nhận callback trạng thái
Tất cả hỗ trợ header Idempotency-Key.

4.2 Mô hình dữ liệu (rút gọn)

payment
payment_id, order_id, amount, currency, status
method (card, qr, wallet, cod, bnpl)
gateway (stripe, vnpay, momo…)
customer_id, risk_score, created_at, updated_at
payment_transaction
tx_id, payment_id, type (authorize/capture/refund/void)
amount, gateway_status, error_code, raw_payload, created_at
payment_method_token
token (PAN tokenized), brand, exp_last4, bin, fingerprint, customer_id
ledger_entry
entry_id, payment_id, direction (debit/credit), amount, account_code, value_date

5) Orchestration & Gateway Adapters

Orchestrator làm gì?
  • Ánh xạ trạng thái nội bộ ↔ trạng thái cổng.
  • Kết hợp Fraud check trước khi authorize/capture.
  • Quản lý retry theo ma trận lỗi (network vs business).
  • Xử lý webhook: xác minh chữ ký, idempotent update, publish event PaymentUpdated.
    Adapter tiêu chuẩn
Interface: authorize(), capture(), void(), refund(), parseWebhook().
Chuẩn hóa lỗi (e.g., INSUFFICIENT_FUNDS, DO_NOT_HONOR, CARD_EXPIRED).
Cấu hình qua feature flags để bật/tắt nhanh theo thị trường.

6) Chống gian lận (Fraud)

6.1 Tầng luật (Rules)

Từ chối nếu: IP proxy/TOR, BIN rủi ro, thẻ quốc gia A mua ship quốc gia B bất thường, nhiều lần fail trong 5 phút, basket giá trị lớn + địa chỉ lạ…
Velocity limits: số lần authorize theo card fingerprint / email / IP.

6.2 Điểm rủi ro (Risk Scoring)

Tính điểm theo đặc trưng: lịch sử khách, tần suất đổi địa chỉ, Thời điểm (00–05h), thiết bị mới, mismatch AVS/CVV (nếu có).
Ngưỡng: score < 40 → pass, 40–70 → review, >70 → reject (ví dụ).

6.3 ML/Graph

Sử dụng mô hình học máy hoặc liên kết đồ thị (email-card-device-address) để phát hiện cụm gian lận.

6.4 3DS/OTP & Step-up

Kích hoạt 3-D Secure / OTP với giao dịch rủi ro cao.
Giảm ma sát bằng cách chỉ step-up khi cần (risk-based authentication).

7) Bảo mật & Tuân thủ

PCI DSS: tránh chạm PAN thô; nếu bắt buộc, cô lập payment vault và scope PCI thật nhỏ.
Tokenization: thay PAN bằng token (từ cổng hoặc tự vận hành vault).
TLS 1.2+, HSTS, mã hóa dữ liệu nhạy cảm at-rest.
Webhook signing + IP allowlist của PSP.
P2PE (Point-to-Point Encryption) nếu có POS.
Log/trace: ghi đủ để audit nhưng không log dữ liệu thẻ.

8) Hoàn tiền (Refund), Hủy (Void) & Đối soát (Settlement)

8.1 Nguyên tắc

Void khi chưa capture (hết phí MDR); Refund khi đã capture (có thể mất phí).
Partial refund hỗ trợ trả từng dòng hàng.
Mọi thao tác sinh payment_transaction + ledger_entry tương ứng.

8.2 Đối soát

Cron/Batch lấy payout report từ cổng → so khớp captured – refund – fee – payout.
Sai lệch → vào reconciliation_diff để tra soát thủ công.
Khuyến nghị có báo cáo D+1 (ngày T+1) cho tài chính.

9) Độ tin cậy: Retry, Timeouts, Concurrency

Đặt timeout ngắn phía client, dài hơn phía server ↔ PSP.
Retry có backoff chỉ cho lỗi mạng/timeout; không retry lỗi business.
Idempotency ở mọi API ghi + dedupe webhook theo event_id.
Outbox pattern cho event PaymentUpdated bảo đảm “exactly-once to consumers”.
Circuit breaker cho từng cổng; fallback sang cổng khác nếu ridge load.

10) UX/Chuyển đổi (Conversion)

BFF chọn phương thức theo ngữ cảnh: thẻ quốc tế, QR nội địa, ví phổ biến theo thị trường.
One-click / Card-on-file với token (và 3DS exemption khi hợp lệ).
SCA/3DS tối ưu: chỉ step-up khi risk cao để tránh rớt đơn.
Error messaging rõ ràng + gợi ý thay phương thức khác ngay.

11) Checklist triển khai nhanh

Orchestrator + Adapters theo interface chung
Idempotency-Key toàn bộ API ghi
Webhook verify signature + dedupe
Ledger/Settlement & báo cáo D+1
Fraud: rules + velocity + (tùy chọn) ML
Tokenization + scope PCI tối thiểu
Quy trình Refund/Void/Chargeback rõ ràng
Observability: metrics (auth rate, capture rate, refund rate), traces, alert

12) Kết luận

Một hệ thống thanh toán tốt không chỉ “thu tiền” mà còn:
  • Dễ cắm thêm phương thức mới,
  • An toàn, chống gian lận,
  • Minh bạch hoàn tiền/đối soát,
  • Tối ưu chuyển đổi với trải nghiệm mượt mà.
Lời khuyên: bắt đầu với 1–2 cổng chủ lực + Orchestrator chuẩn hóa, sau đó mở rộng dần phương thức theo thị trường và dữ liệu conversion thực tế.