UCP Pay

UCP Pay 是 Clink 面向支持商户的 API 式结账流程，覆盖商品搜索、结账准备、用户授权、完成支付、读取订单和数字交付。

什么时候使用 UCP Pay

当商户支持 UCP，且结账需要结构化的商品、履约、订单或数字交付状态时，使用 UCP Pay。如果 Agent 需要操作普通商户网页，则使用 Browser Pay。

支付流程

使用 Catalog 工具搜索商品，或解析准确的商品 URL。
确认 SKU、选项、数量、价格、币种和履约信息。
调用 create_checkout，并根据 next_action 继续。
用户修改支持的结账信息时，使用 update_checkout。
使用当前确认标识调用一次 complete_checkout。
读取 UCP 订单；需要时等待数字交付。

时序图

UCP Checkout 使用独立的 Operation 和订单生命周期。UCP 支付不要调用 Browser Pay 的 confirm_result。

代码示例

下面按接入方式分别给出示例。MCP 使用 tools/call 调用 Clink 工具；RESTful API 使用平台对接的 HTTP 接口。两种方式都要使用上一步响应中的最新 operationId、actionId 和 revision，不能复用过期的确认标识。

MCP

搜索商品

{
  "name": "discover_catalog",
  "arguments": {
    "query": "咖啡券",
    "catalogLanguage": "zh-Hans",
    "limit": 5
  }
}

创建结账

{
  "name": "create_checkout",
  "arguments": {
    "merchantId": "merchant_example",
    "items": [
      {
        "productId": "product_example",
        "quantity": 1,
        "selected": {
          "size": "L"
        }
      }
    ],
    "fulfillmentType": "NO_SHIPPING_REQUIRED"
  }
}

更新结账并完成支付

当 next_action 要求补充配送信息时，使用当前版本更新：

{
  "name": "update_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<current_action_id>",
    "expectedRevision": "<current_revision>",
    "shippingAddress": {
      "name": "张三",
      "addressLine1": "示例路 1 号",
      "city": "上海",
      "postalCode": "200000",
      "country": "CN"
    }
  }
}

读取更新后的响应，使用最新确认标识完成结账：

{
  "name": "complete_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<latest_action_id>",
    "expectedRevision": "<latest_revision>",
    "maxWaitSeconds": 30
  }
}

读取订单和数字交付

{
  "name": "get_ucp_order",
  "arguments": {
    "orderId": "<ucp_order_id>"
  }
}

数字商品可以继续等待交付：

{
  "name": "wait_for_digital_delivery",
  "arguments": {
    "orderId": "<ucp_order_id>",
    "maxWaitSeconds": 120
  }
}

RESTful API

RESTful API 的接口地址和字段以平台开通的 UCP 服务为准。下面展示对应的 HTTP 调用形态；将 {UCP_API_BASE_URL}、{USER_ACCESS_TOKEN} 和响应中的占位 ID 替换为实际值。

搜索商品

curl -X POST "$UCP_API_BASE_URL/catalog/search" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "咖啡券",
    "catalogLanguage": "zh-Hans",
    "limit": 5
  }'

创建结账

curl -X POST "$UCP_API_BASE_URL/checkouts" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "merchant_example",
    "items": [
      {
        "product_id": "product_example",
        "quantity": 1,
        "selected": {
          "size": "L"
        }
      }
    ],
    "fulfillment_type": "NO_SHIPPING_REQUIRED"
  }'

更新并完成结账

curl -X PATCH "$UCP_API_BASE_URL/checkouts/<checkout_id>" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "<operation_id>",
    "action_id": "<current_action_id>",
    "expected_revision": "<current_revision>",
    "shipping_address": {
      "name": "张三",
      "address_line1": "示例路 1 号",
      "city": "上海",
      "postal_code": "200000",
      "country": "CN"
    }
  }'

curl -X POST "$UCP_API_BASE_URL/checkouts/<checkout_id>/complete" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "<operation_id>",
    "action_id": "<latest_action_id>",
    "expected_revision": "<latest_revision>"
  }'

读取订单和数字交付

curl "$UCP_API_BASE_URL/orders/<ucp_order_id>" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

curl "$UCP_API_BASE_URL/orders/<ucp_order_id>/digital-delivery?max_wait_seconds=120" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

字段、Scope 和恢复规则见 Catalog 与 UCP Checkout。

开始使用

接入

Agent 解决方案

配置与上线

介绍

财务信息

什么时候使用 UCP Pay

支付流程

时序图

代码示例

MCP

搜索商品

创建结账

更新结账并完成支付

读取订单和数字交付

RESTful API

搜索商品

创建结账

更新并完成结账

读取订单和数字交付

​什么时候使用 UCP Pay

​支付流程

​时序图

​代码示例

​MCP

​搜索商品

​创建结账

​更新结账并完成支付

​读取订单和数字交付

​RESTful API

​搜索商品

​创建结账

​更新并完成结账

​读取订单和数字交付

什么时候使用 UCP Pay

支付流程

时序图

代码示例

MCP

搜索商品

创建结账

更新结账并完成支付

读取订单和数字交付

RESTful API

搜索商品

创建结账

更新并完成结账

读取订单和数字交付