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

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

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.

Nice change!

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

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?

The idea of wasp-app-runner is to run the app and not concern itself with env variables. This was suggested by @sodic and accepted by me so it's following more the Unix philosophy of simple tools doing a single job. That's why the wasp-app-runner "only" runs Wasp apps.

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.

this one already exists here #483

@FranjoMindek you can use the env object here instead of going for process.env. The env object has the http://localhost:3000/ as the default value: https://wasp.sh/docs/project/env-vars#server-env-vars

I just realized the docs don't say this:

Made an issue for this: wasp-lang/wasp#3294

infomiho

Good stuff @FranjoMindek

I think there is one "big" question to disucss - do we keep the Zod schemas for parsing the payload in the name of uniformity?

Testing it locally

Running it locally with the opensaas.sh got me this error when running wasp db migrate-dev, maybe there is a migration missing?

[  Wasp  ] src/payment/stripe/paymentProcessor.ts(64,9): error TS2353: Object literal may only specify known properties, and 'paymentProcessorUserId' does not exist in type 'UserSelect<DefaultArgs>'.
[  Wasp  ] src/payment/stripe/paymentProcessor.ts(68,15): error TS2339: Property 'paymentProcessorUserId' does not exist on type '{ id: string; createdAt: Date; email: string | null; username: string | null; isAdmin: boolean; isMockUser: boolean; stripeId: string | null; subscriptionStatus: string | null; subscriptionPlan: string | null; datePaid: Date | null; credits: number; }'.
[  Wasp  ] src/payment/stripe/paymentProcessor.ts(73,22): error TS2339: Property 'paymentProcessorUserId' does not exist on type '{ id: string; createdAt: Date; email: string | null; username: string | null; isAdmin: boolean; isMockUser: boolean; stripeId: string | null; subscriptionStatus: string | null; subscriptionPlan: string | null; datePaid: Date | null; credits: number; }'.

opensaas-sh/blog/src/content/docs/guides/deploying.mdx

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

infomiho · 2025-11-04T10:09:35Z

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


@FranjoMindek you can use the env object here instead of going for process.env. The env object has the http://localhost:3000/ as the default value: https://wasp.sh/docs/project/env-vars#server-env-vars

I just realized the docs don't say this:

Made an issue for this: wasp-lang/wasp#3294

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

infomiho · 2025-11-04T11:11:39Z

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

-}
+  const priceId = invoiceLineItems[0].pricing?.price_details?.price;
+  if (!priceId) {
+    throw new Error("Unable to extract price id from items");


Nipick: Earlier we threw HttpError in this fn - do we want to use it for this throw as well?

I researched a bit and HttpError is Wasp error which we use when we want to provide additional data to the web client. Webhook events are not relayed to the web client in any way. So I would maybe remove all notion of HttpError as not to confuse people with it.

Does that make sense to you?

when we want to provide additional data to the web client

There is one more use case, if you check how it's handled in our server code:

if (err instanceof HttpError) { return res.status(err.statusCode).json({ message: err.message, data: err.data }) }

You'll notice it gives you control over the error code as well on the server. Also, it enables you to send some message in the error response vs. just 500 https://github.com/wasp-lang/wasp/blob/main/waspc/data/Generator/templates/server/src/app.js#L16

If you feel like we shouldn't send any extra info (status code, message) that's also fine 👍

I guess that would be valid for self-documentation reasons.

Stripe only recognizes if its 2XX status code or anything else.
400 and 500 make no difference to it.

I'm fine with just Error here, if you are also, you can resolve, otherwise comment.

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

Co-authored-by: Mihovil Ilakovac <[email protected]>

…-lang/open-saas into franjo/refactor-stripe-payment-provider

FranjoMindek · 2025-11-04T19:44:51Z

Running it locally with the opensaas.sh got me this error when running wasp db migrate-dev, maybe there is a migration missing?

It seems like I need to update the opensaas-sh/app_diff, because we don't have paymentProcessorUserId field in there, we have stripeId instead. Don't know how it disappeared from diffs where necessary.

edit: Should be fixed now.

…e-payment-provider

infomiho

Left some more comments

infomiho · 2025-11-10T10:46:44Z

opensaas-sh/app_diff/src/client/Main.css.diff

@@ -1,6 +1,6 @@
 --- template/app/src/client/Main.css


How come we have these changes in this PR?

Should we maybe do a separate PR that only updates the diffs?

Yep, this often happens.
We should have a CI workflow for this.

template/app/src/payment/paymentProcessor.ts

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

infomiho · 2025-11-10T10:57:03Z

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

-}
+  const priceId = invoiceLineItems[0].pricing?.price_details?.price;
+  if (!priceId) {
+    throw new Error("Unable to extract price id from items");


when we want to provide additional data to the web client

There is one more use case, if you check how it's handled in our server code:

if (err instanceof HttpError) { return res.status(err.statusCode).json({ message: err.message, data: err.data }) }

You'll notice it gives you control over the error code as well on the server. Also, it enables you to send some message in the error response vs. just 500 https://github.com/wasp-lang/wasp/blob/main/waspc/data/Generator/templates/server/src/app.js#L16

If you feel like we shouldn't send any extra info (status code, message) that's also fine 👍

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

infomiho · 2025-11-10T11:00:57Z

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

+      if (process.env.NODE_ENV === "development") {
+        console.info("Unhandled Stripe webhook event in development: ", error);
+      } else if (process.env.NODE_ENV === "production") {
+        console.error("Unhandled Stripe webhook event in production: ", error);


I'm afraid this might go unnoticed in the logs. But I guess, if you search for the event name - it will appear. How does this error look like in the logs now?

Currently it logs the error itself, so it's pretty noticeable.
Maybe even tone it down for development?

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

infomiho · 2025-11-10T11:04:53Z

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

+function getOpenSaasSubscriptionStatus(
+  subscription: Stripe.Subscription,
+): SubscriptionStatus | undefined {
  let subscriptionStatus: SubscriptionStatus | undefined;


Why not return right away vs. using a let and returning at the end?

I just extracted the logic out, didn't improve it, my bad.

Stripe only changes

809e982

FranjoMindek commented Sep 17, 2025

View reviewed changes

opensaas-sh/blog/public/llms-full.txt Outdated Show resolved Hide resolved

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 2 commits October 11, 2025 15:44

update env

4673ec6

formatting

fb0ff94

FranjoMindek commented Oct 13, 2025

View reviewed changes

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

infomiho reviewed Nov 4, 2025

View reviewed changes

FranjoMindek and others added 8 commits November 4, 2025 14:19

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

1adc2d0

work

cd0988e

Update opensaas-sh/blog/src/content/docs/guides/deploying.mdx

a86021d

Co-authored-by: Mihovil Ilakovac <[email protected]>

Apply suggestion from @infomiho

68220cc

Co-authored-by: Mihovil Ilakovac <[email protected]>

Apply suggestion from @infomiho

ddbe28e

Co-authored-by: Mihovil Ilakovac <[email protected]>

link change

9a4ea86

Merge branch 'franjo/refactor-stripe-payment-provider' of franjo:wasp…

76b9a32

…-lang/open-saas into franjo/refactor-stripe-payment-provider

rename

5441ffc

FranjoMindek added 9 commits November 4, 2025 20:53

changes

4088bca

capitalize

2262a2c

fix trailing slash bug, formatting

5fab9a3

update diff

ae1b458

abstract more user stuff, move to user.ts, fixes

8b649e0

diff

17586a7

fix diffs

631f237

env to config

b9c8304

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

221a549

…e-payment-provider

infomiho reviewed Nov 10, 2025

View reviewed changes

FranjoMindek added 4 commits November 10, 2025 22:08

user import

39381df

move jsdoc to comment + simplify logic

99f01ad

simplify

0e17428

improve opensaas map

6928c60

FranjoMindek requested a review from infomiho November 10, 2025 21:32

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!

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!

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!

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!

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!

vincanger Oct 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!

Choose a reason for hiding this comment

Uh oh!

infomiho left a comment

Choose a reason for hiding this comment

Testing it locally

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

infomiho left a comment

Choose a reason for hiding this comment

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

vincanger Oct 17, 2025 •

edited

Loading

FranjoMindek commented Nov 4, 2025 •

edited

Loading

FranjoMindek Nov 10, 2025 •

edited

Loading