@01mvp/payment

这是什么

@01mvp/payment 是一个统一的支付接口，让你用同一套代码接入多种支付方式。目前支持五种支付提供商：

提供商	适用场景
Stripe	国际信用卡支付，支持一次性付款和订阅
微信支付	国内市场，支持 PC 扫码 / 公众号 / 小程序
支付宝	国内市场，通过 `alipay-sdk` 接入
PayPal	国际市场，一次性付款
Waffo	新兴支付提供商，通过 `@waffo/pancake-ts` 接入

不管用哪个，调用方式统一，方便后续切换或同时支持。

能做什么

创建订单 -- 生成支付链接或二维码，用户扫码/点击即可付款
微信支付三种场景 -- PC 扫码（NATIVE）、微信公众号内支付（JSAPI）、小程序支付（MINIPROGRAM），包内自动根据环境选择合适的渠道
处理支付回调 -- 接收支付平台的通知（Webhook），自动验签并更新订单状态
查询订单 -- 随时查看某笔订单的支付状态
关闭过期订单 -- 超时未支付的订单自动取消

核心类型

创建支付的参数（PaymentParams）

调用 createPayment() 时需要传入的参数：

Prop

Type

支付计划类型（PaymentPlan）

定义一个可售卖的计划/套餐：

Prop

Type

怎么配置

Stripe

STRIPE_SECRET_KEY=sk_test_xxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxx

去 dashboard.stripe.com 注册即可拿到测试密钥。

微信支付

WECHAT_PAY_APP_ID=wx1234567890abcdef      # 公众号/小程序 AppID
WECHAT_PAY_MCH_ID=1234567890              # 商户号
WECHAT_PAY_API_V3_KEY=your-32-char-key    # API v3 密钥（32位）
WECHAT_PAY_SERIAL_NO=1234567890ABCDEF     # 证书序列号
WECHAT_PAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."  # 商户私钥（PEM格式）

这些凭证在微信支付商户平台获取，具体步骤参考微信支付官方文档。

大概原理

整个支付流程分几步：

用户下单 -- 你的后端调用 createPayment()，传入金额、用户 ID、支付渠道
支付平台响应 -- Stripe 返回一个支付链接，微信 NATIVE 返回一个二维码链接，微信 JSAPI 返回调起支付的参数
用户付款 -- 在 PC 上扫码、在微信里跳转支付页面、或在小程序里调起支付
支付平台回调 -- 用户付完钱，支付平台会发一个通知（Webhook）到你的服务器，告知支付结果
你的后端验签 -- 用 handleWebhook() 验证这个通知是不是真的来自支付平台（防伪造），验证通过后更新订单状态
后续处理 -- 比如订单变成"已支付"后，自动给用户加积分、发通知等

最佳实践

私钥永远放环境变量，不要提交到 Git
始终验证 Webhook 签名再处理业务逻辑
生产环境必须用 HTTPS
实现幂等性（同一个 Webhook 收到多次不会重复处理）
开发测试用沙箱/测试环境，别用真实商户号

payment 支付服务