AP2 全流程数据对象、结构与 W3C 规范关系详解

阅读说明：下文包含 AP2 参考类型中的全部字段说明、A2A 封装 MUST/MAY 规则、协议常量、CartMandate 官方 JSON 示例与 W3C 对齐关系。无需打开仓库源码即可理解数据如何流转、长什么样、与哪些 Web 标准相关。若你更关心「人在场/不在场先做哪步」，可读同目录 ap2_execution_flow.md（流程与本文互补）。集成时以双方约定的 JSON 序列化约定（snake_case / camelCase）为准。

1. W3C 是什么？与 AP2 相关的有哪些？

W3C（World Wide Web Consortium） 是制定 Web 基础标准（HTML、CSS、无障碍、支付相关 API 等）的国际组织。与 AP2 最常一起讨论的标准包括：

W3C 文档 简称 与 AP2 的关系
Payment Request API PR API AP2 复用其数据语义：金额、行项目、支付方式声明、PaymentResponse 等与 W3C 文档中的接口对象一一对应（见本文第 4.3 节全表）。
Contact Picker API Contact Picker PR API 在 Web 中会引用地址；AP2 复用 ContactAddress 的字段集合（见第 4.4 节）。
Verifiable Credentials Data Model 等 VC / VCDM AP2 使用 VDC（Verifiable Digital Credential）、Verifiable Presentation 等术语，与 Issuer–Holder–Verifier 模型概念对齐；PaymentMandate.user_authorization 的说明中举例 SD-JWT VC 等，表示可与该生态对接。AP2 本身不是 W3C 发布的一份 Recommendation。

重要区分：

  • 浏览器里的 Payment Request：JavaScript API new PaymentRequest(...)，由用户代理调起钱包 UI。
  • AP2 中的用法：在 A2A / 代理服务之间传递同一套抽象数据（金额、明细、支付方式、PaymentResponse），不要求必须在浏览器里调用 navigator.payment。

2. 全流程：哪些数据在流转？

结果

支付方式与用户授权

意图与购物车收敛

IntentMandate

CartMandate

PaymentRequest 嵌于 CartContents

PaymentMandate

PaymentResponse 嵌于 PaymentMandateContents

PaymentReceipt

2.1 数据对象总览（无文件依赖）

数据对象 典型流转方向 协议作用
IntentMandate Shopping Agent ↔ 用户 / 商户（依场景） 捕获并约束购物意图（自然语言、可选商户/SKU、是否需确认购物车、退款、过期时间）。人不在场流程的核心凭证之一。
CartMandate Merchant → Shopping Agent → 用户签署 商户对最终购物车与价格的承诺；contents 内含 W3C 语义的 PaymentRequest。
PaymentRequest 全家桶 嵌在 CartContents；并驱动后续 PaymentResponse 对齐 W3C Payment Request API 的 method_data、details、options、shipping_address。
ContactAddress 随 PaymentRequest.shipping_address、PaymentResponse.shipping_address 等 对齐 W3C Contact Picker 的物理地址结构。
PaymentMandate Shopping Agent → 商户 / MPP → 网络与发卡行（概念上） 面向支付生态的「代理化交易」可见性；含 PaymentResponse 与用户 user_authorization。
PaymentResponse 写入 PaymentMandateContents 对齐 W3C PaymentResponse：所选方式、令牌、可选收货与 payer 信息。
PaymentReceipt 支付完成后回传 支付最终状态与确认号；非 W3C PR API 内置类型，属 AP2 收据模型。

此外常参与链路：A2A 的 Message / Artifact / Task（传输容器）、risk_data（风险信号）、merchant_authorization（商户 JWT）。

3. 协议常量：DataPart 键名、A2A 扩展 URI、角色枚举

3.1 AP2 在 A2A DataPart 中使用的键名

常量含义 键名字符串
购物车授权 ap2.mandates.CartMandate
意图授权 ap2.mandates.IntentMandate
支付授权 ap2.mandates.PaymentMandate
支付收据 ap2.PaymentReceipt
支付方式数据（部分实现） payment_request.PaymentMethodData
联系地址 contact_picker.ContactAddress

3.2 A2A 扩展 URI（必须）

支持 AP2 扩展的代理 必须 使用以下 URI：

https://github.com/google-agentic-commerce/ap2/tree/v0.1

3.3 AgentCard 中 params.roles 的允许取值

每个支持 AP2 的代理 必须 至少声明一个角色，取值为：

  • merchant
  • shopper
  • credentials-provider
  • payment-processor

若代理承担 merchant 角色，建议将 AP2 扩展标为 required（表示客户端必须能用 AP2 扩展完成支付）。

4. 完整类型参考（字段级，与参考类型一致）

以下采用 逻辑名（下表「字段名」列）。参考实现里使用 snake_case（如 display_items）；JSON 与浏览器交互时常用 camelCase（如 displayItems），语义相同，集成时做字段名映射即可。

说明：部分公开 JSON 示例里可能出现 user_signature_required、merchant_signature 等写法，与下表中的 user_cart_confirmation_required、merchant_authorization 并存于不同资料；下表以协议参考类型为准，对接时以双方约定的 schema 版本为准。

4.1 IntentMandate（意图授权）

人在场流程会用到初始字段；人不在场流程未来可能对同一 mandate 增加字段。

字段名 类型 必填 说明
user_cart_confirmation_required bool 是 若为 false，在满足所有购买条件后代理可代用户下单。若意图 mandate 未经用户签名，则必须为 true。
natural_language_description string 是 购物代理生成、用户确认的意图描述（知情同意）。示例：High top, old school, red basketball shoes
merchants list[string] 或省略 否 允许履约的商户列表；未设置则代理可与任意合适商户合作。
skus list[string] 或省略 否 允许的 SKU 列表；未设置则任意 SKU。
requires_refundability bool 或省略 否 默认 false；若为 true，商品必须可退款。
intent_expiry string 是 过期时间，ISO 8601 格式。

与 W3C：不属于 Payment Request API 的某个接口；是 AP2 自有 Mandate。

4.2 CartContents（购物车内容）

商户对购物车签名后形成 CartMandate；本对象描述 待签名的购物车内容。

字段名 类型 必填 说明
id string 是 购物车唯一标识。
user_cart_confirmation_required bool 是 若为 true，商户要求用户在完成购买前确认购物车。
payment_request PaymentRequest 是 W3C PaymentRequest 语义：商品、价格、本购物车接受的支付方式集合。
cart_expiry string 是 购物车过期时间，ISO 8601。
merchant_name string 是 商户名称。

4.3 CartMandate（购物车授权）

字段名 类型 必填 说明
contents CartContents 是 购物车内容。
merchant_authorization string 或省略 否 base64url 编码的 JWT，对购物车内容做数字签名，保证真实性与完整性。结构见下 4.3.1。
4.3.1 merchant_authorization（JWT）预期结构（协议说明中的语义）

JWT 为 base64url 编码，整体结构为三块（Header.Payload.Signature）：

  1. Header：包含签名算法与密钥 ID（kid）等。
  2. Payload 典型声明包括：
    • iss、sub、aud：商户（签发者）与预期接收方（如支付处理器）标识。
    • iat、exp：签发时间与短有效期过期时间（例如 5–15 分钟）。
    • jti：唯一 ID，防重放。
    • cart_hash：对 CartContents 对象规范 JSON 表示做安全哈希，保证内容未被篡改。
  3. Signature：商户私钥签名；验证方用公钥验证完整性与来源。

4.4 PaymentCurrencyAmount（W3C PaymentCurrencyAmount）

字段名 类型 必填 说明
currency string 是 三位 ISO 4217 货币代码。
value number 是 金额数值。

4.5 PaymentItem（W3C PaymentItem）

字段名 类型 必填 说明
label string 是 行项目的人类可读描述。
amount PaymentCurrencyAmount 是 该行金额。
pending bool 或省略 否 若为 true，表示金额尚未最终确定。
refund_period int 是（有默认值） 默认 30；该行退款期限（天）。属 AP2/实现侧常见扩展，未必见于 W3C 最简 IDL。

4.6 PaymentShippingOption（W3C PaymentShippingOption）

字段名 类型 必填 说明
id string 是 运费选项唯一 ID。
label string 是 人类可读描述。
amount PaymentCurrencyAmount 是 该选项费用。
selected bool 或省略 否 默认 false；是否为默认选中项。

4.7 PaymentOptions（W3C PaymentOptions）

字段名 类型 必填 说明
request_payer_name bool 或省略 否 默认 false；是否收集付款人姓名。
request_payer_email bool 或省略 否 默认 false；是否收集邮箱。
request_payer_phone bool 或省略 否 默认 false；是否收集电话。
request_shipping bool 或省略 否 默认 true；是否收集收货地址。
shipping_type string 或省略 否 可为 shipping、delivery、pickup。

4.8 PaymentMethodData（W3C PaymentMethodData）

字段名 类型 必填 说明
supported_methods string 是 支付方式标识（如卡、特定钱包等）。
data object 否 该方法专属数据；默认可为空对象。

4.9 PaymentDetailsModifier（W3C PaymentDetailsModifier）

字段名 类型 必填 说明
supported_methods string 是 本修正项适用的支付方式 ID。
total PaymentItem 或省略 否 覆盖原合计的 PaymentItem。
additional_display_items list[PaymentItem] 或省略 否 该支付方式下额外展示行。
data object 或省略 否 该方法专属数据。

4.10 PaymentDetailsInit（W3C PaymentDetailsInit）

字段名 类型 必填 说明
id string 是 本次支付请求唯一 ID。
display_items list[PaymentItem] 是 展示给用户的明细行。
shipping_options list[PaymentShippingOption] 或省略 否 可选运费方案。
modifiers list[PaymentDetailsModifier] 或省略 否 按支付方式的价目修正。
total PaymentItem 是 应付合计。

4.11 PaymentRequest（W3C PaymentRequest）

字段名 类型 必填 说明
method_data list[PaymentMethodData] 是 商户接受的支付方式列表。
details PaymentDetailsInit 是 金额与明细。
options PaymentOptions 或省略 否 是否收集 payer / 收货信息等。
shipping_address ContactAddress 或省略 否 用户提供的收货地址。

4.12 PaymentResponse（W3C PaymentResponse）

字段名 类型 必填 说明
request_id string 是 对应原始 PaymentRequest.details.id。
method_name string 是 用户选择的支付方式。
details object 或省略 否 由支付方式生成，供商户处理交易（如令牌）；内容依方法而定。
shipping_address ContactAddress 或省略 否 收货地址。
shipping_option PaymentShippingOption 或省略 否 选中的运费选项。
payer_name string 或省略 否 付款人姓名。
payer_email string 或省略 否 付款人邮箱。
payer_phone string 或省略 否 付款人电话。

4.13 ContactAddress（W3C ContactAddress）

字段名 类型 必填 说明
city string 或省略 否 城市。
country string 或省略 否 国家。
dependent_locality string 或省略 否 依赖 locality。
organization string 或省略 否 组织。
phone_number string 或省略 否 电话。
postal_code string 或省略 否 邮编。
recipient string 或省略 否 收件人。
region string 或省略 否 省/州等区域。
sorting_code string 或省略 否 分拣码。
address_line list[string] 或省略 否 地址行。

4.14 PaymentMandateContents（支付授权内容）

字段名 类型 必填 说明
payment_mandate_id string 是 本 PaymentMandate 唯一 ID。
payment_details_id string 是 对应支付请求（PaymentDetailsInit）ID。
payment_details_total PaymentItem 是 应付总额（与明细一致）。
payment_response PaymentResponse 是 用户选定方式与令牌等。
merchant_agent string 是 商户代理标识。
timestamp string 是 创建时间，ISO 8601 格式。

4.15 PaymentMandate（支付授权）

字段名 类型 必填 说明
payment_mandate_contents PaymentMandateContents 是 支付授权正文。
user_authorization string 或省略 否 base64url 编码的可验证呈现（Verifiable Presentation），对 CartMandate 与 PaymentMandateContents 的哈希等进行绑定。示例实现路径包括 SD-JWT VC，可能包含：签发方签名的 JWT（含 cnf 等声明）、key-binding JWT（含 aud、nonce、sd_hash、transaction_data 等；其中 transaction_data 为数组，含 CartMandate 与 PaymentMandateContents 的安全哈希）。

协议语义摘要：Cart / Intent mandate 用于商户履约；PaymentMandate 另用于向支付网络/发卡行提供 AI 代理交易的可视信息与信任材料，可与常规授权报文一并送交。

4.16 PaymentReceipt（支付收据）

字段名 类型 必填 说明
payment_mandate_id string 是 已处理的 payment mandate ID。
timestamp string 是 收据创建时间，ISO 8601。
payment_id string 是 支付唯一 ID。
amount PaymentCurrencyAmount 是 支付金额。
payment_status 见下表 是 三选一：成功 / 错误 / 失败。
payment_method_details object 或省略 否 交易所用支付方式详情。
payment_status 的三种形态

Success

字段名 类型 必填 说明
merchant_confirmation_id string 是 商户侧交易确认 ID。
psp_confirmation_id string 或省略 否 支付服务商确认 ID。
network_confirmation_id string 或省略 否 支付网络确认 ID。

Error

字段名 类型 必填 说明
error_message string 是 人类可读错误说明与后续指引。

Failure

字段名 类型 必填 说明
failure_message string 是 人类可读失败说明与后续指引。

4.17 类型嵌套关系（树形）

IntentMandate（独立）
CartMandate
├── contents: CartContents
│   └── payment_request: PaymentRequest
│       ├── method_data: PaymentMethodData[]
│       ├── details: PaymentDetailsInit
│       │   ├── display_items: PaymentItem[]
│       │   ├── shipping_options: PaymentShippingOption[]?
│       │   ├── modifiers: PaymentDetailsModifier[]?
│       │   └── total: PaymentItem
│       │       └── amount: PaymentCurrencyAmount
│       ├── options: PaymentOptions?
│       └── shipping_address: ContactAddress?
└── merchant_authorization: JWT string?

PaymentMandate
├── payment_mandate_contents: PaymentMandateContents
│   ├── payment_details_total: PaymentItem
│   └── payment_response: PaymentResponse
│       ├── details: object?
│       ├── shipping_address: ContactAddress?
│       └── shipping_option: PaymentShippingOption?
└── user_authorization: string?

PaymentReceipt
├── amount: PaymentCurrencyAmount
└── payment_status: Success | Error | Failure

5. A2A 封装规则（完整条文）

5.1 IntentMandate Message

  • 必须提供 IntentMandate Message（A2A Message 的一种 profile）。
  • Message 必须包含一个 DataPart：键为 ap2.mandates.IntentMandate，值为符合 IntentMandate schema 的对象。
  • Message 可以包含另一个 DataPart：键为 risk_data，值为实现方定义的风险信号。

5.2 CartMandate Artifact

  • 发起支付请求时，Merchant Agent 必须产出 CartMandate Artifact（A2A Artifact 的 profile）。
  • 在收齐所有会影响支付的信息之前，Merchant Agent 不得产出 CartMandate。
    • 影响支付的信息：客户端提供的、会改变 CartContents 从而改变应付金额的任何信息（例如收货地址改变运费，使 CartContents 变化）。
  • Artifact 必须包含 DataPart：键 ap2.mandates.CartMandate，值为符合 CartMandate schema 的对象。
  • Artifact 可以包含 DataPart：键 risk_data，值为实现方定义的风险数据。

5.3 PaymentMandate Message

  • 向代理提供 PaymentMandate 时，客户端 必须构造 PaymentMandate Message（A2A Message 的 profile）。
  • Message 必须包含 DataPart：键 ap2.mandates.PaymentMandate，值为符合 PaymentMandate schema 的对象。
  • Message 可以包含其它 Part。

5.4 官方 JSON 示例（CartMandate Artifact 片段，camelCase）

下列为规范文档中的 示意 JSON（字段名为 Web 常见写法；contents 内嵌 payment_request）。可与第 4 节逻辑字段对照。

{
  "name": "Fancy Cart Details",
  "artifactId": "artifact_001",
  "parts": [
    {
      "kind": "data",
      "data": {
        "ap2.mandates.CartMandate": {
          "contents": {
            "id": "cart_shoes_123",
            "user_signature_required": false,
            "payment_request": {
              "method_data": [
                {
                  "supported_methods": "CARD",
                  "data": { "payment_processor_url": "http://example.com/pay" }
                }
              ],
              "details": {
                "id": "order_shoes_123",
                "displayItems": [
                  {
                    "label": "Cool Shoes Max",
                    "amount": { "currency": "USD", "value": 120.0 },
                    "pending": null
                  }
                ],
                "shipping_options": null,
                "modifiers": null,
                "total": {
                  "label": "Total",
                  "amount": { "currency": "USD", "value": 120.0 },
                  "pending": null
                }
              },
              "options": {
                "requestPayerName": false,
                "requestPayerEmail": false,
                "requestPayerPhone": false,
                "requestShipping": true,
                "shippingType": null
              }
            }
          },
          "merchant_signature": "sig_merchant_shoes_abc1",
          "timestamp": "2025-08-26T19:36:36.377022Z"
        }
      }
    },
    {
      "kind": "data",
      "data": {
        "risk_data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...fake_risk_data"
      }
    }
  ]
}

说明：示例顶层出现 merchant_signature、timestamp 以及 user_signature_required 等命名；与第 4 节参考类型中的 merchant_authorization、user_cart_confirmation_required 可能不一致，以你对接的 schema 版本与字段表为准。

6. 为什么说 AP2「遵循」或「部分遵循」W3C？

6.1 可以准确说的表述

  1. 购物车与支付明细：CartContents.payment_request 与整棵 PaymentRequest 子树 按 W3C Payment Request API 的接口语义建模（金额、行项目、方式、响应等）。
  2. 地址与 payer 信息：ContactAddress 与 PaymentResponse 与 W3C Contact Picker / PR API 常见形状一致。
  3. 信任与凭证：VDC / Verifiable Presentation 与 W3C VC 数据模型在「可验证、issuer-holder-verifier」上概念对齐；user_authorization 的示例实现可与 SD-JWT VC 等格式对接。

6.2 需要避免的过度表述

  1. 「AP2 是 W3C 标准」 — 不正确。AP2 是独立的开放协议，不是 W3C Recommendation。
  2. 「实现 AP2 等于在浏览器里调用 Payment Request」 — 不必然。代理链路可无 navigator.payment，仍使用相同数据语义。
  3. 「所有字段与某一版 W3C IDL 逐字等价」 — 需谨慎：存在 扩展字段（如 refund_period）与 命名风格差异。
  4. 「PaymentMandate 必然是 VCDM 2.0 的 VC」 — 未固定为唯一格式；由部署 profile 决定。

7. 端到端数据流（与角色）

MPP / Network Merchant Agent Credentials Provider Shopping Agent MPP / Network Merchant Agent Credentials Provider Shopping Agent 意图阶段（依场景） 收敛购物车，构造 PaymentRequest 用户确认后形成 PaymentResponse IntentMandate（A2A Message / ap2.mandates.IntentMandate） CartMandate Artifact（ap2.mandates.CartMandate） 请求支付方式 支付方式 / token 能力 PaymentMandate Message（ap2.mandates.PaymentMandate） 授权 + PaymentMandate 授权结果 PaymentReceipt（ap2.PaymentReceipt）

8. 小结

问题 结论
全流程有哪些数据？ IntentMandate、CartMandate（含 PaymentRequest 子树）、PaymentMandate（含 PaymentResponse 与 user_authorization）、PaymentReceipt；外加 A2A 封装与风险、商户 JWT。
结构长什么样？ 本文第 4 节已列出全部字段与嵌套关系；第 5 节为 A2A 封装 MUST/MAY。
W3C 指什么？ 主要指 Payment Request API、Contact Picker；凭证侧与 Verifiable Credentials 生态 概念对齐。
AP2「遵循」W3C 吗？ 在支付明细与响应结构上复用 W3C PR API（及 Contact Picker）的数据模型；凭证模型与 VC 生态对齐；AP2 协议本身不是 W3C 标准；代理场景 ≠ 浏览器 PR 运行时。

9. 外部权威链接（仅标准站点）

  • W3C Payment Request API：https://www.w3.org/TR/payment-request/
  • W3C Contact Picker API：https://www.w3.org/TR/contact-picker/
  • W3C Verifiable Credentials Data Model：https://www.w3.org/TR/vc-data-model/
  • A2A 扩展机制：https://a2a-protocol.org/latest/topics/extensions/
# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AI写专著必备：掌握AI专著写作技巧，3天搞定20万字专著！

avatar AtomGit开源社区
cover

推理服务为什么一上流量镜像就开始成本翻倍：从 Shadow Traffic 到分层采样的工程实战

avatar AtomGit开源社区
cover

时序解耦自编码器：用 β‑VAE 和 TCN 实现铣削刀具磨损的可解释异常检测

avatar AtomGit开源社区