Payment — Kiến trúc & dữ liệu

Checkout flow chung

Method-specific flows

Method	Flow
PayLater	Validate availability, persist pending/selected option, cho flow booking/subscription tiếp tục.
PayNow/Windcave	Init checkout, redirect customer, nhận result/webhook, chống retry duplicate.
Direct Debit/Kiwi	Tạo hoặc đọc payment customer theo account+BU+provider, tạo batch debit, xử lý provider status.
Deposit	Kiểm tra eligibility toàn batch, snapshot amount/percentage, lock order, provider checkout, webhook confirm.

Zero-amount checkout

• Bypass provider ở mọi method khi tổng = 0; không tạo session/hpp/redirect.
• Intent auto-confirm phải đến từ authoritative payment state, không từ display text/payable amount.

Windcave integration mode

• Mode XML (legacy/PxPay) vs REST; lưu theo từng business unit payment setting.
• Giá trị null/missing hoặc BU đã có Windcave → resolve XML; không cần can thiệp vận hành.
• Mọi thao tác Windcave (init checkout, callback/result parsing, verification/query, scheduler recovery, test connection) branch theo mode đã lưu.
• Test Connection chỉ validate protocol đang active; không phụ thuộc account/payer setup.
• REST (/api/v1/sessions) chỉ dùng khi mode REST; gọi IHttpClientFactory cho mọi outbound REST.
• REST mode: session chưa có transaction (processing) → log rõ + mark batch Declined, không map Unknown.

Ví dụ thực tế: BU mới bật Windcave nhưng chưa chọn mode. → Không làm hỏng checkout cũ. → Mode resolve XML, checkout tiếp tục qua PxPay như cũ.

Guardrails

• Mọi access tới AccountPaymentCustomer phải scope theo BU; cross-BU là lỗi bảo mật.
• Provider webhook/result phải idempotent vì provider có thể gọi lại nhiều lần.
• Master toggle/payment settings phải được kiểm tra trước khi expose method ở UI.
• Deposit eligibility phải fail cả batch nếu một booking không đủ điều kiện.
• Controller chỉ orchestration; logic nghiệp vụ nằm ở service/domain boundary.

Dữ liệu chính

Nhóm	Dữ liệu
Customer token	AccountPaymentCustomer theo account, BU, provider.
Payment batch	DirectPaymentBatch, DirectPayment, status/error/provider reference.
Checkout lock	Booking/order lock hoặc deposit snapshot để chống double submit.
Settings	BU/provider settings, method toggle, category availability.
Provider callbacks	Result URL, notification URL, webhook payload/error.