Subscription billing architecture for SaaS products on SePay

Recurring billing reality with SePay VietQR

SePay provides direct bank transfers via dynamic VietQR codes. However, running a recurring SaaS business requires far more than one-off payment links: you need to track billing intervals, period start/end dates, renewal invoices, and entitlement synchronization across months.

Your SaaS application → Customer → Product & ProductPrice
                      → Checkout (pinned with provider_config_id) → SePay Launcher
                      ← Authenticated IPN proof ← SePay Gateway
                      → Order → Subscription → BenefitGrant
                      → Signed Webhook → Synchronized user entitlement

Never treat browser redirects as payment evidence

After completing a bank transfer on SePay, customers may be redirected to your success_url. This redirect is strictly a user-facing client experience, not cryptographic proof of payment:

• Customers frequently close browser tabs immediately upon banking app confirmation.
• Network glitches or client-side ad-blockers can interrupt redirect execution.
• Query parameters on the return URL can be manipulated on client devices.

Only an authenticated SePay IPN received on your server webhook endpoint—or an authoritative REST reconciliation check—constitutes verified payment proof.

Recurring renewals without card auto-debit

VietQR payments in Vietnam are inherently customer-initiated push payments, not automatic card charges. VietBilling manages this operational pattern through explicit renewal workflows:

1. Cycle maturity: When a subscription period approaches expiration, a renewal Order (subscription_cycle) and associated Checkout are scheduled automatically.
2. Provider Pinning: The renewal Checkout is strictly pinned to the subscription's original provider_config_id, guaranteeing settlements route to the exact merchant credentials regardless of current organization defaults.
3. Grace periods and reminders: Customers receive renewal payment links while access remains continuous throughout a configured grace period.

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"
  }'

Automated reconciliation and recovery

In production distributed systems, network drops and webhook retries occur. VietBilling's scheduled reconciliation workers query open Checkouts directly against SePay API, ensuring subscription statuses synchronize even during upstream webhook delivery outages.