Nạp tiền QR qua SePay & idempotency

Khách đã đăng nhập được rồi, giờ tới phần họ mong nhất ở một web bán hàng có ví: nạp tiền để mua. Khoá cho khách nạp bằng cách quét mã QR chuyển khoản qua SePay - tiện và quen với người Việt.

Một lần nạp đi qua bốn nhịp. Mèo con không tự viết phần khó; hiểu luồng để mô tả đúng cho Claude và kiểm lại:

• ▸1. Tạo yêu cầu nạp: khách nhập số tiền, app tạo một giao dịch trạng thái "chờ".
• ▸2. Hiện QR: app hiển thị mã QR SePay để khách quét và chuyển khoản.
• ▸3. SePay phát hiện tiền về: khi tiền vào tài khoản, SePay gửi webhook báo cho app.
• ▸4. Cộng số dư: app nhận webhook, xác nhận hợp lệ rồi cộng tiền vào ví khách.

Làm sao app biết khách đã chuyển khoản? Không phải ngồi hỏi SePay liên tục. Thay vào đó SePay chủ động gọi tới một địa chỉ (URL) của app khi có tiền về - cú gọi đó gọi là webhook. App có một endpoint nghe webhook này, đọc thông tin (ai nạp, bao nhiêu, mã giao dịch) rồi xử lý.

Đây là chỗ dễ vấp nhất. Webhook có thể bị gửi nhiều lần cho cùng một lần chuyển khoản: mạng chập chờn, hoặc SePay không nhận được phản hồi nên tự thử lại. Nếu mỗi lần nhận webhook app đều cộng tiền, khách nạp một lần mà số dư nhảy hai, ba lần - sai tiền.

Lời giải là idempotency: xử lý cùng một giao dịch bao nhiêu lần thì kết quả vẫn như xử lý một lần. App kiểm mã giao dịch trước khi cộng:

Mấu chốt: mỗi giao dịch có một mã định danh duy nhất từ SePay. Lưu mã đó vào bảng giao dịch và đặt ràng buộc UNIQUE - để database tự chặn bản trùng. Trước khi cộng, app kiểm đã có mã này chưa:

# nhận webhook: tiền về, mã giao dịch = ma_gd
if da_co(ma_gd):          # đã xử lý rồi
    return "ok"           # bỏ qua, KHÔNG cộng lại
luu(ma_gd)                # cột ma_gd là UNIQUE -> chốt ở database
cong_so_du(nguoi_dung, so_tien)
danh_dau_hoan_tat(ma_gd)

• ▸Mã giao dịch duy nhất + ràng buộc UNIQUE trên database = không lọt bản trùng.
• ▸Kiểm "đã xử lý chưa" trước khi cộng; rồi thì bỏ qua.
• ▸Trạng thái giao dịch rõ ràng: chờ → hoàn tất, để dễ lần lại khi cần.

Một rủi ro nữa: nếu app cộng tiền cho bất kỳ webhook nào gọi tới, kẻ xấu chỉ cần gọi webhook giả là tự bơm số dư. Phải xác thực webhook đúng là từ SePay - qua chữ ký hoặc secret do SePay cấp. Webhook không hợp lệ thì từ chối, không cộng đồng nào.

Idempotency lo "không cộng trùng". Nhưng còn một ca khó hơn: khách chuyển khoản TAY và gõ sai hoặc thiếu nội dung nạp. Tiền về tài khoản SePay, webhook báo, nhưng app không biết cộng cho ai vì thiếu mã tham chiếu khớp tài khoản.

Tuyệt đối không lờ đi hay nuốt khoản này - khách mất tiền mà không được cộng sẽ tố lừa đảo. Cách làm đúng:

• ▸Phòng từ gốc: mỗi yêu cầu nạp sinh một MÃ THAM CHIẾU duy nhất; QR điền sẵn nội dung + số tiền để khách khỏi gõ tay.
• ▸Webhook khớp được tài khoản → cộng đúng khách; KHÔNG khớp → đưa vào "tiền treo", KHÔNG bỏ qua.
• ▸Admin đối chiếu (số tiền, người gửi, thời gian) rồi khớp tay cho đúng khách, hoặc hoàn tiền nếu không xác minh được.
• ▸Mọi xử lý tiền treo GHI LOG (audit); đối soát ở báo cáo sẽ thấy các khoản treo.

SePay nhận chuyển khoản/QR và gửi webhook xác nhận - vừa đủ cho phần nạp tiền của khoá. Mèo con tạo tài khoản SePay, lấy thông tin kết nối (khoá API, địa chỉ webhook) đặt vào .env, rồi mô tả cho Claude gắn vào app.