充值单与 Checkout

@downcity/services 这一版不是 subscription 或 entitlement 系统，它的核心是：

让 Stripe 一次性支付去完成一笔已经存在的 topup。

为什么必须先有 topup

因为“用户说我要充钱”和“系统确认已经到账”不是一回事。

在 Downcity 里，更稳定的建模方式是：

1. 先创建 pending topup
2. 再去 Stripe 支付
3. 支付成功后完成 topup

这样做的好处是：

• 充值金额的可信源在 City，不在前端
• Stripe 支付记录和内部充值单可以稳定一一对应
• 到账动作统一收口到 balance.finishTopup()

最常见链路

const topup = await user.service("balance").action("topups/create").invoke({
  amount: 500,
  note: "recharge",
});

const checkout = await user.service("payment.stripe").action("checkout/create").invoke({
  topup_id: topup.topup_id,
});

前端跳转到 checkout.checkout_url 后，用户就在 Stripe 完成支付。

为什么不让 Stripe 服务直接收金额

如果让前端直接把金额传给 Stripe 服务，再由它独立发起支付，会有几个问题：

• 前端金额更容易被篡改
• 内部没有统一的充值单记录
• 后续到账、失败、过期都很难对齐

所以这层的关键不是“怎么收钱”，而是“先让 City 拿到可信 topup，再让 Stripe 去完成它”。

常用入口

• POST /v1/balance/topups/create
• POST /v1/payment.stripe/checkout/create