Webhooks thanh toán

ModelMart nhận webhook từ SePay cho nạp tiền VND và từ Paddle cho nạp tiền quốc tế. Đây là các endpoint control plane, khác với endpoint model https://api.modelmart.ai/v1.

SePay

SePay gửi sự kiện tới webhook đã cấu hình trong tài khoản. Server phải xác minh checksum theo secret của SePay trước khi xử lý. Chỉ credit giao dịch khi chữ ký hợp lệ, mã giao dịch chưa xử lý, và số tiền khớp với topup đang chờ.

Paddle

Paddle gửi webhook có chữ ký trong header. Xác minh chữ ký bằng secret webhook Paddle trên raw request body trước khi parse JSON. Kiểm tra event ID để retry không tạo credit trùng.

Xử lý an toàn

nhận request
  -> đọc raw body và xác minh chữ ký
  -> kiểm tra event ID chưa xử lý
  -> đối chiếu số tiền, currency và topup reference
  -> ghi credit append-only vào ledger
  -> trả HTTP 2xx

Webhook phải được xử lý idempotent. Không tin số tiền hoặc trạng thái chỉ vì request đến từ mạng internet. Không log raw body, token chữ ký, hoặc thông tin thanh toán nhạy cảm.

Các route xem ví và hóa đơn nằm dưới /v2/wallet và /v2/invoices, có xác thực tenant. Webhook không được dùng để đọc dữ liệu của tenant khác.