> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt > Use this file to discover all available pages before exploring further. # Wallet Service > 查询用户钱包、管理支付卡，并建立购买授权。 Wallet Service 让 Agent 使用用户的 Clink 支付卡与购买授权。独立 Agent 和云端平台在[完成 OAuth 连接](/cn/guides/agent/mcp_integration)后，使用相同的 MCP 工具。 当用户询问钱包、管理支付卡或建立购买授权时，使用本页工具。**它们不是每次付款前都要执行的检查清单。** 对于 [Browser Pay](/cn/guides/agent/browser_pay) 购买，`get_credential` 会根据结账总额处理授权匹配与准备；无需先调用 `list_spendable_instructions` 或 `create_purchase_instruction`。 ## 理解三个层次 | 层次 | 允许什么 | 如何建立 | | :- | :- | :- | | OAuth 连接 | Agent 在已授予的 Scope 内，为特定用户调用工具。 | 用户在 Agent Host 或平台中连接 Clink。 | | 支付卡 | 确定购买使用哪张钱包卡付款。 | 用户添加卡片，并在需要时完成 Agent Pay 注册。 | | 购买授权（Instruction） | 记录用户批准的用途与消费限制，其中包含一条或多条 Mandate。 | 用户在 Clink 授权页面激活。 | 连接钱包并不代表用户批准了所有购买。创建 Instruction 也不代表已激活：只有状态为 `ACTIVE`、且包含适用 Mandate 的 Instruction 才能授权消费。 ## Passkey 与购买授权
Visa
当前 Visa 支付流程使用 Passkey 完成卡片的 Agent Pay 注册，并确认购买授权。首次设置时，用户可以在同一流程中完成注册与授权；仅完成卡片注册不会自动批准购买。这里的 Passkey 验证针对支付授权，OAuth 连接仍只负责工具访问权限。 用户在自己的设备上，通过指纹、面容或设备 PIN 等方式完成验证。Passkey 提供抗钓鱼的身份验证；使用生物识别时，指纹或面容数据在设备端处理，不会发送给远程服务器。详见 [FIDO 的 Passkey 说明](https://fidoalliance.org/passkeys/)。 ```mermaid theme={null} %%{init: {"theme":"base","themeVariables":{"fontFamily":"inherit","fontSize":"14px","primaryColor":"#F7F7F7","primaryTextColor":"#161616","primaryBorderColor":"#E7E7E7","lineColor":"#71717A","edgeLabelBackground":"#FFFFFF"},"flowchart":{"nodeSpacing":40,"rankSpacing":38,"padding":14,"diagramPadding":12}}}%% flowchart TD U["用户
Passkey 确认"] --> I["已生效的购买授权
用途与消费限制"] I --> C["Clink
校验限制并签发凭证"] A["Agent
本次购买请求"] --> C classDef emphasis fill:#F8E1CC,stroke:#F8E1CC,color:#161616 class C emphasis ``` Clink 在签发支付凭证前，检查本次购买是否符合已生效授权的卡片、金额、币种、有效期等条件。**已有有效授权覆盖本次购买时，无须每笔重新进行 Passkey 验证。** 需要用户验证时，Agent 或平台将返回的操作链接展示给用户，由用户在自己的设备上完成。随后读取 Operation 和授权状态，再继续支付；Agent 不能代替用户完成 Passkey 确认。 ## 查询钱包 用户询问有哪些卡、默认卡是哪张，或某张卡能否使用时，以 `{}` 调用 `get_account_state`。每次新的钱包问题都重新读取，因为用户可能在对话之外变更卡片或默认卡。 返回包含 `paymentMethods`、`defaultPaymentInstrumentId` 与 `ready`。展示卡片时使用 `cardScheme` 和 `cardLastFour`；调用工具时使用 `paymentInstrumentId`。 | 字段 | 含义 | | :- | :- | | `ready` | 存在可用支付方式。它不代表默认卡支持 Browser Pay，也不代表某笔购买已经获准。 | | `agent_pay_support` | 当前钱包返回表明该卡具备 Agent Pay 能力。不要仅凭卡品牌推断是否可用。 | | `strongAuthRegistered` | 该卡已完成 Agent Pay 注册。 | | `strongAuthReady`、`authProtocol` | 当前设备的认证信息，不能替代 `strongAuthRegistered`。 | | `blockedReason: "NO_PAYMENT_METHOD"` | 没有可用支付方式，可引导用户添加卡片。 | ## 选择或管理支付卡 | 用户意图 | 操作 | | :- | :- | | “这次用尾号 4242 的卡付款。” | 查询钱包，准确匹配一张卡，将其 `paymentInstrumentId` 传给 `get_credential`。保持钱包默认卡不变。 | | “把这张卡设为默认卡。” | 查询钱包并确认卡片，然后调用 `set_default_card`。根据返回的 `account` 告知结果。 | | “添加、更换或删除一张卡。” | 调用 `start_payment_method_action`，`action` 分别为 `"add"`、`"replace"` 或 `"remove"`。 | | “让我自己选择默认卡。” | 调用 `start_payment_method_action`，传入 `action: "set-default"`。 | 如果用户描述能匹配多张卡，先请用户确认。不要自动替用户修改默认卡。直接修改默认卡需要 `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。” | 以结账最终金额调用 `get_credential`，按返回完成本次授权，无需预先单独创建授权。 | | “为后续办公用品采购设置一项月度授权。” | 与用户确认用途、限额、币种、周期和有效期，再创建周期授权，由用户激活。每次购买仍须符合已生效授权的条件。 | 如果用户希望单独预先授权，例如“为我下一次办公用品购买授权，限额 USD 25.00”，可使用下面的单次授权示例。月度场景则使用授权流程图后说明的周期字段： ```json theme={null} { "requestId": "wallet-budget-example-001", "title": "Office supplies budget", "isRecurring": false, "mandates": [ { "description": "Purchase office supplies within the approved budget", "amountLimit": "25.00", "currencyCode": "USD" } ] } ``` 每个新用户意图生成一个唯一 `requestId`。超时或完成准备步骤后，复用该 ID **及完全一致的原始参数**。不要因为首次请求还在等待，就创建第二项授权。 Instruction 限额使用**主货币单位**的十进制字符串：`"25.00"` 表示 USD 25.00。Browser Pay 的 `get_credential.amount` 使用**最小货币单位**：`2500` 表示 USD 25.00。 用户先确认用途与消费上限，再在 Clink 授权页面按需添加卡片，并通过 Passkey 完成授权。随后读取同一个 `operationId`，并核验同一个 `instructionId`。 ```mermaid theme={null} %%{init: {"theme":"base","themeVariables":{"fontFamily":"inherit","actorBkg":"#F7F7F7","actorBorder":"#E7E7E7","actorTextColor":"#161616","actorLineColor":"#E7E7E7","signalColor":"#71717A","signalTextColor":"#3F3F46","noteBkgColor":"#F8E1CC","noteBorderColor":"#F8E1CC","noteTextColor":"#161616"},"sequence":{"width":116,"height":44,"actorMargin":64,"diagramMarginX":12,"diagramMarginY":12,"messageMargin":28,"noteMargin":14,"boxMargin":12,"wrap":false,"mirrorActors":false,"actorFontSize":14,"messageFontSize":14,"noteFontSize":14}}}%% sequenceDiagram participant U as 用户 participant A as Agent participant C as Clink U->>A: 确认授权范围 A->>C: create_purchase_instruction C-->>A: Operation + 用户动作 A-->>U: 授权链接 Note over U: Passkey 授权 U->>C: 完成授权 A->>C: get_operation C-->>A: 更新后的状态 A->>C: get_instruction C-->>A: ACTIVE + 支付卡与 Mandate A-->>U: 授权已就绪 ``` 按返回的 `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、返回字段与恢复方式。 获取凭证、提交支付并上报结果。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.