跳转到主要内容

​
结账 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_progressComplete操作已提交，正在处理中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管理