update stripe sdk and webhooks to match #427

vincanger · 2025-05-13T15:11:38Z

Description

Contributor Checklist

Make sure to do the following steps if they are applicable to your PR:

Update e2e tests: If you changed the /template/app, then make sure to do any neccessary updates to /template/e2e-tests also.
Update demo app: If you changed the /template/app, then make sure to do any neccessary updates to /opensaas-sh/app_diff also. Check /opensaas-sh/README.md for details.
Update docs: If needed, update the /opensaas-sh/blog/src/content/docs.

vincanger · 2025-05-14T09:23:57Z

template/app/package.json

@@ -24,7 +24,7 @@
    "react-hot-toast": "^2.4.1",
    "react-icons": "4.11.0",
    "react-router-dom": "^6.26.2",
-    "stripe": "11.15.0",
+    "stripe": "^18.1.0",


according to new stripe update policy, this will avoid breaking changes.

Not sure what this means, can you elaborate?

they only introduce breaking changes on major releases, so we can include minor updates.

ok since there's been a new minor update I was getting the error "Type '"2025-04-30.basil"' is not assignable to type '"2025-05-28.basil"' so I pinned the stripe version to avoid future issues.

vincanger · 2025-05-14T09:24:44Z

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

-      // We do this so that we can capture priceId in the payment_intent.succeeded webhook
-      // and easily confirm the user's payment based on the price id. For subscriptions, we can get the price id
-      // in the customer.subscription.updated webhook via the line_items field.
-      payment_intent_data: paymentIntentData,


we're no longer dealing with payment intents to handle one-time payment products. these are now just getting handled directly in checkout.session.completed.

vincanger · 2025-05-14T09:25:29Z

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

@@ -32,8 +32,8 @@ export const stripeWebhook: PaymentsWebhook = async (request, response, context)
      case 'invoice.paid':
        await handleInvoicePaid(data, prismaUserDelegate);
        break;
-      case 'payment_intent.succeeded':
-        await handlePaymentIntentSucceeded(data, prismaUserDelegate);
+      case 'customer.subscription.created':


subscription created events used to be sent in customer.subscription.updated events, but they stopped that , so to handle new subscriptions we need this event.

vincanger · 2025-05-14T09:26:18Z

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

 export async function handleInvoicePaid(invoice: InvoicePaidData, prismaUserDelegate: PrismaClient['user']) {
  const userStripeId = invoice.customer;
  const datePaid = new Date(invoice.period_start * 1000);
-  return updateUserStripePaymentDetails({ userStripeId, datePaid }, prismaUserDelegate);
+  const lineItems = await invoiceLineItemsSchema.parseAsync(invoice.lines);


Not sure if this is needed, because we can be certain that stripe is going to send us the correct format, right?

It's not needed, but not because we trust Stripe (we parse all of their data with Zod), but because we already parsed this data once. The input type of invoice.lines is the same as the output type of lineItems.

So it's a no-op, which is apparent from the duplication in InvoicePaidDataSchema and InvoiceLineItemsSchema:

In fact, I think there's the same duplication in parsing subscription items:

sodic · 2025-05-19T11:55:52Z

I'll take a look tomorrow.

sodic

Hmm, I started reviewing, but got a little confused by the context.

The PR description mentions it closes #229 #198 #293 #412. I went through those issues but couldn't figure out how most of the code in this PR relates to them.

@vincanger is there another issue that this PR addresses? Could you comment on the unexpected code and explain how they relate to those issues, and mention the issue they relate to.

As an example, I understand why the stripe version bump is in this PR, but I don't understand what's happening with the Pending status and the stuff in extractPriceId.

sodic · 2025-06-24T15:30:03Z

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

-  <br/>- `customer.subscription.updated`
-  <br/>- `invoice.paid`
-  <br/>- `payment_intent.succeeded`
+4. select the events you want to listen to. These should be the same events you're consuming in your webhook which you can find listed in `src/payment/stripe/webhookPayload.ts`:


Can we link to the file on Github (no permalink, just link to main).

That way, if the file name becomes outdated, the mistake will be easy to spot.

sodic · 2025-06-24T15:31:01Z

template/app/package.json

@@ -24,7 +24,7 @@
    "react-hot-toast": "^2.4.1",
    "react-icons": "4.11.0",
    "react-router-dom": "^6.26.2",
-    "stripe": "11.15.0",
+    "stripe": "^18.1.0",


Not sure what this means, can you elaborate?

sodic · 2025-06-24T16:00:33Z

template/app/src/payment/plans.ts

@@ -5,6 +5,7 @@ export enum SubscriptionStatus {
  CancelAtPeriodEnd = 'cancel_at_period_end',
  Active = 'active',
  Deleted = 'deleted',
+  Pending = 'pending',


How come we added this?

I added it there as kind of a catch in case they introduce async payment methods or trial periods for their product and forget to update the code. See my other comment below.

vincanger · 2025-07-01T10:05:19Z

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

@@ -8,5 +8,5 @@ export const stripe = new Stripe(requireNodeEnvVar('STRIPE_API_KEY'), {
  // npm package to the API version that matches your Stripe dashboard's one.
  // For more details and alternative setups check
  // https://docs.stripe.com/api/versioning .
-  apiVersion: '2022-11-15',
+  apiVersion: '2025-04-30.basil',


fixes issue #229

vincanger · 2025-07-01T10:08:42Z

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

@@ -54,33 +51,14 @@ export async function createStripeCheckoutSession({
      success_url: `${DOMAIN}/checkout?success=true`,
      cancel_url: `${DOMAIN}/checkout?canceled=true`,
      automatic_tax: { enabled: true },
+      allow_promotion_codes: true,


vincanger · 2025-07-01T10:12:59Z

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

+  return updateUserStripePaymentDetails(
+    { userStripeId, numOfCreditsPurchased, datePaid: new Date() },
+    prismaUserDelegate
+  );


due to updates to the webhook events on Stripe's side, we can now process credits-based payments and subscriptions within the same endpoint. If it's a subscription payment, numOfCreditsPurchased will be undefined and thus won't be updated in the DB. We

I think your sentence got cut off in editing 😄

vincanger · 2025-07-01T10:20:01Z

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

+  const subscriptionStatus: SubscriptionStatus =
+    subscription.status === SubscriptionStatus.Active
+      ? SubscriptionStatus.Active
+      : SubscriptionStatus.Pending;


When a new subscription is created, it can be a few options on Stripe's side: active, pending, trial, etc. Async payment types, such as SEPA transfers, would trigger the pending type and have to be dealt with in a checkout.session.async_payment_succeeded event handler (which we don't include here as most people will just use immediate payments with card). In case they do, the status will be updated with pending here and then later will be sent as completed in the async handler. Similarly, if they choose to allow for trial periods on their products, they would have to implement that logic to deal with trials here.

vincanger · 2025-07-01T12:31:21Z

@sodic ok I commented the code where the relevant issues are solved with the exception of #198 which was actually not addressed explicitly in the code, but after reading the docs while working on this PR I learned that they retry failed webhook events with exponential backoff for a significant period of time and alert you if they're unable to succesfully reach your endpoint.

sodic

We had a call, talked about some stuff.

I left two reminder comments, you'll know what to do :)

sodic · 2025-07-08T10:32:03Z

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

+export async function handleCustomerSubscriptionCreated(
+  subscription: SubscriptionCreatedData,


Let's verify whether this is necessary and if not, let's remove it (parts of it that were left in just in case, probably the pending thing).

Talked about it on a call.

sodic · 2025-07-08T10:48:44Z

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

+  if (session.mode !== 'payment' || session.payment_status !== 'paid') {
+    return;
+  }


We talked about some ways to make this more clear: extracting conditions into variables and/or functions (e.g., isOneTimePayment and calling the function after what it does (e.g., saveOneTimePayment vs handleSomething).

I"m making up names randomly, you'll come up with something more appropriate than I could :)

sodic

Great stuff! I left two suggestions.

sodic · 2025-07-09T09:35:51Z

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

+  if (isSuccessfulOneTimePayment(session)) await saveSuccessfulOneTimePayment(session, prismaUserDelegate);
+}


This is great, two comments:

It seems our convention is always putting curly braces around statements in if blocks and put each statement in its own line, so let's do that here. Btw, this is a the better choice according to most anyway (plenty of reasons ranging from readability to maintainability and bugs, I won't list them all here but they're easily discoverable)

isSuccessfulOneTimePayment can be a local variable. It's probably not general enough to be a function.

sodic · 2025-07-09T09:37:28Z

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

-  paymentIntent: PaymentIntentSucceededData,
+// This is called when a subscription is successfully created
+// But we wait to update the user's subscription status until the invoice is paid in the handleInvoicePaid function.
+export async function handleCustomerSubscriptionCreated(


Can we do the same thing we did in handleCheckoutSessionCompleted with these two functions (handleCustomerSubscriptionCreated and handleInvoicePaid)?

I mean extracting nameable code into something with a name.

vincanger · 2025-07-10T10:51:12Z

Alright @sodic I cleaned up and renamed things as you asked, as well as removing exports from the handlers since they aren't used anywhere outside the webhook file, and added an async declaration for clarity.

sodic · 2025-07-14T16:18:50Z

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

@@ -2,7 +2,7 @@ import type { SubscriptionStatus } from '../plans';
 import { PaymentPlanId } from '../plans';
 import { PrismaClient } from '@prisma/client';

-export const updateUserStripePaymentDetails = (
+export const updateUserStripePaymentDetails = async (


Why the async? Seems unnecessary.

sodic

Did another pass.

It's taking a little long and I'm noticing new stuff on every iteration because I'm unfamiliar with the context, so thanks for the patience.

Are you up for another call to clear some things up for me?
We can chat tomorrow, To prepare: I'll basically ask why each part of each event handler does stuff the way it does because I can't figure out if the API is weird or if we're not using it right.

Maybe you can point me to the relevant docs and I can take a look? I'm hoping they have a flowchart :)

sodic · 2025-07-14T16:20:23Z

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

+// if payment mode === payment (e.g. one-time payment). If payment mode === subscription,
+// we update its status in the customer.subscription.created or customer.subscription.updated webhook.


This part of the comment is not redundant. The code says it all.

sodic · 2025-07-14T16:21:19Z

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

+// which are synchronous, checkout session completed could potentially result in a pending payment.
+// If so, use the checkout.session.async_payment_succeeded event to confirm the payment.


Suggested change

// which are synchronous, checkout session completed could potentially result in a pending payment.

// If so, use the checkout.session.async_payment_succeeded event to confirm the payment.

// which are synchronous, the checkout.session.completed could event potentially result in a pending payment.

// If so, use the checkout.session.async_payment_succeeded event to confirm the payment.

Makes it clearer what we're talking about.

sodic · 2025-07-14T16:21:59Z

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


-  return updateUserStripePaymentDetails({ userStripeId, subscriptionPlan }, prismaUserDelegate);
+// This is called when a subscription is successfully purchased or renewed and payment succeeds.
+// Invoices are not created for one-time payments, so we handle them above.


Instead of "above," let's say where we handle them.

sodic · 2025-07-14T16:23:30Z

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

-
-  const { numOfCreditsPurchased } = getPlanEffectPaymentDetails({ planId, planEffect: plan.effect });
+  // We save everything except the subscription status (hence "unpaid"),
+  // which we update in handleInvoicePaid once we get confirmation the payment succeeded.


Maybe we should mention the event instead of our handler name. Less likely to get outdated.

sodic · 2025-07-14T16:24:21Z

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

+  const userStripeId = subscription.customer;
+  const priceId = extractPriceId(subscription.items);
+  const subscriptionPlan = getPlanIdByPriceId(priceId);
+  return updateUserStripePaymentDetails({ userStripeId, subscriptionPlan }, prismaUserDelegate);


Why isn't there a status update here?

sodic · 2025-07-14T16:43:29Z

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

 export async function handleInvoicePaid(invoice: InvoicePaidData, prismaUserDelegate: PrismaClient['user']) {
  const userStripeId = invoice.customer;
  const datePaid = new Date(invoice.period_start * 1000);
-  return updateUserStripePaymentDetails({ userStripeId, datePaid }, prismaUserDelegate);
+  const lineItems = await invoiceLineItemsSchema.parseAsync(invoice.lines);


It's not needed, but not because we trust Stripe (we parse all of their data with Zod), but because we already parsed this data once. The input type of invoice.lines is the same as the output type of lineItems.

So it's a no-op, which is apparent from the duplication in InvoicePaidDataSchema and InvoiceLineItemsSchema:

In fact, I think there's the same duplication in parsing subscription items:

vincanger added 3 commits May 13, 2025 17:01

update stripe sdk and webhooks to match

8c978ee

Update deploying.mdx

b759d63

Update webhook.ts

df84c5b

vincanger requested a review from sodic May 14, 2025 09:23

vincanger commented May 14, 2025

View reviewed changes

Martinsos assigned sodic and unassigned sodic May 14, 2025

This was referenced May 19, 2025

upgrade stripe version #293

Closed

Upgrade Stripe SDK to Support 100% Off Coupons #412

Closed

sodic requested changes Jun 24, 2025

View reviewed changes

vincanger commented Jul 1, 2025

View reviewed changes

vincanger added 2 commits July 1, 2025 12:26

add github link to payload events

24c6967

lock stripe version

147e0f5

sodic reviewed Jul 8, 2025

View reviewed changes

remove pending status

1041d5e

sodic reviewed Jul 9, 2025

View reviewed changes

remove exports on handlers

2061222

sodic reviewed Jul 14, 2025

View reviewed changes

remove unnecessary functions

3b52486

		export async function handleCustomerSubscriptionCreated(
		subscription: SubscriptionCreatedData,

		if (isSuccessfulOneTimePayment(session)) await saveSuccessfulOneTimePayment(session, prismaUserDelegate);
		}

		// if payment mode === payment (e.g. one-time payment). If payment mode === subscription,
		// we update its status in the customer.subscription.created or customer.subscription.updated webhook.

		// which are synchronous, checkout session completed could potentially result in a pending payment.
		// If so, use the checkout.session.async_payment_succeeded event to confirm the payment.

Uh oh!

update stripe sdk and webhooks to match #427

Are you sure you want to change the base?

update stripe sdk and webhooks to match #427

Uh oh!

Conversation

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

Uh oh!

Description

Contributor Checklist

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!

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!

Choose a reason for hiding this comment

Uh oh!

sodic commented May 19, 2025

Uh oh!

sodic left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vincanger commented Jul 1, 2025

Uh oh!

sodic left a comment

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!

sodic left a comment

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!

vincanger commented Jul 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

vincanger commented May 13, 2025 •

edited

Loading

sodic left a comment •

edited

Loading