Nhận IPN/webhook SePay và đẩy realtime trạng thái thanh toán

Feature URL

Module

payment

Status

in-development

Priority

Platforms

fe · be

AC progress

17 / 19

Last reviewed

2026-05-29

Mục tiêu

Tách riêng các public callback từ SePay thành một mục Payment độc lập: IPN checkout form và bank-transfer webhook của QR top-up. Khi callback xác nhận thanh toán thành công, backend cập nhật PaymentOrder, cộng V-Credits idempotent và đẩy realtime status tới owner qua WebSocket để màn chờ thanh toán cập nhật nhanh.

Phạm vi

Trong phạm vi (In scope):

Public IPN checkout endpoint POST /payments/sepay/ipn.
Public IPN alias POST /v1/payments/sepay/ipn.
Public bank-transfer webhook endpoint POST /payments/sepay/webhook.
Public webhook alias POST /v1/payments/sepay/webhook.
Verify IPN secret qua header X-Secret-Key.
Verify bank-transfer webhook bằng SEPAY_WEBHOOK_AUTH_MODE: none, api_key, hoặc hmac.
Match payment order bằng invoice/order id của IPN hoặc payload.code của webhook.
Validate provider status, transaction type và amount trước khi confirm order.
Publish PaymentOrderConfirmedEvent khi order chuyển SUCCESS.
Push PaymentOrderRealtimePayload tới owner qua /user/queue/payment-orders sau transaction commit.

Ngoài phạm vi (Out of scope):

Tạo checkout top-up, xem feature wallet-topup-create.
Tạo QR top-up và nội dung chuyển khoản, xem feature wallet-topup-sepay-qr-webhook.
API user chủ động sync detail, xem feature payment-order-detail-sync.
Hạ tầng STOMP/WebSocket nền tảng, xem system doc WebSocket / STOMP.
UI ví/nạp tiền hoàn chỉnh trên frontend.

User Stories

Là hệ thống payment, tôi muốn xử lý IPN/webhook từ SePay để xác nhận order đã thanh toán.
Là user đang chờ nạp tiền, tôi muốn màn hình nhận realtime status khi thanh toán thành công thay vì phải polling liên tục.
Là hệ thống ví, tôi muốn chỉ cộng V-Credits sau khi callback match đúng order và amount.
Là ops/support, tôi muốn callback lặp hoặc callback không match order không cộng ví sai và vẫn ACK đúng cho provider khi phù hợp.

Luồng chức năng

sequenceDiagram
    actor User
    participant App as FE/Mobile
    participant SePay
    participant BE
    participant Wallet
    participant WS as WebSocket

    Note over User,SePay: IPN checkout form
    User->>SePay: Hoàn tất checkout
    SePay->>BE: POST /payments/sepay/ipn
    BE->>BE: Verify X-Secret-Key + invoice number
    BE->>SePay: Query order detail
    BE->>BE: Validate invoice, amount, status CAPTURED
    BE->>Wallet: Confirm payment order, cộng V-Credits idempotent
    BE->>BE: Publish PaymentOrderConfirmedEvent
    WS-->>App: MESSAGE /user/queue/payment-orders
    BE-->>SePay: {"success": true}

    Note over User,SePay: Bank-transfer QR webhook
    User->>SePay: Chuyển khoản QR đúng nội dung
    SePay->>BE: POST /payments/sepay/webhook
    BE->>BE: Verify HMAC/API key theo config
    BE->>BE: Match payload.code với providerOrderId
    BE->>BE: Validate transferType=in + amount khớp
    BE->>Wallet: Confirm payment order, cộng V-Credits idempotent
    BE->>BE: Publish PaymentOrderConfirmedEvent
    WS-->>App: MESSAGE /user/queue/payment-orders
    BE-->>SePay: {"success": true}

Acceptance Criteria

Quy tắc nghiệp vụ

Callback từ SePay là server-to-server, không yêu cầu Bearer token.
IPN checkout và bank-transfer webhook cùng dùng confirm path; ví chỉ được cộng khi order local còn xử lý được.
PaymentOrder.providerOrderId là khóa đối soát chính với SePay.
Cộng V-Credits phải idempotent theo payment order.
WebSocket chỉ là tín hiệu realtime sau commit; DB/REST API vẫn là nguồn sự thật.
Client không được tự cộng số dư chỉ dựa trên WebSocket payload; phải reconcile order/wallet state bằng REST.
Local/dev có thể tắt webhook auth bằng SEPAY_WEBHOOK_AUTH_MODE=none; test/prod nên dùng HMAC hoặc API key.

Dữ liệu & Trạng thái

Entity nghiệp vụ:

PaymentOrder: order local chứa owner, amount, providerOrderId, status, paidAt, ipnData, histories.
PaymentProviderOrderState: snapshot provider detail dùng cho IPN checkout.
SepayWebhookPayload: bank-transfer webhook payload gồm code, transferType, transferAmount, transaction id.
WalletTransaction: ledger ví được tạo khi order confirm thành công.
PaymentOrderConfirmedEvent: event sau khi order được xác nhận thanh toán.
PaymentOrderRealtimePayload: payload realtime gửi tới owner.

Trạng thái user-facing:

CREATED — order đang chờ callback hoặc detail sync.
SUCCESS — callback hợp lệ đã xác nhận thanh toán và ví đã cộng credit.
REALTIME_NOTIFIED — client đã nhận WebSocket event và nên refresh order/wallet.
CANCELLED — provider hoặc user đã huỷ.
EXPIRED — order quá hạn, không nên xử lý tự động.
FAILED — order lỗi, không cộng credit.

Endpoint BE hiện có:

POST /api/payments/sepay/ipn
POST /api/v1/payments/sepay/ipn
POST /api/payments/sepay/webhook
POST /api/v1/payments/sepay/webhook
WebSocket destination client subscribe: /user/queue/payment-orders

Liên quan

Phụ thuộc: wallet-topup-create, wallet-topup-sepay-qr-webhook
Ảnh hưởng: payment-order-detail-sync, wallet-topup-create, wallet-topup-sepay-qr-webhook