open-saas 支付接入实战三步跑通 Stripe 订阅付费与 Webhook 回调【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas假设你的 SaaS 产品已经做完现在要加上订阅付费还希望用户能上传文件——但不想从零写支付流程、签名校验和订阅状态流转。open-saasReact Node.js Prisma 的免费 SaaS 模板已经把这些都实现了。读完这篇你会知道付费模块该看哪几个文件、Stripe 的 Key 填在哪、回调怎么接才能自动更新订阅状态、前端的购买按钮到底是怎么调通后端的。️ 架构全景一次购买请求怎么走一圈先建立地图前端只发买哪个计划这一个参数后端 operations.ts 先做登录态和参数校验再把活儿交给 Stripe 处理器创建结账会话并返回支付 URL用户付完款Stripe 会异步回调/payments-webhook后端验签后把订阅状态写回数据库。整个流程不经过任何轮询支付结果的脏活。分层文件职责前端页面payment/PricingPage.tsx渲染定价卡片、触发购买、打开客户门户路由与操作注册payment/payment.wasp.ts挂载 /pricing、/checkout 页面和 webhook业务逻辑payment/operations.ts401/403 权限校验 Zod 参数校验计划定义payment/plans.tsHobby、Pro、Credits10 三个计划及其效果Stripe 实现payment/stripe/结账创建、计费门户、回调处理回调入口payment/webhook.ts把请求转发给当前处理器的 webhook关键设计是 paymentProcessor.ts 里的接口抽象Stripe、Lemon Squeezy、Polar.sh 三家实现了同一套接口换支付渠道只改一行export const paymentProcessor: PaymentProcessor stripePaymentProcessor; // export const paymentProcessor: PaymentProcessor lemonSqueezyPaymentProcessor; // export const paymentProcessor: PaymentProcessor polarPaymentProcessor;️ 动手路线后端填环境变量读三个关键文件先打开 payment/plans.ts它定义了三个计划Hobby 和 Pro 是订阅subscription 效果Credits10 是一次性积分充值credits 效果。你要增删计划就改这里的枚举和 paymentPlans 对象再走一遍完整流程验证。再打开 .env把付费相关的环境变量填齐全部有 Zod 校验缺一个应用直接起不来PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_IDprice_1xxx PAYMENTS_PRO_SUBSCRIPTION_PLAN_IDprice_1yyy PAYMENTS_CREDITS_10_PLAN_IDprice_1zzz STRIPE_API_KEYsk_test_xxx STRIPE_WEBHOOK_SECRETwhsec_xxx前三个是 Stripe 控制台的 Price ID后两个分别是密钥和 webhook 签名密钥。自测方法启动应用用测试账号登录后调用 getCustomerPortalUrl 操作未付过款的用户应返回 null 而不是报错。前端购买按钮怎么接不用自己包 API 请求Wasp 会根据 payment.wasp.ts 里注册的 operations 自动生成类型安全的客户端前端不写 fetch。PricingPage.tsx 里立即购买的核心逻辑就三步const checkoutSession await generateCheckoutSession(paymentPlanId); if (checkoutSession?.sessionUrl) { window.open(checkoutSession.sessionUrl, _self); }管理订阅按钮则用useQuery(getCustomerPortalUrl)拿门户地址且设了enabled: isUserSubscribed只有已订阅用户才发请求。你通常只需要改paymentPlanCards里的价格和功能文案请求逻辑一行都不用动。联调本地把回调闭环跑通回调是最容易漏的一环。开一个终端跑 Stripe 本地转发stripe listen --forward-to localhost:3000/payments-webhook把终端打印的 whsec_ 开头的签名密钥复制进 STRIPE_WEBHOOK_SECRET。注意 webhook.ts 用express.raw解析原始请求体——Stripe 验签必须基于原始字节换成 JSON 解析验签必挂。验签通过后按事件分发switch (event.type) { case invoice.paid: /* 写订阅状态或加积分 */ break; case customer.subscription.updated: /* 状态流转取消时发挽留邮件 */ break; case customer.subscription.deleted: /* 标记为 deleted */ break; }联调流程打开定价页 → 立即购买 → 用测试卡 4242 4242 4242 4242 付款 → 回到 /checkout 成功页 → 查数据库subscriptionStatus 应为 active。最后去计费门户取消订阅观察状态变为 cancel_at_period_end并确认收到挽留邮件。⚠️ 踩坑清单现象webhook 一直 400报签名验证失败。原因把 STRIPE_API_KEY 的值填进了 STRIPE_WEBHOOK_SECRET两者不是一回事。改法webhook secret 必须是 whsec_ 开头的签名密钥本地用stripe listen打印的那个。现象付款成功但用户 subscriptionStatus 没变。原因Stripe 控制台给 webhook 勾选的事件太多后端遇到没处理的事件会抛 UnhandledWebhookEventError而你要的事件被淹没在日志里。改法控制台只勾选上面那 3 个事件然后盯后端日志确认事件真的到了。现象一次性积分购买没有任何回调触发。原因Stripe 只对订阅自动生成 invoice.paid一次性支付必须显式开启 invoice 创建。改法stripe/checkoutUtils.ts 已对 payment 模式启用invoice_creation你照抄这份文件时别把这行删掉。现象调购买接口返回 403 User needs an email to make a payment。原因你的认证方式是 usernameAndPassword拿不到邮箱而 Stripe 建客户必须用邮箱。改法换成带邮箱的认证方式如邮箱密码或 OAuth。现象换 Lemon Squeezy 后支付报Unknown payment processor plan ID。原因paymentProcessorPlans.ts 用环境变量把内部计划映射到渠道侧的计划 ID换渠道后这三个值没换。改法把三个 PAYMENTS_*_PLAN_ID 重填为新渠道的 ID。✅ 验收清单付费环境变量全部填齐三个 PLAN_ID 与 Stripe 控制台 Price ID 一致webhook 只配置 3 个事件本地触发后日志无 Unhandled 报错测试卡购买后用户 subscriptionStatus 变为 active管理后台能看到收入计费门户取消订阅后状态变为 cancel_at_period_end并收到挽留邮件一次性积分计划购买后用户积分余额正确增加未登录调购买接口返回 401非管理员调用户管理接口返回 403文件上传白名单 ALLOWED_FILE_TYPES 已改成你业务需要的类型S3 桶已建好下一步打开 template/blog 的 docs/guides 目录读支付集成章节逐项核对你的环境变量然后在 template/app 目录跑npm run dev把购买 → 回调 → 取消完整闭环走一遍跑通后就可以基于 subscriptionStatus 字段写你自己的付费功能门控逻辑了。【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 open-saas 支付接入实战：三步跑通 Stripe 订阅付费与 Webhook 回调
open-saas 支付接入实战三步跑通 Stripe 订阅付费与 Webhook 回调【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas假设你的 SaaS 产品已经做完现在要加上订阅付费还希望用户能上传文件——但不想从零写支付流程、签名校验和订阅状态流转。open-saasReact Node.js Prisma 的免费 SaaS 模板已经把这些都实现了。读完这篇你会知道付费模块该看哪几个文件、Stripe 的 Key 填在哪、回调怎么接才能自动更新订阅状态、前端的购买按钮到底是怎么调通后端的。️ 架构全景一次购买请求怎么走一圈先建立地图前端只发买哪个计划这一个参数后端 operations.ts 先做登录态和参数校验再把活儿交给 Stripe 处理器创建结账会话并返回支付 URL用户付完款Stripe 会异步回调/payments-webhook后端验签后把订阅状态写回数据库。整个流程不经过任何轮询支付结果的脏活。分层文件职责前端页面payment/PricingPage.tsx渲染定价卡片、触发购买、打开客户门户路由与操作注册payment/payment.wasp.ts挂载 /pricing、/checkout 页面和 webhook业务逻辑payment/operations.ts401/403 权限校验 Zod 参数校验计划定义payment/plans.tsHobby、Pro、Credits10 三个计划及其效果Stripe 实现payment/stripe/结账创建、计费门户、回调处理回调入口payment/webhook.ts把请求转发给当前处理器的 webhook关键设计是 paymentProcessor.ts 里的接口抽象Stripe、Lemon Squeezy、Polar.sh 三家实现了同一套接口换支付渠道只改一行export const paymentProcessor: PaymentProcessor stripePaymentProcessor; // export const paymentProcessor: PaymentProcessor lemonSqueezyPaymentProcessor; // export const paymentProcessor: PaymentProcessor polarPaymentProcessor;️ 动手路线后端填环境变量读三个关键文件先打开 payment/plans.ts它定义了三个计划Hobby 和 Pro 是订阅subscription 效果Credits10 是一次性积分充值credits 效果。你要增删计划就改这里的枚举和 paymentPlans 对象再走一遍完整流程验证。再打开 .env把付费相关的环境变量填齐全部有 Zod 校验缺一个应用直接起不来PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_IDprice_1xxx PAYMENTS_PRO_SUBSCRIPTION_PLAN_IDprice_1yyy PAYMENTS_CREDITS_10_PLAN_IDprice_1zzz STRIPE_API_KEYsk_test_xxx STRIPE_WEBHOOK_SECRETwhsec_xxx前三个是 Stripe 控制台的 Price ID后两个分别是密钥和 webhook 签名密钥。自测方法启动应用用测试账号登录后调用 getCustomerPortalUrl 操作未付过款的用户应返回 null 而不是报错。前端购买按钮怎么接不用自己包 API 请求Wasp 会根据 payment.wasp.ts 里注册的 operations 自动生成类型安全的客户端前端不写 fetch。PricingPage.tsx 里立即购买的核心逻辑就三步const checkoutSession await generateCheckoutSession(paymentPlanId); if (checkoutSession?.sessionUrl) { window.open(checkoutSession.sessionUrl, _self); }管理订阅按钮则用useQuery(getCustomerPortalUrl)拿门户地址且设了enabled: isUserSubscribed只有已订阅用户才发请求。你通常只需要改paymentPlanCards里的价格和功能文案请求逻辑一行都不用动。联调本地把回调闭环跑通回调是最容易漏的一环。开一个终端跑 Stripe 本地转发stripe listen --forward-to localhost:3000/payments-webhook把终端打印的 whsec_ 开头的签名密钥复制进 STRIPE_WEBHOOK_SECRET。注意 webhook.ts 用express.raw解析原始请求体——Stripe 验签必须基于原始字节换成 JSON 解析验签必挂。验签通过后按事件分发switch (event.type) { case invoice.paid: /* 写订阅状态或加积分 */ break; case customer.subscription.updated: /* 状态流转取消时发挽留邮件 */ break; case customer.subscription.deleted: /* 标记为 deleted */ break; }联调流程打开定价页 → 立即购买 → 用测试卡 4242 4242 4242 4242 付款 → 回到 /checkout 成功页 → 查数据库subscriptionStatus 应为 active。最后去计费门户取消订阅观察状态变为 cancel_at_period_end并确认收到挽留邮件。⚠️ 踩坑清单现象webhook 一直 400报签名验证失败。原因把 STRIPE_API_KEY 的值填进了 STRIPE_WEBHOOK_SECRET两者不是一回事。改法webhook secret 必须是 whsec_ 开头的签名密钥本地用stripe listen打印的那个。现象付款成功但用户 subscriptionStatus 没变。原因Stripe 控制台给 webhook 勾选的事件太多后端遇到没处理的事件会抛 UnhandledWebhookEventError而你要的事件被淹没在日志里。改法控制台只勾选上面那 3 个事件然后盯后端日志确认事件真的到了。现象一次性积分购买没有任何回调触发。原因Stripe 只对订阅自动生成 invoice.paid一次性支付必须显式开启 invoice 创建。改法stripe/checkoutUtils.ts 已对 payment 模式启用invoice_creation你照抄这份文件时别把这行删掉。现象调购买接口返回 403 User needs an email to make a payment。原因你的认证方式是 usernameAndPassword拿不到邮箱而 Stripe 建客户必须用邮箱。改法换成带邮箱的认证方式如邮箱密码或 OAuth。现象换 Lemon Squeezy 后支付报Unknown payment processor plan ID。原因paymentProcessorPlans.ts 用环境变量把内部计划映射到渠道侧的计划 ID换渠道后这三个值没换。改法把三个 PAYMENTS_*_PLAN_ID 重填为新渠道的 ID。✅ 验收清单付费环境变量全部填齐三个 PLAN_ID 与 Stripe 控制台 Price ID 一致webhook 只配置 3 个事件本地触发后日志无 Unhandled 报错测试卡购买后用户 subscriptionStatus 变为 active管理后台能看到收入计费门户取消订阅后状态变为 cancel_at_period_end并收到挽留邮件一次性积分计划购买后用户积分余额正确增加未登录调购买接口返回 401非管理员调用户管理接口返回 403文件上传白名单 ALLOWED_FILE_TYPES 已改成你业务需要的类型S3 桶已建好下一步打开 template/blog 的 docs/guides 目录读支付集成章节逐项核对你的环境变量然后在 template/app 目录跑npm run dev把购买 → 回调 → 取消完整闭环走一遍跑通后就可以基于 subscriptionStatus 字段写你自己的付费功能门控逻辑了。【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考