attach()、pay()、reconcile()、状态、错误和完整代码见 Agent Vault SDK 指南及 SDK API 参考。
Vault SDK 不需要终端用户 OAuth,也不连接用户 MCP。平台服务端使用 Clink 应用凭据通过 OAuth
client_credentials 调用 Vault;用户只在托管绑卡或商户验证需要时参与操作。1. 开通凭据并确认覆盖范围
SDK 运行在可信的平台服务或结账 worker 中,由它控制 Playwright 或 CDP 浏览器。Agent 和商户页面只能看到 SDK 提供的占位卡。 Vault SDK 使用 Pre-registration 签发的独立 Vaultclient_id 和 client_secret,申请方式见如何获取平台凭据。申请时还要说明目标商户或 PSP 场景。
Client Secret、
cardToken 和服务端卡片关联只保存在平台可信服务端。不要把它们暴露给模型、Agent 工具、浏览器存储、日志或用户消息。
2. 安装 SDK 并初始化客户端
运行时需要 Node.js>=20.19(ESM-only)。使用 Playwright Page 时还需要 Playwright >=1.40;只用原生 CDP 时不需要。
client_credentials 自动取得和刷新应用 Token,平台不需要自己调用 OAuth 接口。UAT 和 Production 分别创建客户端,不要共用凭据。
3. 规划要保存的用户和卡片数据
使用平台稳定用户 ID 作为externalUserId。不要把邮箱当作主键;用户改邮箱时不能静默地把卡关联到另一个平台用户。
用户改邮箱、删卡、冻结卡或合并账户时,
externalUserId、邮箱和 customerId 的匹配规则需要向 Clink 确认。不能从 SDK 方法名称自行推断。
绑卡 session 和支付窗口是 Vault 自己的托管流程:它们不是用户 OAuth,不能访问钱包的其他资料;支付窗口也不是 Browser Pay 的购买授权(Instruction)。同一个平台同时开通两条路径时,凭据、权限、用户动作、卡片标识和恢复方式分别管理,不要让两条路径同时处理同一个 checkout。
4. 绑卡或复用已有卡
回访用户从服务端读取已保存的customerId 和 cardToken。首次使用或支付窗口过期时,在 attach() 中传入 email:pay() 会返回带托管绑卡链接的 wait_user / bind_card,绑卡完成后由 onCardBound 返回卡片关联。也可以在结账前创建绑卡 session,等用户完成后再读取结果:
sessionId 和 url 不是卡凭据。只有 session 完成后才保存 customerId 和 cardToken:customerId 来自 sessions.create(),cardToken 来自已完成的 session。判断已保存关联能否复用时,以 SDK 返回的最新 expiresAt 和卡状态为准。
5. 挂载平台浏览器并完成支付
一个 checkout 对应一个由平台控制的浏览器任务和 checkout controller。传入平台用户关联,并实现投递用户操作和读取商户结果的回调:vault.attachToCdp()。不要在平台用户之间共享 controller、page session、customerId 或 cardToken。结账结束后关闭或 detach 当前 controller。
checkout.pay() 中,首次绑卡和支付窗口过期都会返回相同的 wait_user / bind_card 操作。平台需要:
- 将托管绑卡链接原样交给用户;
- 等待用户添加卡或重新输入 CVV;
- 保存
onCardBound返回的customerId/cardToken; - 使用 SDK 占位卡继续同一次 checkout。
6. 读取商户结果并 reconcile
平台通过resolveMerchantResult 读取商户订单结果;PSP Token 化响应或 SDK 状态本身不能证明订单已完成。使用 reconcile(),并按 Agent Vault SDK 指南区分完成、失败、等待、用户操作和未知结果。
商户结果等待中或需要用户操作时,保留同一个 checkout controller,等商户页面出现结果后再次调用 reconcile()。结果未知时,先核实原订单再做其他操作,不要换卡或开始第二笔支付。只有确认没有扣款后才调用 retry(),并且要在 detach() 之前调用。结账结束时调用 detach();它释放拦截资源,不会撤销已经发出的请求。
商户订单号与 Vault 标识分开保存。向用户展示的结果应以商户结果为准,不能只根据 PSP 响应或 Clink 上报结果判断。
相关文档
- 如何获取平台凭据:申请 Vault
client_id和client_secret。 - Agent Vault SDK 指南:SDK 行为、支付状态、PSP 覆盖和完整示例。
- SDK API 参考:方法、选项、返回值和错误码。
- 如何对接 MCP:通过 MCP + OAuth 接入 Browser Pay。
- 如何对接 RESTful API:通过 Customer Portal API 接入 Browser Pay。