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

# 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?

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?

infomiho · 2025-11-04T11:13:02Z

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

+  numOfCreditsPurchased: number;
+}
+
+export function updateUserStripeOneTimePaymentDetails(


Do we want to add explicit return types to these fns? I know we want to do it in our codebase, but since this is a template we might want to more relaxed with this?

Oh sure, I think I actually wasn't sure how to get proper prisma type here manually, so I skipped them.
Will add them.

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.

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 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

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 4 commits November 4, 2025 20:53

changes

4088bca

capitalize

2262a2c

fix trailing slash bug, formatting

5fab9a3

update diff

ae1b458

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!

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!

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!

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

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