Improve Stripe payment provider logic #505

FranjoMindek · 2025-09-17T08:16:12Z

Description

Fixes #487

The PR idea was to research stripe payment provider to see If we could optimize our current stripe integration.

For implementation, my main idea was to simplify webhook handling logic and reduce the number of events we have to handle. Secondary idea was to make it easier for users to work with our stripe integration.

The simplification is done through:

We now generate Stripe.Invoice for one-time payments (this is a opt-in setting).
- This allows us to handle both one-time payments and subscriptions under the invoice.paid event. So we can stop handling checkout.session.completed event, which we handled to update ONLY one-time payments related data.
- As a nice side-effect users can how see their one-time payment invoices in their stripe customer portal
I've refactored stripe customer postal to be generated by API on per-custmer basis rather than using public customer portal link
- This is how we do it for lemon squeezy, and it makes sense for already logged-in users (you are automatically logged in into your payment provider customer profile, instead of having to login via magic link)
I've deleted webhookPayload.ts which included payload parsing schema. This is because we already verify the payload via stripe's signature (constructEvent func), and the type system allows us to navigate the data.

Other changes:

Naming changes
I tried to remove all uselss try/catch blocks
- This is mostly console.log(error); throw error; situations

FranjoMindek · 2025-09-17T08:19:15Z

opensaas-sh/blog/public/llms-full.txt


 ## What's inside?

 The template itself is built on top of some very powerful tools and frameworks, including:


This hasn't been run in a while so more changes pop up.

FranjoMindek · 2025-09-17T08:20:57Z

template/app/src/payment/plans.ts

    effect: { kind: 'credits', amount: 10 },
  },
-};
+} as const satisfies Record<PaymentPlanId, PaymentPlan>;


Allows us to do e.g. paymentPlans.credits10.effect.amount which would throw before.

template/app/src/shared/utils.ts

template/app/src/payment/stripe/stripeClient.ts

Copilot

Pull Request Overview

This PR simplifies and hardens the Stripe integration by moving from custom Zod parsing to Stripe’s typed events, shifting one-time payments to be invoice-driven, and generating customer-portal sessions per user instead of relying on a static URL.

Switch webhook processing to use Stripe typed events; remove custom webhookPayload parsing.
Enable invoices for one-time payments and handle credits via invoice.paid.
Introduce stripeClient with explicit API version; generate customer-portal session URLs server-side.

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
template/app/src/shared/utils.ts	Minor cleanup: unused param naming for assertUnreachable.
template/app/src/payment/stripe/webhookPayload.ts	Removed custom Zod-based webhook parsing in favor of Stripe types.
template/app/src/payment/stripe/webhook.ts	Rewrote webhook handling to use Stripe typed events; added invoice-driven flows and helper extractors.
template/app/src/payment/stripe/stripeClient.ts	Introduced stripeClient with centralized API version constant and docs.
template/app/src/payment/stripe/paymentProcessor.ts	Generate billing portal sessions per user; ensure Stripe customer creation; minor API refinements.
template/app/src/payment/stripe/paymentDetails.ts	Split update into one-time vs subscription paths; updated shapes and fields.
template/app/src/payment/stripe/checkoutUtils.ts	Ensure/create Stripe customer; enable invoice creation for one-time checkouts; align with stripeClient.
template/app/src/payment/plans.ts	Strengthened typing for paymentPlans using satisfies and as const.
template/app/src/analytics/stats.ts	Switched to stripeClient usage for listing balance transactions.
template/app/.env.server.example	Removed obsolete STRIPE_CUSTOMER_PORTAL_URL.
opensaas-sh/blog/src/content/docs/guides/payments-integration.mdx	Updated docs to reflect customer-portal and customer creation changes.
opensaas-sh/blog/public/llms.txt	Added a new docs link.
opensaas-sh/blog/public/llms-full.txt	Multiple doc updates; links and guidance refreshed.
.github/workflows/e2e-tests.yml	Removed obsolete STRIPE_CUSTOMER_PORTAL_URL from CI env.
opensaas-sh/app_diff/*	App-diff adjustments mirroring template changes (not core template code).

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

template/app/src/payment/stripe/webhook.ts

opensaas-sh/blog/public/llms-full.txt

opensaas-sh/blog/src/content/docs/guides/payments-integration.mdx

opensaas-sh/blog/public/llms-full.txt

FranjoMindek · 2025-09-21T07:27:22Z

template/app/src/payment/stripe/checkoutUtils.ts

+ * Returns a Stripe customer for the given User email, creating a customer if none exist.
+ * Implements email uniqueness logic since Stripe doesn't enforce unique emails.
+ */
+export async function ensureStripeCustomer(userEmail: string): Promise<Stripe.Customer> {


Old name fetchStripeCustomer lied, because it also created a customer if none existed.

FranjoMindek · 2025-09-21T07:31:05Z

template/app/src/payment/stripe/checkoutUtils.ts

-  priceId: string;
-  customerId: string;
-  mode: StripeMode;
+  priceId: Stripe.Price['id'];


I try to extract types from stripe as much as I can.
If I miss it anywhere it is a mistake.

# Conflicts: # template/app/src/payment/stripe/checkoutUtils.ts

# Conflicts: # opensaas-sh/app_diff/src/analytics/stats.ts.diff # opensaas-sh/app_diff/src/payment/stripe/paymentDetails.ts.diff # opensaas-sh/app_diff/src/payment/stripe/paymentProcessor.ts.diff # template/app/src/analytics/stats.ts # template/app/src/payment/stripe/checkoutUtils.ts # template/app/src/payment/stripe/paymentDetails.ts # template/app/src/payment/stripe/paymentProcessor.ts # template/app/src/payment/stripe/stripeClient.ts # template/app/src/payment/stripe/webhook.ts # template/app/src/payment/stripe/webhookPayload.ts # template/app/src/shared/utils.ts

…e-payment-provider # Conflicts: # opensaas-sh/blog/src/content/docs/blog/2024-12-10-turboreel-os-ai-video-generator-built-with-open-saas.mdx

# Conflicts: # opensaas-sh/blog/public/llms-full.txt

Copilot

Pull Request Overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

template/app/src/payment/stripe/checkoutUtils.ts

…e-payment-provider

FranjoMindek · 2025-10-13T08:15:17Z

template/e2e-tests/package.json

    "e2e:playwright": "DEBUG=pw:webserver npx playwright test",
    "local:e2e:cleanup-stripe": "PID=$(ps -ef | grep 'stripe listen' | grep -v grep | awk '{print $2}') || true && kill -9 $PID || true",
-    "local:e2e:playwright:ui": "npx playwright test --ui",
+    "local:e2e:playwright:ui": "SKIP_EMAIL_VERIFICATION_IN_DEV=true npx playwright test --ui",


Explore: how come we don't set this by default inside of wasp-app-runner if we depend on it?

Why did I add this? Did I do something wrong?

FranjoMindek · 2025-10-13T08:16:57Z

template/app/src/payment/stripe/checkoutUtils.ts

-      customer_update: {
-        address: "auto",
+}: CreateStripeCheckoutSessionParams): Promise<Stripe.Checkout.Session> {
+  // WASP_WEB_CLIENT_URL will be set up by Wasp when deploying to production: https://wasp.sh/docs/deploying


Reminder to create a issue about solving the env vars situation on open-saas.
Use Wass's defineEnvValidationSchema.
Centralize them in a single place.

Stripe only changes

809e982

FranjoMindek commented Sep 17, 2025

View reviewed changes

template/app/src/shared/utils.ts Show resolved Hide resolved

FranjoMindek mentioned this pull request Sep 17, 2025

Stripe and payment processing improvements #493

Closed

FranjoMindek self-assigned this Sep 17, 2025

FranjoMindek added 2 commits September 17, 2025 16:58

changes

3df17a2

further improvements

d0a2e15

FranjoMindek commented Sep 18, 2025

View reviewed changes

template/app/src/payment/stripe/stripeClient.ts Show resolved Hide resolved

FranjoMindek requested a review from Copilot September 20, 2025 06:15

Copilot AI reviewed Sep 20, 2025

View reviewed changes

FranjoMindek commented Sep 21, 2025

View reviewed changes

FranjoMindek added 17 commits September 21, 2025 09:33

remove typ catch

1560833

split payment details funcs

fec25ab

add awaits

05b0fad

name

91e2f0d

Merge branch 'main' into franjo/refactor-stripe-payment-provider

de70c30

# Conflicts: # template/app/src/payment/stripe/checkoutUtils.ts

formatting

0cbe24c

fix format

5dce0da

update

4d6a64f

map to switch

1541759

wording

dddc128

fix typo

d7b5f8f

format

d6a608a

fix diffs?

346da0f

Merge remote-tracking branch 'origin/main' into franjo/refactor-strip…

4d9fb58

…e-payment-provider # Conflicts: # opensaas-sh/blog/src/content/docs/blog/2024-12-10-turboreel-os-ai-video-generator-built-with-open-saas.mdx

docs: update LLM files after documentation changes

8371bd4

comments

e5caba8

FranjoMindek added 4 commits October 1, 2025 11:25

wording

2e5ea07

wording

f09865f

wording

b4f80d3

Merge branch 'main' into franjo/refactor-stripe-payment-provider

2c82386

# Conflicts: # opensaas-sh/blog/public/llms-full.txt

FranjoMindek requested a review from Copilot October 1, 2025 09:33

Copilot AI reviewed Oct 1, 2025

View reviewed changes

template/app/src/payment/stripe/checkoutUtils.ts Outdated Show resolved Hide resolved

fix typo

34209ae

FranjoMindek marked this pull request as ready for review October 1, 2025 09:49

FranjoMindek added 5 commits October 1, 2025 13:09

to 204

f288f9b

Merge remote-tracking branch 'origin/main' into franjo/refactor-strip…

0bd0b73

…e-payment-provider

Merge remote-tracking branch 'origin/main' into franjo/refactor-strip…

375cf1a

…e-payment-provider

update env

4673ec6

formatting

fb0ff94

FranjoMindek commented Oct 13, 2025

View reviewed changes

FranjoMindek requested a review from infomiho October 13, 2025 08:17


		## What's inside?

		The template itself is built on top of some very powerful tools and frameworks, including:

Uh oh!

Improve Stripe payment provider logic #505

Are you sure you want to change the base?

Improve Stripe payment provider logic #505

Uh oh!

Conversation

FranjoMindek commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

FranjoMindek Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FranjoMindek Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Sep 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

FranjoMindek Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

FranjoMindek commented Sep 17, 2025 •

edited

Loading

FranjoMindek Sep 17, 2025 •

edited

Loading

FranjoMindek Sep 21, 2025 •

edited

Loading

FranjoMindek Oct 13, 2025 •

edited

Loading

FranjoMindek Oct 13, 2025 •

edited

Loading