> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP结账API与状态机流转详解

> 详解UCP结账API与状态机流转机制，包括结账会话从incomplete到completed六个状态的完整生命周期、Create/Get/Update/Complete/Cancel五种核心操作接口、ISO 4217最小货币单位金额处理规范及嵌入式UI集成方式，指导开发者在AI代理购物场景中实现安全可靠的结账支付流程

# 结账 API

## 2.1 能力标识

结账能力的命名空间为 `dev.ucp.shopping.checkout`，是UCP最核心的交易能力。它定义了从创建购物会话到完成支付的完整流程。

## 2.2 结账会话状态机

一个结账会话（Checkout Session）在其生命周期内经历6个明确的状态：

| 状态                     | 含义                         | 可转换到                                                    |
| ---------------------- | -------------------------- | ------------------------------------------------------- |
| `incomplete`           | 会话已创建，买家信息或商品信息不完整         | `requires_escalation`, `ready_for_complete`, `canceled` |
| `requires_escalation`  | 需要人工介入处理（年龄验证、高风险审核、库存确认等） | `incomplete`, `ready_for_complete`, `canceled`          |
| `ready_for_complete`   | 所有必要信息已就绪，可以提交完成           | `complete_in_progress`, `canceled`                      |
| `complete_in_progress` | Complete操作已提交，正在处理中        | `completed`, `incomplete`                               |
| `completed`            | 交易成功完成，订单已创建               | 终态                                                      |
| `canceled`             | 交易已取消                      | 终态                                                      |

```text theme={null}
状态流转图:

  incomplete ──────→ requires_escalation
      │                    │
      ├──────→ ready_for_complete ←──┘
      │              │
      │        complete_in_progress
      │              │
      │          completed (终态)
      │
      └──────→ canceled (终态)
```

**关键设计**: `requires_escalation` 状态允许商家在AI无法自动处理的场景下将控制权交给人类（例如需要法律合规确认的高价商品）。`complete_in_progress` 到 `incomplete` 的回退路径处理支付失败等异常场景。

## 2.3 五种操作

### Create — 创建结账会话

```http theme={null}
POST /ucp/checkout/sessions
Content-Type: application/json
Authorization: Bearer {access_token}
UCP-Agent: profile="https://agent.example/profiles/shopping.json"

{
  "line_items": [
    {
      "product_id": "prod_abc123",
      "variant_id": "var_001",
      "quantity": 2
    }
  ],
  "buyer": {
    "email": "buyer@example.com"
  }
}
```

响应：

```json theme={null}
{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "incomplete",
    "created_at": "2026-04-11T10:00:00Z",
    "line_items": [
      {
        "id": "li_001",
        "product_id": "prod_abc123",
        "variant_id": "var_001",
        "name": "经典帆布运动鞋 - 白色 42码",
        "quantity": 2,
        "unit_price": {
          "amount": 29900,
          "currency_code": "CNY"
        },
        "line_total": {
          "amount": 59800,
          "currency_code": "CNY"
        }
      }
    ],
    "pricing": {
      "subtotal": { "amount": 59800, "currency_code": "CNY" },
      "shipping": null,
      "tax": null,
      "total": { "amount": 59800, "currency_code": "CNY" }
    }
  }
}
```

### Get — 查询结账会话

```http theme={null}
GET /ucp/checkout/sessions/{session_id}
Authorization: Bearer {access_token}
```

返回会话的当前完整状态，包括所有行项目、定价、买家信息和配送选项。

### Update — 更新结账会话

```http theme={null}
PATCH /ucp/checkout/sessions/{session_id}
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "buyer": {
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "+86-138-0000-0000",
    "shipping_address": {
      "line1": "朝阳区xxx路xxx号",
      "city": "北京",
      "state": "北京市",
      "postal_code": "100000",
      "country_code": "CN"
    }
  },
  "fulfillment": {
    "method": "standard_shipping"
  },
  "payment": {
    "handler": "com.stripe.payment",
    "token": "tok_xxxxxxxxxxxx"
  }
}
```

Update操作可以多次调用，逐步补充信息。当所有必要信息就绪后，状态自动转为 `ready_for_complete`。

### Complete — 提交完成

```http theme={null}
POST /ucp/checkout/sessions/{session_id}/complete
Authorization: Bearer {access_token}
```

仅当状态为 `ready_for_complete` 时可调用。调用后状态变为 `complete_in_progress`，商家异步处理支付和订单创建。成功后状态变为 `completed`，失败则回退到 `incomplete`。

响应：

```json theme={null}
{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "complete_in_progress",
    "order_id": null
  }
}
```

完成后的最终响应（通过Get查询或Webhook回调）：

```json theme={null}
{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "completed",
    "order_id": "ord_20260411_xyz789",
    "completed_at": "2026-04-11T10:05:00Z"
  }
}
```

### Cancel — 取消会话

```http theme={null}
POST /ucp/checkout/sessions/{session_id}/cancel
Authorization: Bearer {access_token}

{
  "reason": "buyer_changed_mind"
}
```

除了 `completed` 和 `canceled` 两个终态外，任何状态都可以取消。

## 2.4 ISO 4217 金额处理

UCP严格要求所有金额使用 **ISO 4217最小货币单位**（minor units）表示，避免浮点数精度问题：

| 货币     | currency\_code | 最小单位       | 299元的表示  |
| ------ | -------------- | ---------- | -------- |
| 人民币    | `CNY`          | 分（1/100）   | `29900`  |
| 美元     | `USD`          | 美分（1/100）  | `29900`  |
| 日元     | `JPY`          | 円（无小数）     | `299`    |
| 科威特第纳尔 | `KWD`          | 费尔（1/1000） | `299000` |

```json theme={null}
{
  "amount": 29900,
  "currency_code": "CNY"
}
```

**开发注意**: 不同货币的最小单位指数不同。CNY和USD是2位（除以100），JPY是0位（直接使用），KWD是3位（除以1000）。实现时务必参考ISO 4217的exponent定义。

## 2.5 嵌入式结账UI

当AI代理无法在纯API模式下完成结账（例如复杂的支付验证、3D Secure认证），UCP支持嵌入式UI模式：

| 模式        | 说明                      | 适用场景        |
| --------- | ----------------------- | ----------- |
| **API模式** | AI代理通过REST/MCP直接完成全部操作  | 简单结账、已关联身份  |
| **嵌入式UI** | 商家提供结账页面URL，AI代理嵌入展示给用户 | 复杂支付验证、首次授权 |

嵌入式UI通过 `requires_escalation` 状态触发。商家在响应中返回UI URL：

```json theme={null}
{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "requires_escalation",
    "escalation": {
      "type": "embedded_ui",
      "url": "https://store.example.com/checkout/embed/cs_20260411_abc123",
      "reason": "payment_verification_required"
    }
  }
}
```

嵌入式UI支持双向通信，用户在商家页面完成操作后，状态自动更新。

## 2.6 价格透明要求

UCP要求所有价格信息必须完全透明。在结账会话中，定价对象必须包含：

| 字段         | 说明   | 是否必须       |
| ---------- | ---- | ---------- |
| `subtotal` | 商品小计 | 是          |
| `shipping` | 运费   | 是（可为0）     |
| `tax`      | 税费   | 是（可为0）     |
| `discount` | 折扣   | 条件（有折扣时必须） |
| `total`    | 最终总价 | 是          |

AI代理在调用Complete操作前，**必须**向消费者展示完整的价格明细并获得确认。

***

**下一章**: [身份关联](/zh/book-3/ch3-identity) — OAuth 2.0 Authorization Code流程、令牌撤销和scope管理