> ## 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.

# UCP Pay

> 使用 Clink UCP 完成商品结账。

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

## 什么时候使用 UCP Pay

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

## 支付流程

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

### 时序图

```mermaid theme={null}
sequenceDiagram
  participant U as 用户
  participant A as Agent
  participant M as Clink MCP
  participant C as Catalog / UCP 商户
  participant O as Operation

  U->>A: 搜索商品或提供商品 URL
  A->>M: discover_catalog / get_product / parse_product_item
  M->>C: 查询商品与价格
  C-->>M: 商品、SKU、选项与履约信息
  M-->>A: 返回商品详情
  A-->>U: 展示商品与价格
  U->>A: 确认商品和结账信息
  A->>M: create_checkout
  M->>O: 创建 Checkout Operation
  O-->>M: next_action / checkout 摘要
  M-->>A: 返回结账状态

  alt 需要补充或修改结账信息
    A-->>U: 请求收货地址或其他必需信息
    U->>A: 提供信息
    A->>M: update_checkout
    M->>O: 更新 Operation 与确认版本
    O-->>M: 新的 next_action / 摘要
    M-->>A: 返回更新后的结账状态
  end

  alt 需要用户授权或确认
    A-->>U: 展示授权链接或确认摘要
    U->>A: 完成授权或确认
  end

  A->>M: complete_checkout
  M->>O: 完成当前确认
  O->>C: 执行支付与订单创建
  C-->>O: 支付与订单结果
  O-->>M: 终态或等待状态
  M-->>A: 返回 Operation 结果
  A->>M: get_ucp_order / get_order
  M-->>A: 返回订单与履约状态

  opt 数字商品
    A->>M: wait_for_digital_delivery
    M-->>A: 交付就绪或有界等待结果
  end
  A-->>U: 报告支付、订单和交付结果
```

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

## 代码示例

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

### MCP

#### 搜索商品

```json theme={null}
{
  "name": "discover_catalog",
  "arguments": {
    "query": "咖啡券",
    "catalogLanguage": "zh-Hans",
    "limit": 5
  }
}
```

#### 创建结账

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

#### 更新结账并完成支付

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

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

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

```json theme={null}
{
  "name": "complete_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<latest_action_id>",
    "expectedRevision": "<latest_revision>",
    "maxWaitSeconds": 30
  }
}
```

#### 读取订单和数字交付

```json theme={null}
{
  "name": "get_ucp_order",
  "arguments": {
    "orderId": "<ucp_order_id>"
  }
}
```

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

```json theme={null}
{
  "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 替换为实际值。

#### 搜索商品

```bash theme={null}
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
  }'
```

#### 创建结账

```bash theme={null}
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"
  }'
```

#### 更新并完成结账

```bash theme={null}
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"
    }
  }'
```

```bash theme={null}
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>"
  }'
```

#### 读取订单和数字交付

```bash theme={null}
curl "$UCP_API_BASE_URL/orders/<ucp_order_id>" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

```bash theme={null}
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](https://docs.clinkbill.com/cn/api-reference/mcp/commerce.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.