stripe 23.0.0: what changes for payments and webhooks

If you have built Stripe into payments for an e-commerce or booking site and write the server side in Node.js, you may receive a dependency update PR that bumps the major version of stripe. stripe 23.0.0, published to npm on October 1, 2026, looks like just a one-number bump, but it changes the content of payment requests and the behavior of webhook verification.

The changelog lists many breaking changes marked with "⚠️". We lay out those directly related to the payment screen and the webhook endpoint, together with the results of running 22.6.2 and 23.0.0 locally. We checked by having the SDK send requests to a local test server, and did not connect to Stripe's production or sandbox environments.

Upgrading the SDK also changes the API version it sends

The beginning of the 23.0.0 changelog says, "This release changes the pinned API version to 2026-09-30.endive." The configuration table in the README also explains that if apiVersion is not set, "stripe-node will use the latest version at the time of release."

We pointed the destination to a local server and recorded the actual headers.

stripe 22.6.2  sent Stripe-Version: 2026-08-26.dahlia
stripe 23.0.0  sent Stripe-Version: 2026-09-30.endive
stripe 23.0.0（apiVersion: '2026-08-26.dahlia' を指定）  sent Stripe-Version: 2026-08-26.dahlia

For code that does not specify apiVersion, the API version sent to Stripe changes as soon as you upgrade the package. If you specify it, you can keep sending the previous version even after upgrading the SDK. However, the README says "our types only reflect the latest API version," so the TypeScript types change to match the new version. Note that if you keep using the old version, there will be places where the types and the actual responses do not match.

Specifying payment methods for Checkout has been removed from the types and the API

The generated code changes in 23.0.0 include "Remove support for payment_method_types on Checkout.SessionCreateParams, PaymentIntentConfirmParams, PaymentIntentCreateParams, …" and, in its place, add "Add support for allowed_payment_method_types on Checkout.SessionCreateParams and Checkout.Session."

We type-checked code that creates a Checkout session with payment_method_types: ['card'] on both versions.

# stripe 23.0.0
error TS2561: Object literal may only specify known properties, but 'payment_method_types'
  does not exist in type 'SessionCreateParams'. Did you mean to write 'payment_method_data'?
error TS2561: ... but 'payment_method_types' does not exist in type 'PaymentIntentCreateParams'.
# stripe 22.6.2
（エラーなし。逆に allowed_payment_method_types は存在しないとエラー）

With TypeScript, the build stops, so you will notice. The case that needs care is when you write plain JavaScript. Even in 23.0.0, the payment_method_types written in the code was put into the request body as is and sent (payment_method_types[0]=card). The SDK does not stop it, so the outcome depends on how Stripe handles it.

According to Stripe's API changelog (breaking changes in 2026-09-30.endive), with this API version, passing payment_method_types when creating a Checkout Session returns a 400 error. The same applies to Payment Intents (create, update, confirm) and Setup Intents (create, update), and the error code is given as payment_method_types_no_longer_supported. In other words, JavaScript code that does not specify apiVersion will no longer be able to create payment screens once the SDK is upgraded. Instead, use dynamic payment methods managed in the Dashboard, or allowed_payment_method_types. The changelog explains that allowed_payment_method_types excludes payment methods that do not fit the currency or amount instead of returning an error. The editorial team did not connect to the Stripe API; the 400 error is based on the changelog, and we have not checked the actual response. Before updating, we recommend running through Checkout in a sandbox from creation to payment completion.

The allowed_payment_method_types type also included paypay. Support for PayPay (the paypay_payments capability, payment_method_details.paypay, and so on) is also among the items added in 23.0.0. Stripe's API changelog describes it as a one-time online payment for eligible accounts based in Japan, and it does not support recurring payments or subscriptions.

Two behaviors that change in webhook signature verification

If you confirm orders by receiving payment completion via webhooks, this change may have the bigger impact. The changelog describes it as follows.

stripe.webhooks.signature.verifyHeader() and verifyHeaderAsync() previously skipped timestamp tolerance verification when the tolerance argument was omitted. They now default to Webhook.DEFAULT_TOLERANCE

Passing 0 to stripe.webhooks.constructEvent now properly skips timestamp tolerance verification. Previously, passing 0 would perform verification with the default tolerance Webhook.DEFAULT_TOLERANCE.

Using the SDK's generateTestHeaderString, we created headers with signature timestamps set to "now," "10 minutes ago," and "1 hour ago," and verified them with three different call patterns (DEFAULT_TOLERANCE is 300 seconds in both versions).

Two things can be read from this.

1. Code that calls signature.verifyHeader() directly will reject old signatures starting with 23.0.0. If you have processing that verifies delayed events after the fact, it may result in errors
2. Code that specifies constructEvent(..., 0) will stop checking timestamps starting with 23.0.0. Through 22.6.2, the 300-second check still applied even when 0 was passed, so code written with the assumption that "0 means the default" will silently change to accepting old (replayed) signatures

The signature itself is still verified, but the timestamp check is a defense against attacks in which a stolen legitimate request is resent later. Search your repository as follows, and wherever 0 is passed, remove the argument or specify the number of seconds explicitly.

grep -rnE "constructEvent(Async)?\(|verifyHeader(Async)?\(" --include=*.js --include=*.ts --include=*.mjs --include=*.cjs src/ server/ api/ 2>/dev/null

Other changes to check

• End of Node.js 18 support: The changelog states "Node.js 20 is now the minimum supported version." The engines in package.json also changed from >=18 to >=20. If you pin the Node.js version in a serverless runtime, upgrade it first. Maintenance deadlines for each Node.js version are summarized in Node.js 24 enters maintenance on October 20
• Change in error types: When a response body is cut off partway, the error is now StripeConnectionError instead of StripeAPIError. Review any processing that decides retries based on error type
• Removal of a type export: ErrorType is no longer exported, and you are directed to use Stripe.errors instead
• URL for the Specified Commercial Transactions Act disclosure: specified_commercial_transactions_act_url was added to Account.business_profile in the types (for platforms that create accounts with Connect). It is a Japan-specific field; type checking passed on 23.0.0, while 22.6.2 reported an error saying it does not exist

How to proceed with the upgrade

The following is the editorial team's proposal.

1. Pin the API version first. If you specify apiVersion: '2026-08-26.dahlia' explicitly while still on 22.x, you can handle the SDK upgrade and the API version upgrade separately
2. Upgrade the SDK to 23.0.0 and fix type errors and webhook calls. Check replacements of payment_method_types, the fourth argument of constructEvent, and direct calls to verifyHeader
3. Run payments end to end in a sandbox. Verify card payments, the payment methods you use, refunds, and everything through webhook receipt and order confirmation
4. Upgrade the API version last. Also check the version in the dashboard's webhook delivery settings

Operational aspects of payments, such as preparing for chargebacks, are covered in Preparing for friendly fraud and chargebacks, and the steps for checking npm dependency versions are covered in sharp's AVIF vulnerability: check that Astro and Next.js use 0.35.4 or later.

Scope of verification

On October 11, 2026, we checked the CHANGELOG.md of stripe/stripe-node (23.0.0, 2026-09-30), the README and package.json of stripe 23.0.0 as published on npm, and the publication timestamps on registry.npmjs.org (document research). We also installed stripe 22.6.2 and 23.0.0 on Node.js 22.22.0 on Linux, pointed requests at a local HTTP server to record the Stripe-Version header and body, ran type checks with TypeScript 5, and compared webhook verification using signatures created with generateTestHeaderString (hands-on testing). On October 16, 2026, we also checked the entries in Stripe's API changelog (2026-09-30.endive) on the removal of payment_method_types and the addition of PayPay. We did not connect to the Stripe API (live or sandbox) and have not confirmed actual responses such as 400 errors.

For payment library upgrades or reviews of your webhook endpoints, contact us through Development, AI, and automation consultations.

References

• stripe/stripe-node — CHANGELOG.md（23.0.0 - 2026-09-30）
• stripe/stripe-node - README.md (API versions and TypeScript types, webhook signatures)
• npm registry - stripe (publication timestamps)
• Stripe Docs — Removes the payment method types parameter from Checkout Sessions（2026-09-30.endive）
• Stripe Docs — Removes the payment method types parameter from Payment Intents and Setup Intents（2026-09-30.endive）