结账 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`	交易已取消	终态

状态流转图:

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

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

2.3 五种操作

Create — 创建结账会话

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"
  }
}

响应：

{
  "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 — 查询结账会话

GET /ucp/checkout/sessions/{session_id}
Authorization: Bearer {access_token}

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

Update — 更新结账会话

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 — 提交完成

POST /ucp/checkout/sessions/{session_id}/complete
Authorization: Bearer {access_token}

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

{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "complete_in_progress",
    "order_id": null
  }
}

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

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

Cancel — 取消会话

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`

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

{
  "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操作前，必须向消费者展示完整的价格明细并获得确认。

下一章: 身份关联 — OAuth 2.0 Authorization Code流程、令牌撤销和scope管理

UCP协议架构与核心概念详解 UCP OAuth 2.0身份关联机制

开始

学习路径

AI代理商务入门

OTR 开放信任协议

UCP 通用商务协议

ACP 代理商务协议

MCP 模型上下文协议

AI时代的SEO

ORBEXA 一体化方案

模板与提示词

术语词典

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

结账 API

2.1 能力标识

2.2 结账会话状态机

2.3 五种操作

Create — 创建结账会话

Get — 查询结账会话

Update — 更新结账会话

Complete — 提交完成

Cancel — 取消会话

2.4 ISO 4217 金额处理

2.5 嵌入式结账UI

2.6 价格透明要求

​结账 API

​2.1 能力标识

​2.2 结账会话状态机

​2.3 五种操作

​Create — 创建结账会话

​Get — 查询结账会话

​Update — 更新结账会话

​Complete — 提交完成

​Cancel — 取消会话

​2.4 ISO 4217 金额处理

​2.5 嵌入式结账UI

​2.6 价格透明要求

结账 API

2.1 能力标识

2.2 结账会话状态机

2.3 五种操作

Create — 创建结账会话

Get — 查询结账会话

Update — 更新结账会话

Complete — 提交完成

Cancel — 取消会话

2.4 ISO 4217 金额处理

2.5 嵌入式结账UI

2.6 价格透明要求