Stripe login and payment flow

This guide describes how a logged-in end user completes a Stripe purchase when your client uses the Vimond Default Payment Provider. It complements the platform Payment guide (product groups and orders on the Vimond REST API) by focusing on the payment-provider service and Stripe.js. For the Vipps redirect-based flow, see Vipps login and payment flow.

Typical components:

Role	Responsibility
Client app	Login (OIDC/JWT), checkout UI, Stripe Elements, confirmCardPayment
Default Payment Provider	Customer/payment-method APIs, checkout, webhook verification, agreements and charges
Stripe	Payment methods, subscriptions, payment intents, webhooks

API contracts: Default Payment Provider — Stripe Checkout, Stripe Webhooks, Customer · compact OpenAPI index

Prerequisites: End-user authentication. For subscription concepts after purchase, see SVOD.

Simplified flow (high-level)

What happens in plain language

1. User logs in in the web app and gets a JWT.
2. Web app fetches saved payment methods from backend.
3. User checks out with Stripe card flow.
4. Backend creates Stripe subscription/payment intent and returns clientSecret.
5. Frontend confirms payment with Stripe (confirmCardPayment).
6. Stripe sends webhooks to backend.
7. Backend updates agreements, charges, and entitlements.

Sequence flow (implementation-oriented)

Note: The client confirms payment for UX; webhooks finalize agreement and charge records. Do not treat a successful confirmCardPayment alone as subscription activation.

Stripe SVOD sequence (detailed)

Client confirms payment; durable state is driven by webhooks.

Stripe SVOD sequence (swim lanes)

Stripe SVOD subscription state machine

Webhook events with dedicated handlers

Stripe event	Handler	Main effect
customer.subscription.created	StripeSubscriptionCreatedHandler	Draft agreement
invoice_payment.paid	StripeInvoicePaymentPaidHandler	Persist charge; redeem voucher on first charge
customer.subscription.updated	StripeSubscriptionUpdatedHandler	Route by status strategy
invoice.paid	StripeInvoicePaidHandler	SVOD receipt
customer.subscription.deleted	StripeSubscriptionDeletedHandler	End agreement, release voucher if needed

StripeEventType also lists charge, payment_intent, checkout.session, and invoice failure events — some are observability-only or TVOD-specific.

Webhook entry points:

• POST /api/v1/webhook/stripe/ — shared tenant mode (preferred; resolves tenancy from Stripe account)
• POST /api/v1/webhook/stripe/{organization} — organization-scoped variant

All Stripe webhooks require a valid Stripe-Signature header.

Key backend endpoints

Endpoint	Purpose
POST /api/v1/pay/stripe/checkout	Create SVOD subscription; returns clientSecret
POST /api/v1/pay/stripe/tvod	Create TVOD payment intent
GET /api/v1/customer/paymentMethods	List saved payment methods
PUT /api/v1/customer	Update customer / default payment method
POST /api/v1/webhook/stripe/	Stripe webhook receiver

Key frontend interactions

• Fetch methods: getCustomerPaymentMethods(...)
• Checkout calls: createStripeSubscription(...), createStripeTVOD(...)
• Payment confirmation: stripe.confirmCardPayment(...)

Notes

• Backend is the source of truth for final state via Stripe webhooks.
• Frontend handles immediate UX, but webhook processing finalizes durable agreement and charge state.

Related guides

• Payment — product groups, orders, and REST API purchase flow
• SVOD — viewing and managing subscriptions after purchase
• TVOD — transactional purchases
• Auto-renew subscriptions — renewal behaviour