> ## 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. # Browser Pay 工具 > 通过 Clink MCP 获取网页支付凭证，并上报商户支付结果。 这些工具用于商户网站上的银行卡付款。完整流程见 [Browser Pay](/cn/guides/agent/browser_pay)。示例展示 MCP `tools/call` 请求的 `name` 和 `arguments`；成功的工具数据位于 `structuredContent`。 | 工具 | 所需 OAuth Scope | | :- | :- | | `get_credential` | `payment:execute`、`wallet:read`、`instruction:read`、`instruction:write` | | `confirm_result` | `payment:execute` | ## get\_credential 为商户结账页的最终总额获取支付凭证。Clink 检查钱包卡和购买授权，返回凭证，或带有 [`next_action` 的 Operation](/cn/api-reference/mcp/operations)。 ### 参数 | 参数 | 必填 | 类型 | 含义 | | :- | :- | :- | :- | | `merchantUrl` | 是 | string | 使用域名的 HTTPS 结账页 URL，不得包含嵌入的凭据。Clink 保留其 origin。 | | `amount` | 是 | 正整数 | 包含运费和税费的最终总额，使用最小货币单位。USD 12.50 传 `1250`。 | | `currency` | 是 | string | 支持的三位 ISO 4217 币种代码，会转为大写。 | | `merchantName` | 否 | string | 商户名称，1–100 个字符。 | | `merchantCountryCode` | 否 | string | 已知时传入两位 ISO 3166-1 国家代码。 | | `paymentInstrumentId` | 否 | string | 用户为本次结账选择的支付卡。来自最新钱包数据，且 `agent_pay_support: true`。省略则使用默认卡，不会修改默认卡。 | | `products` | 否 | array | 1–50 条商品记录，结构见下表。 | | `shippingAddress` | 否 | object | 配送地址，结构见下文。 | 用户指定卡后，本次结账的后续调用都应保留相同的 `paymentInstrumentId`。无需在此调用前单独完成 Agent Pay 注册；需要时，返回的授权流程会处理注册。实际卡可用性以钱包和工具返回结果为准。 每条 `products` 记录包含： | 字段 | 必填 | 含义 | | :- | :- | :- | | `productId`、`productName` | 是 | 非空商品标识和名称。 | | `quantity` | 是 | 正数。 | | `unitPrice` | 是 | 非负单价，使用主货币单位，可传数字或十进制字符串。建议使用十进制字符串。 | | `currencyCode` | 是 | 三位币种代码。 | | `productUrl` | 否 | 商品 URL。 | | `extra` | 否 | 对象形式的商品补充信息。 | 传入 `shippingAddress` 时，需要包含 `street_address`、`address_locality`、`address_region`、`address_country`（两位代码）、`postal_code`、`first_name`、`last_name` 和 `phone_number`。`extended_address` 可选。使用已知的客户信息；信息不可用时，省略该可选对象。 ### 请求 ```json theme={null} { "name": "get_credential", "arguments": { "merchantUrl": "https://shop.example.com/checkout", "merchantName": "Example Store", "merchantCountryCode": "US", "amount": 1250, "currency": "USD", "products": [ { "productId": "item-001", "productName": "Example item", "quantity": 1, "unitPrice": "12.50", "currencyCode": "USD" } ] } } ``` ### 返回 返回结构采用 Operation envelope，还可能包含： | 字段 | 含义 | | :- | :- | | `credential` | 签发成功时出现，包含 `card`，或加密的 `key` / `payload`。 | | `credential.display` | 用于向用户展示的 `brand` 和可选 `last4`。 | | `credential.expires_at` | 估算过期时间，优先使用解密后的有效期信息。 | | `wallet_cards` | 当 `SETUP_REQUIRED` 要求设置 `DEFAULT_CARD` 时提供的可用卡列表。每项包含 `paymentInstrumentId`、可选 `cardScheme` 和 `cardLastFour`、`isDefault`、`agent_pay_support`。 | | `resources.payment_order_id` | 在凭证外部可用时返回的订单标识。 | | `resources.payment_execution_detail_id` | 在凭证外部可用时返回的执行明细标识。 | 以下示例展示 `structuredContent`；标识、URL、卡字段和密文均为占位值。 直接使用 `credential.card`。此返回仅确认凭证已签发，不代表商户支付结果。 ```json theme={null} { "operation_id": "op_example", "status": "SUCCEEDED", "revision": 2, "resources": { "payment_order_id": "order_example", "payment_execution_detail_id": "detail_example" }, "messages": [ { "code": "credential_issued", "text": "A single-use card credential was issued for this checkout. It is already decrypted: do not call decrypt_credential; fill credential.card into the checkout form, then report the merchant result with confirm_result." } ], "credential": { "orderId": "order_example", "paymentExecutionDetailId": "detail_example", "clientReferenceId": "op_example", "status": "COMPLETED", "card": { "number": "", "securityCode": "", "expiry": "12/30" }, "display": { "brand": "VISA", "last4": "1234" }, "expires_at": "2030-01-01T00:10:00Z" } } ``` 按[凭证解密示例](/cn/guides/agent/browser_pay/decryption)处理 `key` 和 `payload`，再使用得到的卡字段。 ```json theme={null} { "operation_id": "op_example", "status": "SUCCEEDED", "revision": 2, "resources": { "payment_order_id": "order_example", "payment_execution_detail_id": "detail_example" }, "messages": [ { "code": "credential_issued", "text": "A single-use card credential was issued for this checkout. It is encrypted: call decrypt_credential with credential.key and credential.payload unchanged to get the card, fill it into the checkout form, then report the merchant result with confirm_result." } ], "credential": { "key": "", "payload": "", "display": { "brand": "VISA", "last4": "1234" }, "expires_at": "2030-01-01T00:10:00Z" } } ``` 将返回的链接展示给用户，再通过 `get_operation` 读取 `op_setup_example`。后续返回见[设置完成示例](/cn/api-reference/mcp/operations#operation-envelope)。 ```json theme={null} { "operation_id": "op_setup_example", "status": "ACTION_REQUIRED", "revision": 1, "next_action": { "action_id": "act_example", "type": "REDIRECT_USER", "description": "Ask the buyer to activate the purchase instruction with their Passkey on their own device, then wait on this operation with get_operation maxWaitSeconds 60 in the same turn.", "params": { "redirect_url": "https://agent.example.com/authorize/pi_example?instructionId=ins_example", "redirect_kind": "PASSKEY", "actor": "USER_DEVICE_ONLY" }, "expected_revision": 1 }, "resources": { "instruction_id": "ins_example" }, "messages": [] } ``` 加密凭证的处理方式见[解密参考](/cn/guides/agent/browser_pay/decryption)。已解密的返回中，`credential` 直接包含 `card`、`orderId`、`paymentExecutionDetailId` 和 `clientReferenceId`。卡字段为 `number`、`securityCode`，以及可选的 `expiryMonth`、`expiryYear`、`expiry`、`dynamicDataType`、`dynamicDataId` 和 `dynamicDataExpiration`（字符串形式的 Unix 时间戳，单位为秒）。 负载还可能包含 `amount`（主货币单位）、`currencyCode`、`status`、`cardholderName`、`billingAddress`、`paymentExecutionId`、`paymentTransactionId`、`instructionId` 和 `mandateId`。 此处的 `SUCCEEDED` 仅确认凭证已签发，不代表商户支付成功。随后调用 `get_operation` 只能读取签发状态，不会返回凭证。观察到商户结果后调用 `confirm_result`；如果没有提交，则上报 `NOT_SUBMITTED`。 ### 继续流程与重试 用户完成授权或绑卡链接后，使用结账信息重复请求，不要传入设置操作的 `operationId`。若设置仍未完成，遵循当前 `next_action`。 最终上报前，重复相同结账信息会返回尚未处理的凭证。凭证在提交前过期时，相同请求可以为同一订单获取替换凭证。最终上报后，相同信息会开始新购买。此工具没有 `idempotencyKey` 参数。 为兼容早期返回的 `CONFIRM`，schema 还允许同时传入 `operationId`、`actionId` 和 `expectedRevision`，该形式不得包含任何结账字段。新接入使用上述结账信息流程；如果较早的签发 Operation 显示 `CONFIRM`，重复相同结账信息即可使用当前流程。 ## confirm\_result 记录 Agent 对 Browser Pay 支付的观察结果。该工具不会执行支付，也不会独立验证商户支付是否成功。不要用于 UCP Checkout 或直接支付。 ### 参数 | 参数 | 必填 | 类型 | 含义 | | :- | :- | :- | :- | | `orderId` | 是 | string | 签发负载的 `orderId`，或 `resources.payment_order_id`。 | | `paymentExecutionDetailId` | 是 | string | 签发负载的 `paymentExecutionDetailId`，或 `resources.payment_execution_detail_id`。 | | `operationId` | 是 | string | 签发本次凭证的 `get_credential` 返回中的 `operation_id`，也对应负载的 `clientReferenceId`。 | | `outcome` | 是 | enum | `SUCCEEDED`、`FAILED`、`NOT_SUBMITTED` 或 `UNKNOWN`，含义见下表。 | | `paidAmount` | 否 | 非负整数 | 商户成功页展示的金额，使用最小货币单位。必须与 `currency` 一起传入。 | | `currency` | 否 | string | 三位币种代码，必须与 `paidAmount` 一起传入。 | | `failureReason` | 否 | enum | 仅在 `FAILED` 或 `NOT_SUBMITTED` 时接受。 | | Outcome | 所需的观察依据 | | :- | :- | | `SUCCEEDED` | 商户明确确认支付成功。 | | `FAILED` | 提交后，商户明确展示失败。 | | `NOT_SUBMITTED` | 从未提交银行卡，可以在点击支付之前上报。 | | `UNKNOWN` | 已提交银行卡，但无法确定结果。 | `failureReason` 支持 `CARD_DECLINED`、`AUTHENTICATION_REQUIRED`、`AMOUNT_CHANGED`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_LOST`、`MERCHANT_ERROR`、`BUYER_CANCELLED` 和 `OTHER`。 以下为上述凭证对应的不同上报情形。只有商户明确确认付款后，才能上报成功。 使用签发凭证时返回的标识，不要使用设置操作的标识。 ```json theme={null} { "name": "confirm_result", "arguments": { "orderId": "order_example", "paymentExecutionDetailId": "detail_example", "operationId": "op_example", "outcome": "SUCCEEDED", "paidAmount": 1250, "currency": "USD" } } ``` 此 `structuredContent` 返回表示已记录 Agent 的报告，不是独立的付款确认。 ```json theme={null} { "payment_order_id": "order_example", "payment_execution_detail_id": "detail_example", "status": "SUCCEEDED", "messages": [ { "code": "agent_reported_result", "text": "Result reported by the agent; not confirmed by the card network." } ] } ``` 如果总额在提交前发生变化，应改为上报 `NOT_SUBMITTED`。 ```json theme={null} { "name": "confirm_result", "arguments": { "orderId": "order_example", "paymentExecutionDetailId": "detail_example", "operationId": "op_example", "outcome": "NOT_SUBMITTED", "failureReason": "AMOUNT_CHANGED" } } ``` ### 返回与上报规则 该工具返回结果报告，不是 Operation envelope： | 字段 | 含义 | | :- | :- | | `payment_order_id`、`payment_execution_detail_id` | 支付标识。 | | `status` | 已记录的结果状态：`SUCCEEDED`、`FAILED` 或 `PENDING`。 | | `report_deadline` | 在待定报告中返回时，表示补报最终结果的截止时间。 | | `messages` | 解释消息，包含 `agent_reported_result`。 | 上报 `UNKNOWN` 后，查看商户已有交易，并在 `report_deadline` 前补报最终结果，不要再次付款。相同结果可以重报；已有最终结果后，冲突的最终结果会被拒绝。若 `messages` 包含 `paid_amount_mismatch`，表示上报金额与 Clink 记录不同，且没有覆盖 Clink 的记录。 ## 错误与恢复 Browser Pay 业务拒绝返回 `isError: true`，以及包含 `code` 和 `message` 的 `structuredContent.error`，不携带 `next_action`。缺少 Scope 时可能只返回文本工具错误，详见[通用错误处理](/cn/api-reference/mcp/operations#错误)。 | Code | 恢复方式 | | :- | :- | | `invalid_merchant_url` | 使用真实 HTTPS 结账 URL，要求域名且不含嵌入的凭据。 | | `unsupported_currency` | 检查结账币种及支持的 ISO 4217 代码。 | | `card_unavailable`、`card_not_supported` | 刷新 `get_account_state`，让用户重新选择可用且受支持的卡，不要擅自换卡。 | | `encryption_key_unavailable` | 平台联系 Clink 完成公钥配置。 | | `credential_outstanding` | 先处理并上报已有结账，再发起另一笔。原结账信息可以恢复其凭证。 | | `issuance_incomplete` | 使用完全相同的结账信息重试 `get_credential`。 | | `credential_unavailable` | 检查是否已经上报最终结果。如果从未提交银行卡，使用已知标识上报 `NOT_SUBMITTED`，原因为 `CREDENTIAL_EXPIRED` 或 `CREDENTIAL_LOST`。不能据此认定已提交的付款失败。 | | `action_not_claimable` | 读取同一 Operation 并遵循当前 `next_action`，不要重放过期操作。 | | `not_browser_pay_payment`、`order_not_found` | 核对三个标识是否都来自当前用户的同一次 Browser Pay 凭证签发。 | | `result_already_reported` | 已有不同的最终结果，查看已有记录，不要覆盖或再次付款。 | | `report_window_expired` | 上报窗口已关闭，支付已转入人工复核。 | | `result_reporting_unavailable` | 未能确认上报结果。稍后重试相同报告，不要再次提交支付。 | | `browser_pay_unavailable` | 当前部署无法提供 Browser Pay，检查环境及可用支付能力。 | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.