Kiến trúc subscription billing cho SaaS sử dụng SePay

Bản chất của subscription trên SePay VietQR

SePay là cổng chuyển giao thanh toán ngân hàng trực tiếp qua chuẩn VietQR. Tuy nhiên, việc thu phí định kỳ cho SaaS (recurring billing) không đơn thuần là tạo một link thanh toán. Ứng dụng SaaS cần theo dõi chu kỳ gói, thời điểm bắt đầu/kết thúc kỳ, xử lý gia hạn và cấp quyền entitlement một cách nhất quán.

Ứng dụng của bạn → Customer → Product & ProductPrice
                 → Checkout (được gán provider_config_id) → SePay Launcher
                 ← Xác thực IPN (bằng chứng thanh toán) ← SePay Gateway
                 → Order → Subscription → BenefitGrant
                 → Signed Webhook → Kích hoạt quyền trong SaaS

Không nhầm lẫn redirect trình duyệt với bằng chứng thanh toán

Sau khi khách hàng chuyển khoản thành công trên SePay, trình duyệt có thể được chuyển hướng về success_url. Tuy nhiên, đây chỉ là trải nghiệm giao diện phía client (UX), tuyệt đối không được dùng làm căn cứ cấp quyền:

• Khách hàng có thể tắt tab ngay khi ứng dụng ngân hàng báo thành công trước khi trang web redirect.
• Trình duyệt hoặc mạng có thể bị gián đoạn, rớt kết nối.
• Tham số URL có thể bị sửa đổi trái phép ở client.

Chỉ có thông báo SePay IPN có chữ ký hợp lệ gửi trực tiếp đến webhook endpoint máy chủ, hoặc kết quả đối soát API xác thực mới được xem là bằng chứng hoàn tất thanh toán.

Mô hình gia hạn định kỳ không cần auto-debit

Các cổng thanh toán VietQR tại Việt Nam như SePay hoạt động theo hình thức chuyển khoản từng lần (one-time push payments) chứ không tự động trừ tiền trong thẻ (auto-debit). VietBilling giải quyết bài toán này qua mô hình gia hạn chủ động:

1. Chu kỳ đến hạn: Khi gói thuê bao gần hết hạn, hệ thống tự động sinh một đơn hàng gia hạn (Order loại subscription_cycle) và phiên Checkout tương ứng.
2. Gán cố định cấu hình cổng (Provider Pinning): Phiên checkout gia hạn luôn được gán cố định với đúng provider_config_id ban đầu của thuê bao, bảo đảm tiền về đúng tài khoản đối tác dù tổ chức có đổi cấu hình mặc định sau này.
3. Thông báo và Grace Period: Gửi link thanh toán gia hạn cho khách hàng và duy trì thời gian ân hạn (grace period) hợp lý trước khi khóa quyền.

curl -X POST "https://api.vietbilling.com/public/v2/checkouts" \
  -H "Authorization: Bearer vb_live_..." \
  -H "Idempotency-Key: chk_renewal_sub_789" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "c1000000-0000-0000-0000-000000000001",
    "product_id": "p1000000-0000-0000-0000-000000000001",
    "success_url": "https://app.example/billing/success",
    "cancel_url": "https://app.example/billing/cancel"
  }'

Đối soát tự động và khôi phục sự cố

Trong môi trường phân tán, webhook IPN có thể bị trễ hoặc nghẽn mạng. Hệ thống đối soát định kỳ (Reconciliation Worker) của VietBilling sẽ tự động rà soát các phiên Checkout đang chờ (open), truy vấn trạng thái đơn hàng trên SePay và cập nhật trạng thái thuê bao kịp thời, ngăn chặn việc gián đoạn dịch vụ của khách hàng.