Skip to main content
Browser Pay 让 Agent 使用 Clink 签发的支付凭证,在商户网站的银行卡结账页面完成付款。商户无需预先注册到 Clink。Agent 操作商户网页;Clink 负责钱包、购买授权和凭证签发。 开始前,请连接 MCP 并读取当前业务规则。用户需要已授权购买及其预算范围,并满足以下条件:
  • 支付卡。 当前钱包返回的 agent_pay_support 表示卡片是否具备 Agent Pay 能力;商户或发卡行仍可能拒绝本次付款。
  • 商户结账页。 Agent 能读取最终总额、填写卡表单及嵌入的支付字段、提交付款,并查看商户的支付或订单结果。
  • 用户验证。 用户能完成银行要求的验证,例如 3-D Secure 或一次性验证码。
收到加密凭证的平台还需要实现凭证解密。

支付流程

有效的购买授权覆盖本次付款时,get_credential 可以直接返回凭证。直接使用 credential.card;仅当返回 key 和 payload 时执行解密。
图中展示成功路径。未提交银行卡时,上报 NOT_SUBMITTED;已经提交但无法确认结果时,上报 UNKNOWN。

1. 读取结账最终金额

使用商户结账页展示的最终总额,包含运费和税费。不要使用商品标价,也不要将用户的最高预算当作付款金额。联系人和配送信息来自用户或其商户账户。 选择网站的银行卡付款选项,关闭保存支付信息的选项。如果用户指定使用某张钱包卡,先通过最新的 get_account_state 获取其 paymentInstrumentId,并检查 agent_pay_support: true;否则省略卡选择参数,使用默认卡。

2. 获取支付凭证

以下是一个 tools/call 请求。结账总额为 USD 12.50 时,传入 amount: 1250:
需要的 Scope 为 wallet:read、payment:execute、instruction:read 和 instruction:write。 Clink 检查支付卡并匹配有效的购买授权。已有授权覆盖本次付款时,可以在本次调用中直接返回凭证;否则,可以为当前结账发起一次性授权。无需在每次 Browser Pay 调用前先查询或创建购买授权。 按实际返回内容处理: 当跳转返回 actor: "USER_DEVICE_ONLY" 时,由用户在自己的设备上打开链接。Agent 不应在自己的浏览器中打开或预览。提供 Passkey 或绑卡链接后,等待同一个设置 Operation:
设置完成后,使用结账信息再次调用 get_credential,不要传入设置操作的 operationId。如果用户为本次结账指定了卡,每次调用都保留相同的 paymentInstrumentId;如果用户选择修改默认卡,先调用 set_default_card,再省略卡选择参数重试。 打开链接不代表授权已完成。返回内容仍要求操作时,继续遵循当前 next_action。

3. 读取或解密凭证

根据实际返回形态处理,不要假设所有客户端都收到同一种结果: 云端平台通过线下联系 Clink 配置公钥,详见平台接入。

支付凭证如何受到保护

Visa
当前 Visa 路径使用 Token 化卡号和动态安全码填写商户卡表单。Token 化卡号替代用户原始卡号,动态安全码有有效期;使用实际返回的凭证及到期信息完成本次结账。 平台收到 key 与 payload 时,凭证另经平台公钥加密,使用对应私钥解密后读取卡字段。这层保护用于凭证交付;购买范围由 Passkey 确认的购买授权决定。直接返回 credential.card 时,同样需要遵守授权范围和凭证有效期。

保留支付标识

保留以下标识用于结果上报: orderId 标识 Clink 的支付订单,不是商户订单号。商户返回订单号时,单独保留该商户订单号。
get_credential Operation 的 status: "SUCCEEDED" 表示凭证已签发,不代表商户已收款。get_operation 不会返回凭证,也不能独立核实商户的支付结果。
get_credential.amount 和 confirm_result.paidAmount 使用最小货币单位;凭证负载的 amount 使用主货币单位。例如 USD 12.50 分别表示为 1250 和 12.50。请按币种精度转换,不要对所有币种统一乘以 100。

4. 填写并提交商户支付

将返回的卡号、有效期和安全码填写到当前结账页的银行卡字段,包括嵌入页面的支付服务商字段。有效期格式以表单要求为准。返回 cardholderName 和 billingAddress 时使用它们;缺少账单信息时向用户获取,不要自行编造。 在凭证有效期内使用。解密后的有效期信息及 ttlMinutes(如有)优先于外层 credential.expires_at 的估算值。 提交前再次核对总额:
  • 总额未变:提交并查看商户结果。需要 3-D Secure 或一次性验证码时,由用户完成。
  • 总额变化:不要提交旧凭证。上报 NOT_SUBMITTED 和 failureReason: "AMOUNT_CHANGED",再在用户授权范围内按新总额获取凭证。
卡信息仅用于本次结账的支付字段,不要写入聊天、日志或保存的笔记。向用户描述支付卡时,使用 credential.display。

5. 上报实际观察到的结果

使用第 3 步保留的标识,通过 confirm_result 上报本次 Browser Pay 支付。以下示例表示已观察到支付成功:
成功页展示实际付款金额时,同时传入 paidAmount 和 currency。failureReason 仅适用于 FAILED 和 NOT_SUBMITTED,详见完整参数参考。 对于 UNKNOWN,保留支付标识,查看商户已有订单或支付结果,不要再次付款。在返回的 report_deadline 前补报最终结果。相同结果可以安全重报;冲突的最终结果会被拒绝。 Clink 记录 Agent 的报告,并返回 agent_reported_result 消息。该记录不是商户的独立确认。本流程的退款由商户处理。 根据商户页面实际展示的信息,向用户简要说明结果。例如,页面已确认以下信息时:
Example Store 已确认支付 USD 12.50。商户订单号:EX-1042。
如果页面没有展示商户订单号,就省略该项,不要编造或用 Clink 的 orderId 替代。

恢复流程,避免重复购买

confirm_result 仅用于 Browser Pay。UCP Checkout 和直接支付通过各自工具取得结果,不应通过该接口上报。 字段约束和错误码见 Browser Pay 工具及 Operation 与恢复。