Skip to main content

概述

钱包接口允许已认证用户读取充值配置、创建支付链接、兑换充值码、查询充值记录以及管理自动充值。
支付和自动充值接口会创建真实的财务操作。只能在可信服务端、获得用户明确确认后调用。

读取充值配置

展示金额或付款方式前,始终先读取当前配置:
常用字段包括: 这些值属于部署和活动配置。创建支付链接前,应再次校验所选金额。

创建支付链接

当前钱包流程接收整数美元金额以及以下付款方式:
在浏览器中将用户重定向到 pay_link。获得支付链接并不代表余额已经到账;支付提供商确认完成后,系统才会入账。
不要把系统访问令牌放入跳转 URL,也不要将其发送给支付提供商。

兑换充值码

充值码只能使用一次。不要记录充值码,也不要重试已经成功的兑换操作。

充值记录

响应包含 itemspagepage_sizetotal。支付完成后,应同时刷新充值记录和账号余额:
账号额度使用内部单位,请按照认证与额度中的方法通过 quota_per_unit 换算。

读取自动充值状态

响应字段包括:
  • bound:是否已绑定可重复扣款的付款方式
  • card_last4:卡号末四位掩码
  • enabled:是否已启用自动充值
  • threshold:触发充值的钱包美元余额
  • amount:每次触发时充值的美元金额
  • stripe_ready:当前账号是否可以配置自动充值

绑定付款方式

尚未绑定付款方式时,启动设置流程:
将用户重定向到 setup_link。等待支付提供商回调后,再次调用 GET /api/user/auto-recharge,确认 bound: true 后才能启用自动充值。

配置自动充值

绑定完成后,一次性更新三个设置:
threshold 不能为负数。当前控制台要求自动充值的 amount 至少为 10 美元,但客户端仍应遵守服务器和支付提供商返回的最新限制。 如果只想关闭自动充值而保留绑定的付款方式,请发送相同请求体,并将 enabled 设置为 false

删除付款绑定

删除绑定会同时关闭自动充值并移除已保存的卡片引用。调用前必须取得用户明确确认。

推荐支付流程

  1. 读取 /api/user/topup/info,校验金额和付款方式。
  2. 只创建一次支付或绑定链接。
  3. 将用户重定向到返回的链接。
  4. 将支付提供商的跳转结果视为待确认状态,而不是到账证明。
  5. 轮询 /api/user/topup/self/api/user/self/api/user/auto-recharge,直到出现预期状态。
  6. 在应用层保证重试幂等,避免同一次用户操作生成多个支付链接。