Skip to main content
Wallet Service 让 Agent 使用用户的 Clink 支付卡与购买授权。独立 Agent 和云端平台在完成 OAuth 连接后,使用相同的 MCP 工具。 当用户询问钱包、管理支付卡或建立购买授权时,使用本页工具。它们不是每次付款前都要执行的检查清单。 对于 Browser Pay 购买,get_credential 会根据结账总额处理授权匹配与准备;无需先调用 list_spendable_instructions 或 create_purchase_instruction。

理解三个层次

连接钱包并不代表用户批准了所有购买。创建 Instruction 也不代表已激活:只有状态为 ACTIVE、且包含适用 Mandate 的 Instruction 才能授权消费。

Passkey 与购买授权

Visa
当前 Visa 支付流程使用 Passkey 完成卡片的 Agent Pay 注册,并确认购买授权。首次设置时,用户可以在同一流程中完成注册与授权;仅完成卡片注册不会自动批准购买。这里的 Passkey 验证针对支付授权,OAuth 连接仍只负责工具访问权限。 用户在自己的设备上,通过指纹、面容或设备 PIN 等方式完成验证。Passkey 提供抗钓鱼的身份验证;使用生物识别时,指纹或面容数据在设备端处理,不会发送给远程服务器。详见 FIDO 的 Passkey 说明。 Clink 在签发支付凭证前,检查本次购买是否符合已生效授权的卡片、金额、币种、有效期等条件。已有有效授权覆盖本次购买时,无须每笔重新进行 Passkey 验证。 需要用户验证时,Agent 或平台将返回的操作链接展示给用户,由用户在自己的设备上完成。随后读取 Operation 和授权状态,再继续支付;Agent 不能代替用户完成 Passkey 确认。

查询钱包

用户询问有哪些卡、默认卡是哪张,或某张卡能否使用时,以 {} 调用 get_account_state。每次新的钱包问题都重新读取,因为用户可能在对话之外变更卡片或默认卡。 返回包含 paymentMethods、defaultPaymentInstrumentId 与 ready。展示卡片时使用 cardScheme 和 cardLastFour;调用工具时使用 paymentInstrumentId。

选择或管理支付卡

如果用户描述能匹配多张卡,先请用户确认。不要自动替用户修改默认卡。直接修改默认卡需要 wallet:read 和 wallet:setup;直接修改不可用时,提供用户自行操作的 set-default 流程。 start_payment_method_action 返回带有 REDIRECT_USER 动作的 Operation。将链接交给用户,由用户在自己的设备上打开。完成后用 get_operation 读取同一个 Operation,再重新调用 get_account_state。打开页面或从页面返回都不能证明操作已完成。

建立购买授权

用户明确希望建立授权,例如设置限定预算或周期消费时,使用 create_purchase_instruction。保留用户确定的用途、金额、币种和有效期,创建前读取已连接 MCP 服务端的当前规则。 根据用户意图选择流程: 如果用户希望单独预先授权,例如“为我下一次办公用品购买授权,限额 USD 25.00”,可使用下面的单次授权示例。月度场景则使用授权流程图后说明的周期字段:
每个新用户意图生成一个唯一 requestId。超时或完成准备步骤后,复用该 ID 及完全一致的原始参数。不要因为首次请求还在等待,就创建第二项授权。
Instruction 限额使用主货币单位的十进制字符串:"25.00" 表示 USD 25.00。Browser Pay 的 get_credential.amount 使用最小货币单位:2500 表示 USD 25.00。
用户先确认用途与消费上限,再在 Clink 授权页面按需添加卡片,并通过 Passkey 完成授权。随后读取同一个 operationId,并核验同一个 instructionId。 按返回的 next_action 继续:准备和授权可能需要多个用户动作。如果 Instruction 为 PENDING 且尚未绑定卡片,绑卡过程保持同一项 Instruction。CREATED、PENDING、读取失败,或用户说“已完成”,都不能证明授权已生效。 以返回的 effectiveUntilTime 为实际到期时间,服务可能限制有效期。周期授权需要 isRecurring: true,并在每条 Mandate 上设置 WEEKLY、MONTHLY 或 YEARLY 的 recurringFrequency;它允许限额内的周期消费,本身不会定时发起购买。

查询、修改或取消授权

  • 用 list_spendable_instructions 查找指定卡的有效授权。不传 paymentInstrumentId 时使用当前默认卡。有效授权仍需匹配购买用途、币种、限额、商户或品类及有效期。
  • 用 get_instruction 读取指定授权,核验激活或后续变更。
  • 用 start_instruction_action 的 action: "sign" 和 instructionId 获取已有授权的激活链接。
  • 用 action: "update" 或 "cancel" 打开用户自行管理授权的页面。这两种动作不传 Instruction ID,用户在页面上选择授权。操作后读取对应 Instruction,核验变更。
start_instruction_action 返回 { action, actor, url, ... },不是 Operation。其 actor 为 USER_DEVICE_ONLY,将 url 展示给用户即可。

注册与风控设置

用户明确要求注册 Agent Pay 时,用选定卡片的 paymentInstrumentId 调用 start_agent_pay_registration。跟进返回的 Operation,并确认同一张卡的 strongAuthRegistered: true。Browser Pay 和购买授权创建会处理各自的准备流程,不需要预先单独注册。 用 get_risk_rules 读取当前风控设置。需要修改时,调用 start_risk_rules_action,将返回链接交给用户。操作后再次读取 get_risk_rules 获取实际值;Operation 完成本身不能说明设置内容。

钱包工具参考

查看参数、Scope、返回字段与恢复方式。

继续接入 Browser Pay

获取凭证、提交支付并上报结果。