FE: module payments — thu tiền người mua (ADR-0051) #

Phần chung (khởi tạo client, lỗi, danh sách, ngôn ngữ) ở tài liệu FE của Core: docs/fe/common.md (bản đọc: xforge-documentation, ADR-0102 của xforge-core). Sửa file này CÙNG PR khi đổi hành vi FE thấy được của module.

Store nhận tiền bằng tài khoản SePay / MoMo CỦA CHÍNH STORE.

• Cấu hình (admin store, core.manage_settings): setConfig mã payments.sepay (enabled, webhookKey bí mật ≥ 16 ký tự, bankBin / bankAccount / bankHolder cho VietQR) và payments.momo (enabled, partnerCode, accessKey, secretKey bí mật, endpoint sandbox / production, requestType, returnUrl có {id}). Màn cấu hình hiện URL từ getPaymentWebhookUrls() để admin dán vào SePay (null = server chưa đặt PUBLIC_API_URL).
• Nhân viên (payments.read / payments.write / payments.reconcile): createPaymentIntent({ body: { amount, description?, referenceType?, referenceId?, expiresInMinutes? } }) → code (nội dung chuyển khoản), transfer (ngân hàng
  • qrUrl VietQR, null khi chưa cấu hình / không còn chờ), momo (có trả bằng MoMo được không). Chỉ VND. Danh sách listPaymentIntents (lọc status, reference_type, reference_id), cancelPaymentIntent, createPaymentIntentMomoCheckout (→ payUrl / deeplink / qrCodeUrl). Hàng chờ đối soát: listPaymentTransactions({ query: { status: "unmatched" } }) → unmatchedReason (no_code, underpaid, not_payable…) → khớp tay matchPaymentTransaction({ params: { id }, body: { intentId } }) hoặc ignorePaymentTransaction. IPN MoMo thất lạc: queryPaymentIntentMomo({ params: { id } }).
• Tiền vào hàng chờ đối soát: thông báo payments.unmatched (kèm Web Push) cho người có payments.reconcile: link.key = payments.payments, link.id = id giao dịch, tham số amount, currency, provider; đến trễ vài giây. Topic payments.unmatched (người có payments.read, docs/fe/cms.md §6), data: { transactionId }: màn hàng chờ đang mở đọc lại listPaymentTransactions. Cổng gửi lại giao dịch đã ghi thì không báo lần hai.
• Người mua (storefront, không cần đăng nhập): FE gửi link chứa id + code; trang trả tiền gọi getStorefrontPaymentIntent({ params: { id }, query: { code } }) để hiện số tiền, QR chuyển khoản (nội dung = code, đừng cho sửa) và nút MoMo (createStorefrontPaymentMomoCheckout({ params: { id }, body: { code } }) → chuyển tới payUrl). Hỏi lại (poll vài giây) tới khi status = paid; expired / cancelled → báo hết hạn. Trả thiếu / chuyển sai nội dung → vẫn pending, nhân viên đối soát.
• Tắt payments ở cửa hàng (màn "Module của cửa hàng", docs/fe/cms.md §3.2 của Core): store còn ý định pending, hoặc ý định mới hết hạn chưa quá 24 giờ (chuyển khoản trễ) → 409 payment_intents_pending (details.count) — tắt lúc này thì cổng gọi về bị từ chối, tiền khách đã trả không được ghi nhận (kể cả chuyển khoản tự do không gắn ý định). Hiện message. Người có payments.read / payments.write: gợi ý mở listPaymentIntents({ query: { status: "pending" } }) và huỷ bằng cancelPaymentIntent; thiếu quyền thì chỉ hiện message (đừng dẫn tới màn sẽ 403). details.count (tối đa 1000 — hiện "1000+") gồm cả ý định mới hết hạn và có thể lệch danh sách tới ~1 phút (việc định kỳ đánh dấu hết hạn chạy mỗi 60 giây). Kiểm tra này không bảo đảm tuyệt đối (ý định tạo đúng lúc tắt vẫn lọt): hướng dẫn người dùng tắt các module tạo ý định (checkout, order…) TRƯỚC, đợi hết ý định chờ, rồi mới tắt payments.