@visiblebase/service-payment-stripe

VisibleBase 官方 Stripe 支付服务。

当前版本只处理 Stripe 一次性充值，把支付成功结果同步到用户全局余额；不处理 subscription 或 entitlement，也不直接依赖 Stripe SDK。

安装

pnpm add @visiblebase/service-payment-stripe

使用

import { Base } from "@visiblebase/core";
import { balanceService } from "@visiblebase/service-balance";
import {
  stripePaymentService,
  type StripePaymentServiceBalanceBridge,
} from "@visiblebase/service-payment-stripe";

const base = new Base({ db });
const balance = balanceService();
const stripeBalanceBridge: StripePaymentServiceBalanceBridge = {
  readTopup: async (topup_id) => await balance.readTopup(topup_id),
  finishTopup: async (topup_id, extra) => await balance.finishTopup(topup_id, extra),
};

base.use(balance);
base.use(stripePaymentService({
  balance: stripeBalanceBridge,
  secret_key: process.env.STRIPE_SECRET_KEY,
  webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
}));

服务会自动创建 service_stripe_payments 和 service_stripe_events 表。

运行时环境变量

当你不想把配置直接写进 stripePaymentService() 参数时，可以通过 Runtime env 提供：

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• STRIPE_SUCCESS_URL
• STRIPE_CANCEL_URL
• VISIBLEBASE_BASE_URL
• STRIPE_CURRENCY
• STRIPE_ITEM_NAME
• STRIPE_API_BASE_URL

其中最常见的是：

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• VISIBLEBASE_BASE_URL（可选）

如果你没有单独配置 STRIPE_SUCCESS_URL / STRIPE_CANCEL_URL，服务会按下面顺序自动补默认跳转地址：

1. VISIBLEBASE_BASE_URL
2. 当前请求的 origin

最终生成的路径都是：

• {base-or-origin}/v1/payment.stripe/redirect/success
• {base-or-origin}/v1/payment.stripe/redirect/cancel

典型链路

1. 用户先通过 balance 创建一笔 pending topup
2. 再调用 payment.stripe 为该 topup 创建 Stripe Checkout
3. Stripe 支付成功后，服务通过 webhook 调 balance.finishTopup() 完成到账

路由

• POST /v1/payment.stripe/checkout/create
• GET /v1/payment.stripe/payments/me
• GET /v1/payment.stripe/payments
• GET /v1/payment.stripe/events
• POST /v1/payment.stripe/webhook

也就是说，你在 Stripe Dashboard 里注册 webhook endpoint 时，默认地址就是：

• {base_url}/v1/payment.stripe/webhook

配置 webhook_secret 或 STRIPE_WEBHOOK_SECRET 后，webhook 会校验 stripe-signature。checkout.session.completed 会自动完成对应 topup 并增加用户全局余额。

如果你部署在 Cloudflare Workers 这类显式 bindings 环境里，记得同时提供：

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET

也就是说，大多数部署下你不再需要手动配置跳转地址。

如果你希望显式覆写跳转地址，可以再提供：

• STRIPE_SUCCESS_URL
• STRIPE_CANCEL_URL