tools/call 调用 get_account_state:
structuredContent 读取成功的结构化结果。返回 isError: true 时,应处理错误,不能将其文本视为成功响应。启动流程的工具返回 Operation 封装,但 start_instruction_action 返回的是链接交接对象。
Scope 汇总
缺少权限时返回
insufficient scope: <scope> is required。在 OAuth Client 已登记的 Scope 范围内请求用户补充授权。events:read 和 events:consume 用于借助事件跟进流程,不能替代上表权限。
get_account_state
读取当前钱包。参数:{}。
每个
paymentMethods[] 包含:
用户每次重新询问钱包状态或选择卡片时,重新读取。不要用旧结果识别用户当前的卡片。使用默认卡购买不需要预先调用此工具。
set_default_card
仅在用户要求时修改钱包默认卡。先从新的get_account_state 结果中准确匹配一张卡。
paymentInstrumentId 必填,必须是非空字符串。返回 { changed, account }:account 结构与 get_account_state 相同,changed: false 表示该卡已经是默认卡。
卡片已不可用时,重新读取钱包。修改被拒绝或无法确认时,先刷新状态再告知用户;必要时提供 start_payment_method_action 的 set-default 流程。如果只是本次购买换卡,应把卡 ID 传给购买工具,而不是修改默认卡。
start_payment_method_action
启动由用户完成的卡片添加或管理流程。action 支持 add、replace、set-default、remove,默认值为 add。
返回带有 REDIRECT_USER 动作的 Operation。向用户展示 next_action.params.redirect_url;actor: "USER_DEVICE_ONLY" 表示用户必须在自己的设备上打开,Agent 不应预览该链接。此调用本身不会变更卡片。用户完成后读取同一个 Operation,再刷新 get_account_state。
create_purchase_instruction
创建购买授权草稿并启动激活流程,用于用户明确提出的授权管理。Browser Pay 应直接按结账事实调用get_credential,由其处理授权匹配与创建。
每条 Mandate 包含:
传入
shippingAddress 时,必填 name、line1、city、state、zip 和 countryCode: "US"。可选字段为 line2、line3 和对象类型的 deliveryContactDetails。
常规结果是 Operation。支持相应能力的 Host 也可能收到用于链接交互的 MCP input_required;保留协议请求状态,并以完全一致的原始参数继续。接受或打开链接不代表激活成功。
只有同一 ID、状态为
ACTIVE、已绑定卡片并包含适用 Mandate 的 Instruction 才能授权消费。Operation 完成不代表商户付款已经发生。
list_spendable_instructions
查询一张卡上包含可用 Mandate 的有效授权。paymentInstrumentId 可选,不传时使用当前默认卡;无法确定默认卡时返回空列表。结果为 { instructions: [...] },字段使用下文的 Instruction 结构。已使用或已占用的单次 Mandate 会被过滤。使用授权前仍需匹配购买用途、币种、金额、商户或品类及有效期;查询结果本身不代表用户批准一笔新购买。
get_instruction
读取指定授权的权威状态。instructionId 必填。主要返回字段如下:
除
instructionId 外,字段可能缺失或为 null。金额、卡 ID 或状态缺失时,不能视为有效授权。结果还可能包含提供方的其他字段。
start_instruction_action
获取由用户操作的签署、修改或取消授权链接。
修改或取消时,只传
{ "action": "update" } 或 { "action": "cancel" }。用户在管理页面中选择授权。
返回 { action, actor: "USER_DEVICE_ONLY", url },适用时还包含 instructionId 和 paymentInstrumentId。它不是 Operation:将 url 展示给用户,操作后用 get_instruction 核验相应授权。获取链接本身不会完成签署、修改或取消。
start_agent_pay_registration
为用户选定、且agent_pay_support: true 的卡启动独立注册流程。
paymentInstrumentId 必填。返回的 Operation 提供由用户在自己设备上打开的 Passkey 链接。之后读取同一个 Operation 或钱包;同一张卡的 strongAuthRegistered: true 才证明注册完成,strongAuthReady 和 authProtocol 不能替代它。
卡已注册时,不要重复发起注册。无法验证卡片归属或资格时,重新读取钱包。Browser Pay 和购买授权创建会在各自流程内处理准备步骤,此工具不是它们的前置条件。卡片具备 Agent Pay 能力本身不代表每一种支付场景都已可用。
风控设置
两个工具均以{} 为参数,需要 wallet:read。
具备事件权限时,Operation 可能确认发生过经过验证的保存。实际值始终以
get_risk_rules 为准,包括用户未作修改或未收到完成事件的情况。
通用等待、跳转与错误处理见 Operation 与后续动作。