嵌入式结账协议

概述

嵌入式结账协议 (ECP) 使主机能够嵌入商家的结账界面，在买家交互时接收事件，并委托关键用户操作（如地址和支付选择）。

W3C Payment Request 对齐

ECP 汲取了 W3C Payment Request API 的灵感，为嵌入式结账场景调整其思维模型：

概念W3C Payment Request嵌入式结账
初始化new PaymentRequest()使用 continue_url 加载
UI 就绪show() 返回 Promiseec.start 通知
支付方式更改paymentmethodchange 事件ec.payment.change 通知
提交支付用户接受 → PaymentResponse委托 ec.payment.credential_request
完成response.complete()ec.complete 通知

发现

ECP 可用性通过服务发现发出信号。当商家宣告 embedded 传输时，所有 continue_url 值都支持 ECP：

{
  "services": {
    "dev.ucp.shopping": {
      "embedded": {
        "schema": "https://ucp.dev/services/shopping/embedded.openrpc.json"
      }
    }
  }
}

加载嵌入式结账

要启动 ECP 会话，使用查询参数增强 continue_url：

  • ec_version（字符串，必需）：UCP 版本（格式：YYYY-MM-DD）
  • ec_auth（字符串，可选）：身份验证令牌
  • ec_delegate（字符串，可选）：逗号分隔的委托列表

示例：

https://example.com/checkout/abc123?ec_version=2026-01-11&ec_delegate=payment.credential,fulfillment.address_change

委托

委托允许主机本机处理特定操作：

ec_delegate 值对应消息
payment.instruments_changeec.payment.instruments_change_request
payment.credentialec.payment.credential_request
fulfillment.address_changeec.fulfillment.address_change_request

消息格式

所有 ECP 消息必须使用 JSON-RPC 2.0 格式：

{
  "jsonrpc": "2.0",
  "method": "ec.start",
  "params": {...},
  "id": "optional_request_id"
}

核心消息

ec.ready（握手）

在主机和嵌入式结账之间建立连接：

{
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential", "fulfillment.address_change"]
  }
}

主机响应：

{
  "jsonrpc": "2.0",
  "id": "ready_1",
  "result": {
    "checkout": {
      "payment": {
        "instruments": [...]
      }
    }
  }
}

ec.start（生命周期）

发出结账可见且准备交互的信号：

{
  "jsonrpc": "2.0",
  "method": "ec.start",
  "params": {
    "checkout": {
      "id": "checkout_123",
      "status": "incomplete",
      "totals": [...],
      "line_items": [...]
    }
  }
}

ec.complete（生命周期）

指示结账成功完成：

{
  "jsonrpc": "2.0",
  "method": "ec.complete",
  "params": {
    "checkout": {
      "id": "checkout_123",
      "order": {
        "id": "ord_99887766",
        "permalink_url": "https://merchant.com/orders/ord_99887766"
      }
    }
  }
}

ec.payment.credential_request（委托）

从主机请求支付凭证：

{
  "jsonrpc": "2.0",
  "id": "payment_credential_request_1",
  "method": "ec.payment.credential_request",
  "params": {
    "checkout": {
      "id": "checkout_123",
      "payment": {
        "selected_instrument_id": "payment_instrument_123"
      }
    }
  }
}

主机响应：

{
  "jsonrpc": "2.0",
  "id": "payment_credential_request_1",
  "result": {
    "checkout": {
      "payment": {
        "instruments": [
          {
            "id": "payment_instrument_123",
            "credential": {
              "type": "token",
              "token": "tok_123"
            }
          }
        ]
      }
    }
  }
}

安全

CSP 要求

  • 商家：设置 frame-ancestors <host_origin>;
  • 主机：使用适当的 frame-src 或中间 iframe

Iframe 沙箱 

<iframe sandbox="allow-scripts allow-forms allow-same-origin"></iframe>

另请参阅