数据截至 2026-08-21(上游 commit 9ed9049a14d9)

UCP — 支付架构（信任三角与 Payment Handler）

本章讲 UCP 怎么处理支付——这是它比一般 agent 协议背得更重的一块，因为牵涉真钱和 PCI 合规。核心目标：让平台（尤其是 AI agent）永远不碰原始卡号，又能完成支付。

1. 它要解决的小问题：N×M 爆炸

平台、商家、支付处理方三者两两组合，集成数量是 N×N×N 级别。UCP 把它解耦：把“接受什么支付工具（instrument）”和“怎么处理（handler）”分开，让复杂度回落。来源：docs/specification/overview/index.md:2459-2465、docs/documentation/core-concepts.md:350-355。

2. 思路/直觉：信任三角

支付模型建在三条双边信任关系上——注意没有“三方都互信”这种东西：

                 已有合同 + API key
      商家 ◀───────────────────────────▶ 支付凭证方 (CP / PSP)
        ▲                                      ▲
        │                                      │ 平台找 CP 的界面
  平台把  │ token / mandate                      │ (iframe/API) 换 token
  结果交给│                                      │
        │                                      │
      平台 ◀──────────────────────────────────┘
           平台 ↔ 商家：平台把“结果”交给商家完成下单

关键约束（背下来）：凭证只能“平台 → 商家”单向流动，商家 MUST NOT 在响应里回带凭证。 来源：docs/documentation/core-concepts.md:357-374、docs/specification/overview/index.md:2491-2497。

3. 核心概念：Payment Handler 是“规范”，不是“实体”

这是最容易理解错的一点，规范专门强调：

Payment Credential Provider（CP/PSP） = 参与者（实体），如 Google Pay、Shop Pay、某 PSP。
Payment Handler = 这些参与者编写的规范（一份 JSON Schema 蓝图），定义“某支付工具如何被获取与处理”，标识符如 com.google.pay、dev.shopify.shop_pay。

来源：docs/specification/overview/index.md:2521-2536、docs/documentation/core-concepts.md:377-386。

谁负责什么，规范给了一张很清楚的分工表：

角色	职责	动作
支付凭证方	定义规范	发布 Handler 蓝图（JSON Schema）：怎么 tokenize、需要哪些 config
商家	配置 Handler	选用某 Handler，在 checkout 响应里填自己的配置（公钥、Merchant ID）
平台	执行协议	读商家配置，按凭证方的规范逻辑去拿 token

来源：docs/specification/overview/index.md:2499-2509。

4. 三步支付生命周期

支付按 协商 → 获取 → 完成 三步走：

① Negotiation  商家 → 平台   商家在 profile / checkout 响应里广告可用 handlers
                            （“用这个 CP 端点 + 这把公钥来付”）
② Acquisition  平台 ↔ CP     平台执行 handler 逻辑，直接找 CP 换 token
                            （客户端/agent 侧完成，商家不参与 → 原始数据不碰商家前端）
③ Completion   平台 → 商家   平台把不透明凭证(token)提交给商家，商家用其 PSP 后端扣款

来源：docs/specification/overview/index.md:2510-2520、docs/documentation/core-concepts.md:388-396。

真实数据形状：完成时提交的 instrument

看“Complete Checkout”请求里支付工具长什么样（docs/specification/overview/index.md:2644-2687，对应 source/schemas/shopping/types/payment_instrument.json）：

{
  "payment": {
    "instruments": [
      {
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "display": { "brand": "visa", "last_digits": "4242" },
        "credential": { "type": "PAYMENT_GATEWAY", "token": "{...加密 token...}" }
      }
    ]
  }
}

注意 handler_id：它告诉商家“用哪个支付凭证方的哪把密钥来解密/扣款”，防止密钥混淆攻击。来源：docs/specification/overview/index.md:2497。

5. PCI 边界：谁背合规

UCP 的支付设计本质是“把 PCI 范围推给该背的人”：

参与方	怎么缩小 PCI 范围
平台	只经手不透明凭证（加密数据/token 引用），从不接触/存储原始卡号 → 多数实现可完全避开 PCI 范围
商家	用凭证方托管的 tokenization，自己只收 token 引用；从不记录原始凭证
支付凭证方	通常已是 PCI-DSS Level 1 认证，负责原始凭证采集/保护/处理

来源：docs/specification/overview/index.md:2845-2878。

6. 三个实战场景（理解“同一套机制覆盖不同付法”）

规范给了三个并列场景，体现 handler 模型的弹性：

场景 A：数字钱包。 平台认出 com.google.pay，把商家的 config 喂给钱包 API，拿回加密 token。docs/specification/overview/index.md:2577-2687。
场景 B：直接 tokenize + SCA 挑战。 平台用通用 tokenizer 换 token；银行要 3DS，商家返回 status: requires_escalation + code: requires_3ds，平台把 continue_url 开在 WebView 让用户过验证再重试。docs/specification/overview/index.md:2688-2779。
场景 C：自主 agent（AP2）。 agent 不用会话 token，而是在非 agent 表面用用户私钥签 mandate，提交 ap2.checkout_mandate 作为不可抵赖的授权证明。docs/specification/overview/index.md:2780-2844（细节见 04 章与 ap2-mandates 规范）。

7. 巧妙之处 / 坑

巧：available_instruments 双向声明 + 商家裁决。 平台和商家各自在 profile 里声明能处理哪些工具类型，商家把两者与购物车上下文取交后在响应里给出权威结果，平台 MUST 以响应为准。docs/specification/overview/index.md:2554-2563。
巧：动态过滤 handlers。 商家 MUST 按购物车上下文过滤 handler（如订阅商品去掉 BNPL、按收货地区过滤地方支付方式）。docs/specification/overview/index.md:2537-2539。
坑：单一支付工具约束。 一次 complete MUST 只含恰好一个支付工具，除非 dev.ucp.shopping.split_payments 能力激活；违反要回 payment_failed。docs/specification/overview/index.md:2565-2570。
坑：中间件不得重序列化。 因为 Content-Digest 是对原始字节算的，代理/网关重新序列化 JSON 会让签名失效（详见 05 章）。docs/specification/signatures.md:419-423。

8. 代码地图

主题	文件	符号 / 锚点
信任三角 / PCI / 分工	`docs/specification/overview/index.md`	“Payment Architecture” §2459-2570、“PCI-DSS Scope Management” §2845-2878
三步生命周期 + 三场景	`docs/specification/overview/index.md`	“Payment in the Checkout Lifecycle” §2510-2520、“Implementation Scenarios” §2572-2844
Handler schema	`source/schemas/payment_handler.json`	`$defs.base`、`platform_schema`、`business_schema`、`response_schema`
支付工具 / 凭证类型	`source/schemas/shopping/types/payment_instrument.json`、`source/schemas/shopping/types/payment_credential.json`	—
支付对象（checkout 内）	`source/schemas/shopping/payment.json`	—
分账扩展	`source/schemas/shopping/split_payments.json`	`name=dev.ucp.shopping.split_payments`

1. 它要解决的小问题：N×M 爆炸​

2. 思路/直觉：信任三角​

3. 核心概念：Payment Handler 是“规范”，不是“实体”​

4. 三步支付生命周期​

真实数据形状：完成时提交的 instrument​

5. PCI 边界：谁背合规​

6. 三个实战场景（理解“同一套机制覆盖不同付法”）​

7. 巧妙之处 / 坑​

8. 代码地图​