Skip to content

Sequence Diagrams: SePay Payments (Donations and Premium)

1. Donation happy path (guest or user)

A visitor picks an amount, scans the VietQR, and the page flips to "thank you" once SePay reports the transfer.

sequenceDiagram
    autonumber
    actor U as Visitor
    participant FE as Browser (DonatePage.jsx / usePaymentOrder)
    participant PC as PaymentController
    participant PS as PaymentOrderServiceImpl
    participant DB as PostgreSQL
    participant Bank as Bank app
    participant SP as SePay
    participant WC as SepayWebhookController
    participant WS as SepayWebhookServiceImpl
    participant N as PaymentNotificationListener

    U->>FE: choose amount, optional name/message
    FE->>PC: POST /payments/orders {type: DONATION, amount}
    PC->>PS: createOrder() (@RateLimited)
    PS->>DB: insert payment_orders (code FMxxxxxxxx, PENDING, expires_at)
    PS-->>FE: {code, amount, bank info, qrUrl}
    FE-->>U: show VietQR + copy buttons
    loop every 3 s until PAID or expired
        FE->>PC: GET /payments/orders/{code}
        PC-->>FE: {status: PENDING}
    end
    U->>Bank: scan QR, transfer (memo = code)
    Bank-->>SP: incoming transfer on linked account
    SP->>WC: POST /webhooks/sepay (X-SePay-Signature, X-SePay-Timestamp)
    WC->>WS: verify HMAC(timestamp.rawBody), |now - ts| <= 300 s
    WS->>DB: insert sepay_transactions ON CONFLICT DO NOTHING
    WS->>DB: order.paid_amount += amount, status = PAID
    WC-->>SP: 200 {"success": true}
    WS-)N: PaymentPaidEvent (AFTER_COMMIT, @Async)
    N->>DB: upsert admin notification DONATION_RECEIVED
    FE->>PC: GET /payments/orders/{code}
    PC-->>FE: {status: PAID}
    FE-->>U: thank-you screen

2. Premium purchase, including underpaid

sequenceDiagram
    autonumber
    actor U as Logged-in user
    participant FE as Browser (PremiumPlans / usePaymentOrder)
    participant PC as PaymentController
    participant PS as PaymentOrderServiceImpl
    participant WS as SepayWebhookServiceImpl
    participant DB as PostgreSQL
    actor A as Admin

    U->>FE: pick plan (e.g. 12 months)
    FE->>PC: POST /payments/orders {type: PREMIUM, planId} (JWT)
    PC->>PS: createOrder() — 401 if guest, 400 if plan inactive
    PS->>DB: insert order (expected_amount = plan.price)
    PS-->>FE: {code, amount, qrUrl}
    Note over U,WS: user transfers, webhook arrives as in flow 1
    WS->>DB: paid_amount += amount
    alt paid_amount >= expected_amount
        WS->>DB: status = PAID, users.premium_until = max(now, premium_until) + days
        Note right of WS: surplus = paid - expected, shown in admin tab
    else paid_amount < expected_amount
        WS->>DB: status = UNDERPAID
        WS-)A: notification PAYMENT_UNDERPAID
        A->>PC: POST /admin/payments/orders/{id}/resolve {grantPremium: true|false}
        PC->>DB: status = RESOLVED (+ premium extension if granted)
    end
    FE->>PC: GET /auth/me
    PC-->>FE: {premium: true, premiumUntil}

3. Webhook rejection and edge cases

sequenceDiagram
    autonumber
    participant SP as SePay (or attacker)
    participant WC as SepayWebhookController
    participant WS as SepayWebhookServiceImpl
    participant DB as PostgreSQL

    SP->>WC: POST /webhooks/sepay
    alt secret not configured
        WC-->>SP: 503
    else body > 64 KiB
        WC-->>SP: 413
    else bad signature or stale timestamp
        WC-->>SP: 401 (fixed log line, no payload logged)
    else duplicate sepay id (retry / replay)
        WS->>DB: insert … ON CONFLICT DO NOTHING (0 rows)
        WC-->>SP: 200 {"success": true} (no-op)
    else transferType = out
        WS->>DB: insert match_status = IGNORED
        WC-->>SP: 200 {"success": true}
    else no code / unknown code / CANCELLED order
        WS->>DB: insert match_status = UNMATCHED
        WC-->>SP: 200 {"success": true}
    end

4. Reconciliation job (missed webhooks)

sequenceDiagram
    autonumber
    participant J as AppScheduler reconcile-sepay (daily 00:15, day T-1)
    participant R as SepayReconcileServiceImpl
    participant API as SePay userapi v2
    participant WS as SepayWebhookServiceImpl
    participant DB as PostgreSQL

    J->>R: reconcile() at 00:15 Asia/Ho_Chi_Minh
    alt Harness flag sepay_reconcile_enabled off, or no API token
        R-->>J: return, no call
    end
    Note over R: day = yesterday (T-1): from yesterday 00:00 to today 00:00, bank time
    loop pages until has_more = false (max 10, 400 ms apart)
        R->>API: GET /v2/transactions?q=FM&transfer_type=in&transaction_date_from=yesterday 00:00 (Bearer token)
        API-->>R: data[], meta.pagination
    end
    Note over R: keep rows dated yesterday with an FM code (rows from today wait for tomorrow)<br/>webhook_success = 1 counts as webhook, the rest get a negative sepay_id from their UUID
    R->>DB: which sepay_ids are already stored
    loop each row not stored yet
        R->>WS: process(tx, source = RECONCILE), same path as webhook
        WS->>DB: skip if same reference + amount already stored, else insert ON CONFLICT DO NOTHING and match
    end
    alt 401 / 429 / 5xx / bad body
        Note over R: stop paging, result = api_error (Run now in the admin Jobs tab the same day reruns T-1)
    end
    R->>R: log INFO "SePay reconcile run: day, result, total, webhook, reconciled, already, failed"
    Note over R: Grafana Business Stats, row SePay Reconcile, reads this line<br/>total = webhook + reconciled + already + failed

4b. Admin checks one order on SePay

sequenceDiagram
    autonumber
    participant A as AdminPaymentsTab (row menu)
    participant C as AdminPaymentController
    participant S as AdminPaymentServiceImpl
    participant R as SepayReconcileServiceImpl
    participant API as SePay userapi v2
    participant WS as SepayWebhookServiceImpl

    A->>C: POST /admin/payments/orders/{id}/check-sepay
    C->>S: checkOrderOnSepay(id), PENDING / EXPIRED / UNDERPAID only
    S->>R: checkCode(order code, order createdAt)
    R->>API: GET /v2/transactions?q=FMXXXXXXXX&transfer_type=in&transaction_date_from=createdAt-1h
    API-->>R: data[]
    loop rows with this code and webhook_success != 1, not stored yet
        R->>WS: process(tx, source = RECONCILE)
    end
    R-->>S: found, processed
    S-->>A: found, processed, order as it is now
    alt no API token
        S-->>A: 503
    else SePay error (401 / 429 / down)
        S-->>A: 502
    end

5. Order expiry job

sequenceDiagram
    autonumber
    participant J as AppScheduler (every 15 min)
    participant PS as PaymentOrderServiceImpl
    participant DB as PostgreSQL
    J->>PS: expireStaleOrders()
    PS->>DB: UPDATE payment_orders SET status = EXPIRED WHERE status = PENDING AND expires_at < now()
    Note over PS,DB: a late transfer still matches an EXPIRED order (money received) and moves it to PAID / UNDERPAID