Browser Pay 工具

这些工具用于商户网站上的银行卡付款。完整流程见 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。

参数

参数	必填	类型	含义
`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 可选。使用已知的客户信息；信息不可用时，省略该可选对象。

请求

{
  "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。此返回仅确认凭证已签发，不代表商户支付结果。

{
  "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": "<tokenized card number>",
      "securityCode": "<dynamic security code>",
      "expiry": "12/30"
    },
    "display": {
      "brand": "VISA",
      "last4": "1234"
    },
    "expires_at": "2030-01-01T00:10:00Z"
  }
}

按凭证解密示例处理 key 和 payload，再使用得到的卡字段。

{
  "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": "<base64 wrapped key>",
    "payload": "<base64 sealed payload>",
    "display": {
      "brand": "VISA",
      "last4": "1234"
    },
    "expires_at": "2030-01-01T00:10:00Z"
  }
}

将返回的链接展示给用户，再通过 get_operation 读取 op_setup_example。后续返回见设置完成示例。

{
  "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": []
}

加密凭证的处理方式见解密参考。已解密的返回中，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。以下为上述凭证对应的不同上报情形。只有商户明确确认付款后，才能上报成功。

上报成功
上报已记录
总额发生变化

使用签发凭证时返回的标识，不要使用设置操作的标识。

{
  "name": "confirm_result",
  "arguments": {
    "orderId": "order_example",
    "paymentExecutionDetailId": "detail_example",
    "operationId": "op_example",
    "outcome": "SUCCEEDED",
    "paidAmount": 1250,
    "currency": "USD"
  }
}

此 structuredContent 返回表示已记录 Agent 的报告，不是独立的付款确认。

{
  "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。

{
  "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 时可能只返回文本工具错误，详见通用错误处理。

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，检查环境及可用支付能力。

概述

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

get_credential

参数

请求

返回

继续流程与重试

confirm_result

参数

返回与上报规则

错误与恢复

​get_credential

​参数

​请求

​返回

​继续流程与重试

​confirm_result

​参数

​返回与上报规则

​错误与恢复

get_credential

参数

请求

返回

继续流程与重试

confirm_result

参数

返回与上报规则

错误与恢复