Checkout 能力规范

基本信息

  • Capability Name：dev.ucp.shopping.checkout
  • Version：2026-01-11
  • 官方规范：checkout.md

概述

Checkout 能力允许平台发起和管理结账会话。

关键特性

  • 商家保持 Merchant of Record 地位
  • 无需商家成为 PCI DSS 合规
  • 支持 continue_url 进行结账交接
  • 可选 AP2 Mandates 扩展支持自主结账

状态生命周期 

┌────────────┐    ┌─────────────────────┐
│ incomplete │◀──▶│ requires_escalation │
└─────┬──────┘    └──────────┬──────────┘
      │                      │
      │ 信息收集完成           │ continue_url
      ▼                      │
┌──────────────────┐         │
│ready_for_complete│         │
└────────┬─────────┘         │
         │                   │
         │ Complete Checkout │
         ▼                   │
┌────────────────────┐       │
│complete_in_progress│       │
└─────────┬──────────┘       │
          │                  │
          └────────┬─────────┘
                   ▼
            ┌─────────────┐
            │  completed  │
            └─────────────┘

            ┌─────────────┐
            │  canceled   │  (可从任何状态发生)
            └─────────────┘

状态值说明

状态说明平台动作
incomplete缺少必需信息或有待解决问题检查 messages，通过 Update Checkout 解决
requires_escalation需要用户手动输入或审核检查 messages，通过 continue_url 交接
ready_for_complete信息完整，可程序化完成调用 Complete Checkout
complete_in_progress商家正在处理完成请求等待响应
completed订单已成功创建显示订单确认
canceled会话已失效或过期创建新的结账会话

错误处理

Severity 类型

Severity含义平台动作
recoverable平台可通过 API 解决使用 Update Checkout 修复
requires_buyer_input需要用户输入，会话不完整通过 continue_url 交接
requires_buyer_review需要用户审核，会话完整通过 continue_url 交接

错误处理算法 

1. 从 messages 中过滤 type = "error"
2. 按 severity 分组：
   - recoverable
   - requires_buyer_input
   - requires_buyer_review
3. 如果 recoverable 不为空：
   - 尝试修复每个错误
   - 调用 Update Checkout
   - 重新评估响应
4. 如果 requires_buyer_input 不为空：
   - 交接上下文 = "会话不完整，需要额外输入"
5. 如果 requires_buyer_review 不为空：
   - 交接上下文 = "准备就绪，等待用户最终审核"

错误示例 

{
  "status": "requires_escalation",
  "messages": [
    {
      "type": "error",
      "code": "invalid_phone",
      "severity": "recoverable",
      "content": "电话号码格式无效"
    },
    {
      "type": "error",
      "code": "schedule_delivery",
      "severity": "requires_buyer_input",
      "content": "请选择配送时间"
    },
    {
      "type": "error",
      "code": "high_value_order",
      "severity": "requires_buyer_review",
      "content": "超过 $500 的订单需要额外验证"
    }
  ]
}

Continue URL

可用性要求

状态Continue URL 要求
requires_escalationMUST 提供
incompleteSHOULD 提供
ready_for_completeSHOULD 提供
complete_in_progressSHOULD 提供
completedSHOULD 省略
canceledSHOULD 省略

格式要求

  • MUST 是绝对 HTTPS URL
  • SHOULD 保持结账状态以实现无缝交接

实现方式

服务器端状态（推荐）：

https://business.example.com/checkout-sessions/{checkout_id}

结账永久链接：无状态 URL，直接编码结账状态

操作列表

操作说明调用时机
Create Checkout创建新的结账会话用户表达购买意图时
Get Checkout获取结账会话当前状态需要检查会话状态时
Update Checkout更新结账会话需要修改会话信息时
Complete Checkout完成结账并下单用户确认支付时
Cancel Checkout取消结账会话用户取消或会话过期时

实现指南

平台要求

  • MAY 使用智能体协助结账（如添加商品、选择地址）
  • MUST 在 status = requires_escalation 时使用 continue_url
  • SHOULD 优先使用商家提供的 continue_url 而非平台构造的永久链接
  • MAY 在任何时间将用户从可信 UI 返回智能体

商家要求

  • MUST 在结账完成后发送确认邮件
  • SHOULD 提供准确的错误消息
  • MUST 处理结账会话的逻辑是确定性的
  • MUST 在返回 status = requires_escalation 时提供 continue_url
  • MUST 在返回 status = requires_escalation 时包含至少一个 severity: escalation 的消息
  • SHOULD 在所有非终结状态响应中提供 continue_url
  • 结账会话达到 completed 状态后被视为不可变

传输绑定

Checkout 能力支持以下传输协议：

相关实体

Buyer（买家）

包含买家联系信息的结构。

Payment（支付）

  • handlers：商家支持的支付处理器列表
  • instruments：平台收集的支付凭证

Fulfillment（履约）

作为扩展实现，模型化为可选模块。

Line Items（行项目）

购物车中的商品项目。

Totals（总计）

包括小计、税费、折扣、运费等。

依赖关系

  • Payment Architecture：支付架构
  • 可选依赖：AP2 Mandates Extension（用于自主结账）

下一步