Pay4SaaS核心概念
Webhook
Webhook 是支付方式向你的服务器发送的实时通知。用户付款成功、订阅状态变更、续费失败——这些事件都通过 Webhook 告知你的后端。
工作原理
用户付款 → 支付方式处理 → 发送 Webhook → 你的 /api/webhooks/{provider} → 更新数据库Pay4SaaS 已经封装好了所有 Webhook 的接收和处理逻辑，你只需要在支付方式后台配置好 Webhook URL。
Webhook 端点
| 渠道 | 端点 | 配置位置 |
|---|---|---|
| Stripe | /api/webhooks/stripe | Stripe Dashboard → Webhooks |
| PayPal | /api/webhooks/paypal | PayPal Developer → Webhooks |
| Creem | /api/webhooks/creem | Creem Dashboard → Webhooks |
| 支付宝 | /api/webhooks/alipay | 支付宝开放平台 → 应用网关 |
生产环境的 Webhook URL 格式：https://你的域名/api/webhooks/{provider}
支持的事件
Stripe
| 事件 | 用途 |
|---|---|
checkout.session.completed | 积分购买、买断购买、首次订阅 |
customer.subscription.created | 订阅创建（激活或试用） |
customer.subscription.updated | 订阅状态变更 |
customer.subscription.deleted | 订阅取消/过期 |
invoice.paid | 订阅续费成功 |
invoice.payment_failed | 订阅续费失败 |
PayPal
| 事件 | 用途 |
|---|---|
BILLING.SUBSCRIPTION.ACTIVATED | 订阅激活 |
BILLING.SUBSCRIPTION.CANCELLED | 订阅取消 |
BILLING.SUBSCRIPTION.EXPIRED | 订阅过期 |
BILLING.SUBSCRIPTION.SUSPENDED | 订阅暂停 |
PAYMENT.SALE.COMPLETED | 付款成功（订阅续费） |
CHECKOUT.ORDER.APPROVED | 一次性购买完成 |
Creem
| 事件 | 用途 |
|---|---|
checkout.completed | 结账完成（积分/买断） |
subscription.active | 订阅激活 |
subscription.trialing | 进入试用 |
subscription.paid | 续费成功 |
subscription.canceled | 订阅取消 |
subscription.expired | 订阅过期 |
Webhook 验签
每个支付方式都有签名验证机制，防止伪造请求：
- Stripe： 使用
STRIPE_WEBHOOK_SECRET验证签名头stripe-signature - PayPal： 使用
PAYPAL_WEBHOOK_ID通过 PayPal API 验证 - Creem： 使用
CREEM_WEBHOOK_SECRET验证 HMAC 签名 - 支付宝： 使用证书验证请求签名
这些都已经在对应的 Webhook handler 中实现好了，你只需要配置好密钥。
本地调试
本地开发时，支付方式无法直接访问 localhost。你需要用内网穿透工具创建一个公网 URL。
通过 ngrok，它是一个内网穿透工具，一句话版解释是，把你本地电脑上跑的服务，临时“暴露”到公网，让开发能通过一个公网网址访问。，免费版每月有 2w 次调用，完全够了。
特别注意！！！如果测试支付，务必把它打开，不打开，支付没法测，支付流程走不通。
下载一下，https://ngrok.com/download/。
注册登录一下，然后，https://dashboard.ngrok.com/get-started/your-authtoken，打开这个，有 token。
解压运行，输入 ngrok config add-authtoken 你的token，然后 ngrok http + 你项目的 localhost 端口，会看到这样的信息。
复制这个地址，去 creem 配置 Webhook。
使用 ngrok
ngrok http 3000得到一个公网 URL（如 https://xxxx.ngrok.io），然后：
- 在支付方式后台将 Webhook URL 设置为
https://xxxx.ngrok.io/api/webhooks/{provider} - 本地启动项目
npm run dev - 触发一次支付，观察终端日志
注意事项
- 上线后记得把 Webhook URL 改为正式域名