Skip to main content
这些工具通过用户已认证的 MCP 连接调用。业务流程见 Wallet Service,连接授权见 MCP 连接与 OAuth。工具名和参数名区分大小写。 以下 JSON 示例均为工具参数。例如,通过 MCP 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 与后续动作。