跳转到主要内容
本页只说明 Agent Vault SDK 的平台适配层:服务端凭据、用户与卡片关联、浏览器边界和上线检查。Vault SDK 可以与 Browser Pay 在同一个平台共存,但每次支付尝试开始前要先选择一条路径。SDK 状态机和 PSP 行为不在这里重复。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 签发的独立 Vault client_id 和 client_secret,申请方式见如何获取平台凭据。申请时还要说明目标商户或 PSP 场景。 Client Secret、cardToken 和服务端卡片关联只保存在平台可信服务端。不要把它们暴露给模型、Agent 工具、浏览器存储、日志或用户消息。

2. 安装 SDK 并初始化客户端

运行时需要 Node.js >=20.19(ESM-only)。使用 Playwright Page 时还需要 Playwright >=1.40;只用原生 CDP 时不需要。
SDK 用这组凭据通过 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。传入平台用户关联,并实现投递用户操作和读取商户结果的回调:
使用原生 CDP 时调用 vault.attachToCdp()。不要在平台用户之间共享 controller、page session、customerId 或 cardToken。结账结束后关闭或 detach 当前 controller。 checkout.pay() 中,首次绑卡和支付窗口过期都会返回相同的 wait_user / bind_card 操作。平台需要:
  • 将托管绑卡链接原样交给用户;
  • 等待用户添加卡或重新输入 CVV;
  • 保存 onCardBound 返回的 customerId / cardToken;
  • 使用 SDK 占位卡继续同一次 checkout。
3DS、二维码和跳转操作属于当前商户浏览器或用户设备。平台按 SDK 返回内容投递,并按 Agent Vault SDK 指南继续和 reconcile 各种支付方式。

6. 读取商户结果并 reconcile

平台通过 resolveMerchantResult 读取商户订单结果;PSP Token 化响应或 SDK 状态本身不能证明订单已完成。使用 reconcile(),并按 Agent Vault SDK 指南区分完成、失败、等待、用户操作和未知结果。 商户结果等待中或需要用户操作时,保留同一个 checkout controller,等商户页面出现结果后再次调用 reconcile()。结果未知时,先核实原订单再做其他操作,不要换卡或开始第二笔支付。只有确认没有扣款后才调用 retry(),并且要在 detach() 之前调用。结账结束时调用 detach();它释放拦截资源,不会撤销已经发出的请求。 商户订单号与 Vault 标识分开保存。向用户展示的结果应以商户结果为准,不能只根据 PSP 响应或 Clink 上报结果判断。

相关文档