结账 REST 绑定

概述

本文档指定结账能力的 REST 绑定。

协议基础

基础 URL

所有 UCP REST 端点都相对于商家的基础 URL，通过 /.well-known/ucp 的 UCP profile 发现。

内容类型

  • 请求：application/json
  • 响应：application/json

传输安全

所有 REST 端点必须通过 HTTPS 提供服务，最低 TLS 版本为 1.3。

操作

操作方法端点描述
创建结账POST/checkout-sessions创建结账会话
获取结账GET/checkout-sessions/{id}获取结账会话
更新结账PUT/checkout-sessions/{id}更新结账会话
完成结账POST/checkout-sessions/{id}/complete下单
取消结账POST/checkout-sessions/{id}/cancel取消结账会话

HTTP 头

UCP-Agent 头

所有请求必须包含 UCP-Agent 头，包含平台 profile URI：

UCP-Agent: profile="https://platform.example/profile"

Idempotency-Key

修改状态的操作应该通过 Idempotency-Key 头支持幂等性。

示例：创建结账

请求：

POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "line_items": [
    {
      "item": {
        "id": "item_123",
        "title": "红色 T 恤",
        "price": 2500
      },
      "quantity": 2
    }
  ],
  "currency": "USD"
}

响应：

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      }
    ]
  },
  "id": "chk_1234567890",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [...],
  "totals": [...],
  "links": [...],
  "payment": {
    "handlers": [...]
  }
}

示例：完成结账

请求：

POST /checkout-sessions/{id}/complete HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "payment_data": {
    "id": "pi_gpay_5678",
    "handler_id": "com.google.pay",
    "type": "card",
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

响应：

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [...]
  },
  "id": "chk_123456789",
  "status": "completed",
  "currency": "USD",
  "order": {
    "id": "ord_99887766",
    "permalink_url": "https://merchant.com/orders/ord_99887766"
  }
}

状态码

状态码描述
200 OK请求成功
201 Created资源成功创建
400 Bad Request请求无效
404 Not Found找不到请求的资源
409 Conflict幂等键被重用且参数不同
500 Internal Server Error发生意外错误

错误响应

错误响应遵循标准 UCP 错误结构：

{
  "status": "requires_escalation",
  "messages": [
    {
      "type": "error",
      "code": "invalid_cart_items",
      "content": "一个或多个购物车商品无效",
      "severity": "requires_buyer_input"
    }
  ]
}

安全

身份验证

当需要身份验证时，REST 传输可以使用：

  1. 开放 API：公共操作无需身份验证
  2. API 密钥：通过 X-API-Key 头
  3. OAuth 2.0：通过 Authorization: Bearer {token} 头
  4. 双向 TLS：用于高安全环境

另请参阅