Make Payment Side Effects Reliable via Webhooks and Unify Stripe Flows

[ygrishajev]

Context

The current Stripe payment integration has grown organically, resulting in multiple inconsistent patterns for handling payments, coupons, and card validation. The client performs work that should be the backend's responsibility — polling for balance changes, confirming 3DS results, marking payment methods as validated. This RFC proposes unifying all payment flows behind a consistent pattern using webhooks and a single transaction-awaiting endpoint.

---

Current State

Aspect	Payment	Coupon	Card Validation
Transaction record	Yes	Yes	No
How client resolves	Balance polling (2s × 15)	Balance polling (2s × 15)	Inline / retry after 3DS
3DS handling	Client calls /payment-methods/validate	N/A	Client calls /payment-methods/validate + retries createWallet
Side effects run in	Webhook	Webhook	Inline API handler
Stripe API used	paymentIntents.create	Invoice with discount	paymentIntents.create (capture: "manual")

Payment Flow (with optional 3DS)

sequenceDiagram
    participant Client
    participant API
    participant Stripe
    participant Webhook

    Client->>API: POST /v1/stripe/transactions/confirm
    API->>API: Create transaction record (DB)
    API->>Stripe: paymentIntents.create(confirm: true)
    Stripe-->>API: PaymentIntent (succeeded | requires_action)

    alt No 3DS required
        API-->>Client: { success: true, transactionId }
        Client->>Client: Start balance polling (2s interval, 30s max)
        Stripe->>Webhook: payment_intent.succeeded
        Webhook->>API: Update transaction → "succeeded"
        Webhook->>API: Top up wallet
        Client->>Client: Detect balance increase → stop polling
    else 3DS required
        API-->>Client: { requiresAction: true, clientSecret, paymentIntentId }
        Client->>Stripe: stripe.confirmCardPayment(clientSecret)
        Stripe-->>Client: 3DS authentication result
        Client->>API: POST /v1/stripe/payment-methods/validate (mark as validated)
        API-->>Client: { success: true }
        Client->>Client: Start balance polling (2s interval, 30s max)
        Stripe->>Webhook: payment_intent.succeeded
        Webhook->>API: Update transaction → "succeeded"
        Webhook->>API: Top up wallet
        Client->>Client: Detect balance increase → stop polling
    end

Loading

Coupon Flow

sequenceDiagram
    participant Client
    participant API
    participant Stripe
    participant Webhook

    Client->>API: POST /v1/stripe/coupons/apply
    API->>API: Create transaction record (DB)
    API->>Stripe: Create invoice with discount
    Stripe-->>API: Invoice finalized
    API-->>Client: { coupon, amountAdded, transactionId }
    Client->>Client: Start balance polling (2s interval, 30s max)
    Stripe->>Webhook: invoice.payment_succeeded
    Webhook->>API: Update transaction → "succeeded"
    Webhook->>API: Top up wallet
    Client->>Client: Detect balance increase → stop polling

Loading

Card Validation / Onboarding Flow (with optional 3DS)

sequenceDiagram
    participant Client
    participant API
    participant Stripe
    participant Webhook

    Client->>API: POST /v1/start-trial (createWallet)
    API->>API: No transaction record created
    API->>Stripe: paymentIntents.create($1, capture: manual)
    Stripe-->>API: PaymentIntent (requires_capture | requires_action)

    alt No 3DS required
        API->>API: markPaymentMethodAsValidated()
        API->>API: initializeAndGrantTrialLimits()
        API-->>Client: { wallet data }
    else 3DS required
        API-->>Client: { requires3DS: true, clientSecret, paymentIntentId }
        Client->>Stripe: stripe.confirmCardPayment(clientSecret)
        Stripe-->>Client: 3DS authentication result
        Client->>API: POST /v1/stripe/payment-methods/validate
        API->>Stripe: Retrieve PaymentIntent, check status
        API->>API: markPaymentMethodAsValidated()
        API-->>Client: { success: true }
        Client->>Client: Refetch payment methods
        Client->>API: POST /v1/start-trial (retry createWallet)
        API->>API: initializeAndGrantTrialLimits()
        API-->>Client: { wallet data }
    end

Loading

---

Problems

1. Three different resolution mechanisms

Flow	How client knows it's done
Payment (no 3DS)	Balance polling via PaymentPollingProvider (2s × 15 attempts)
Payment (3DS)	Call validatePaymentMethodAfter3DS, then balance polling
Coupon	Balance polling via PaymentPollingProvider
Validation (no 3DS)	Inline — createWallet returns synchronously
Validation (3DS)	Call validatePaymentMethodAfter3DS, refetch methods, retry createWallet

There's no unified way for the client to say "wait for this payment action to complete."

2. Client performs backend responsibilities

• PaymentPollingProvider — 80+ lines of React context with refs, timeouts, and effects to poll wallet balance every 2 seconds. This "is the payment done yet?" logic belongs on the backend.
• validatePaymentMethodAfter3DS — after 3DS, the client explicitly tells the backend to check the PaymentIntent and mark the payment method. The payment_intent.succeeded webhook could do this automatically.
• use3DSecure hook — mixes UI state management (open/close popup) with backend mutation calls. Two concerns in one.

3. Card validation has no audit trail

createTestCharge creates a Stripe PaymentIntent but stores no transaction record in the DB. If validation fails or behaves unexpectedly, there's zero visibility. Meanwhile, createPaymentIntent (for real payments) stores a full transaction record. These two methods do nearly the same thing at the Stripe API level — the only real difference is capture_method: "manual".

4. Webhook explicitly skips validation intents

In stripe-webhook.service.ts:109-115:

if (paymentIntent.metadata.type === "payment_method_validation") {
  return; // skip
}

This forces the client to handle the validation marking via a separate API call. If the webhook processed these intents, the client wouldn't need to.

5. Two nearly-identical PaymentIntent creation methods

createPaymentIntent and createTestCharge in stripe.service.ts both create Stripe PaymentIntents. Differences:

Aspect	createPaymentIntent	createTestCharge
Transaction record	Yes	No
capture_method	automatic	"manual"
Amount	Variable	Hardcoded $1
On success	Update transaction status	markPaymentMethodAsValidated()
Payment methods config	automatic_payment_methods	payment_method_types: ["card", "link"]
Idempotency	Optional, caller-provided	Hardcoded per customer+method

These could be a single method with a captureMethod parameter.

---

Proposed Design

Core idea

1. Every payment action returns a transactionId — payment, coupon, and card validation all create transaction records
2. One endpoint to await results: GET /v1/stripe/transactions/:id?awaitStatus=succeeded — holds the request until the transaction reaches the requested status or times out
3. Webhooks handle all side effects — wallet top-up, payment method validation marking, transaction status updates
4. Client never polls, never confirms — just calls the mutation, handles 3DS if needed, then awaits the transaction

Unified Payment Flow (all types)

sequenceDiagram
    participant Client
    participant API
    participant Stripe
    participant Webhook

    Client->>API: POST mutation endpoint (payment / coupon / validation)
    API->>API: Create transaction record (DB)
    API->>Stripe: Create PaymentIntent / Invoice
    Stripe-->>API: Result
    API-->>Client: { transactionId, requires3DS?, clientSecret? }

    opt 3DS required
        Client->>Stripe: stripe.confirmCardPayment(clientSecret)
        Stripe-->>Client: Authentication result
    end

    Client->>API: GET /v1/stripe/transactions/:id?awaitStatus=succeeded
    Note over API: Holds request, polls DB every 500ms (60s timeout)

    Stripe->>Webhook: payment_intent.succeeded / invoice.payment_succeeded
    Webhook->>API: Update transaction → "succeeded"
    Webhook->>API: Side effects (top up wallet / mark payment method)

    API-->>Client: { status: "succeeded", ... }
    Client->>Client: Show success, refresh UI

Loading

What changes

Backend:

• New GET /v1/stripe/transactions/:id endpoint with optional ?awaitStatus query param
• Merge createTestCharge into createPaymentIntent (add captureMethod param, always create transaction)
• Webhook processes payment_method_validation intents instead of skipping them (marks payment method as validated)
• Remove validatePaymentMethodAfter3DS method and /v1/stripe/payment-methods/validate route
• Remove awaitResolved from confirm/coupon endpoints (superseded by the GET endpoint with ?awaitStatus)

Client:

• Delete PaymentPollingProvider entirely (~230 lines)
• Simplify use3DSecure to pure UI state (remove backend mutation call)
• Remove validatePaymentMethodAfter3DS from usePaymentMutations
• Add simple awaitTransaction(id) call — just a GET request
• All flows (payment.tsx, PaymentPopup.tsx, PaymentMethodContainer.tsx) follow the same 3-step pattern

Benefits

• Consistent client pattern — every flow: mutate → (optional 3DS) → await transaction
• ~300 lines of client code removed — polling provider, 3DS backend calls, per-flow resolution logic
• Audit trail for card validation — validation charges get transaction records like everything else
• Single source of truth — webhook handles all side effects; client just observes final state
• More reliable — all payment side effects (wallet top-up, payment method validation) run in webhooks, which benefit from Stripe's built-in retry and recovery mechanisms. If the server is temporarily down, Stripe will redeliver the event — unlike inline API handling where a failure means the side effect is lost
• Simpler debugging — every payment action has a transaction ID you can trace end-to-end

[stalniy]

I have a concern about awaiting tx status update on API side:

It's a long-polling, which keeps an HTTP connection open. If it times out, the client still needs to retry, so it can end up similar to short polling on the client side (just with a different retry conditions). However, long polling could be replaced with SSE/Websocket notification then in combination with Postgres LISTEN/NOTIFY (which has a nice interface provided by postgres.js) api won't need to poll the database but instead listen for notification broadcasted from /stripe-webhook and then forward it to corresponding SSE/Websocket connection. This is probably better for scaling but may be harder/longer to implement.

Overall, I really like the idea of routing all payments through a single, consistent flow. It is a big win! Great job!

[ygrishajev]

it is not done yet, i'm trying to plan it out ;)

on the client we gotta stop polling at some point too

[ygrishajev]

however, I think ws/server events is the right way. Let's plan this feature including that. It doesn't have to happen full scope

[baktun14]

I like the idea of homogenizing the transaction process, well done! I mostly reponsible for all of this, so thanks for initiating this refactor.