用途:在 PinMe Worker(Cloudflare Worker TypeScript)中编写、修改或审查直接调用 UniwebPay 的支付服务代码。PinMe 按用户(非按项目)开通 UniwebPay 钱包与密钥,并在部署时注入 UNIWEB_* 绑定;Worker 直接使用 @uniwebpay/sdk 调用 UniwebPay,不经过 PinMe 支付代理路由,也不调用旧的 VibeCash API。
环境绑定:Env 含 UNIWEB_SECRET(服务端 sk_server_ 密钥)、UNIWEB_WEBHOOK_SECRET(钱包级 whsec_,用于验签)、UNIWEB_API_URL、UNIWEB_PAY_URL、UNIWEB_WALLET_ID、WORKER_URL、PROJECT_NAME、DB 等。绑定在凭据开通后注入,已有项目需启用或轮换密钥后重新部署。同一用户所有项目共享一个钱包与密钥;完整 sk_live_ 不会下发给 Worker。缺失 UNIWEB_SECRET 时应提示用户启用并重新部署,不应编造值。
主要能力:SDK 只能在服务端实例化。支持固定金额支付链接(links.create,一次性)、稳定商品目录(products.create + prices.create,返回永久 paymentUrl)、动态购物车(checkout.create,24 小时有效)、订阅(recurring 价格 + checkout mode/subscriptions)、支付状态查询、退款、客户管理。金额为整数最小单位,默认货币 SGD;wechat/alipay/paynow 仅支持 SGD,订阅仅支持 card。list() 返回 { data, hasMore };listAll() 为异步生成器(checkout 与 refunds 不提供)。SDK 仅对 GET/DELETE 的 429/5xx 自动重试,POST/PATCH 不重试。
Webhook:回调优先级为 link > product > 钱包级回退。checkout 无 webhookUrl 字段,需在 product 上设置。签名密钥始终为钱包级 whsec_。用 verifyWebhook(rawBody, signature, secret) 验签(异步,容差 ±5 分钟),原始 body 只读一次。Webhook 路由须绕过项目自身鉴权,验签失败返回 400,临时失败返回 500,以 event.id 幂等,响应需在 10 秒内。
限制:密钥不得出现在响应、日志、D1、代码或浏览器端;Worker 中用 env 而非 process.env;不得在浏览器导入 SDK;successUrl/cancelUrl 仅作 UX 跳转,履约只能基于验证过的 Webhook;钱包级与退款、订阅变更、打款、KYC 等接口仅在有项目管理权限且用户明确要求时生成。本地开发无 WORKER_URL,需用隧道(cloudflared/ngrok)测试回调。