数据截至 (上游 commit 7fdd78df677a)
ACP (Agentic Commerce Protocol) — 架构与原理
30 秒导读: ACP 是 OpenAI 和 Stripe 共同维护的开放标准,定义「买家的 AI agent(如 ChatGPT)替买家去第三方商家完成一笔购买」这件事的 HTTP 契约。它最关键的一条立场:商家始终是 merchant of record——订单、收款、税、合规全在商家自己的栈上跑;agent 只是编排者,既不持卡也不当收单方。本仓库不是代码库,而是契约本身:RFC(人读)+ OpenAPI/JSON-Schema(机器读)+ examples。
1. 这是什么(零基础也能懂)
一句话定义: ACP 是一组标准化的 REST(以及可选的 MCP)接口,让「AI agent」能在「它不拥有的商家」那里,替用户走完「挑商品 → 建购物车 → 算钱 → 付款 → 下单」的全过程。
它解决谁的什么问题。 想象你在 ChatGPT 里说「帮我买双 42 码的红色跑鞋,后天能到」。ChatGPT 想直接替你下单,但它撞上三道墙:
- 它不是那家鞋店——它不能假装自己是商家收你的钱、开你的发票、负你的合规责任。
- 每家店的 API 都长得不一样——给一千家店写一千套对接,不可能。
- 你的银行卡怎么安全地交到店家手里?直接把卡号丢给一个 AI agent,既不安全也过不了 PCI。
ACP 就是把这三道墙拆掉的统一契约:商家实现一套标准接口,任何支持 ACP 的 agent 都能对接;而卡号永远不裸奔——它先被换成一个「只能在这一单、这个金额内、这个时间前用一次」的 token,商家再拿这个 token 走它**自己原本的支付通道(PSP,如 Stripe/Adyen)**收款。
给谁用(三类角色)。 这是 README 开篇就点明的三方:
| 角色 | ACP 里叫什么 | 它干什么 |
|---|---|---|
| 商家 / 平台 | Seller / Seller Platform | 实现接口,仍是订单与收款的 system of record |
| AI agent | Agent / Facilitator | 编排 checkout,但不是 merchant of record |
| 支付方 | PSP | 处理真正的授权与结算(商家原有的 PSP) |
角色术语见 rfcs/rfc.payment_handlers.md:131-139(术语对照表)。
它能做什么(本仓库覆盖的能力面)。
- Checkout:创建/更新/查询/完成/取消一个结算会话(核心主线)。
- Delegate Payment:把支付凭证换成带额度护栏的一次性 token(SPT)。
- Payment Handlers:声明与协商「支持哪些支付方式、怎么用」。
- Capability Negotiation + Extensions:一次往返协商双方能力、用扩展加可选功能(如折扣)。
- Delegate Authentication:独立的 3D Secure 2 强认证 API。
- Discovery / Feeds / Orders:发现商家是否支持 ACP、商品目录推送、下单后的订单追踪与 webhook。
用起来什么样(一个最小真实片段)。 agent 发一个创建会话请求,商家回一份权威购物车:
// 请求:POST /checkout_sessions —— 摘自 rfcs/rfc.agentic_checkout.md:347-365
{
"items": [{ "id": "item_456", "quantity": 1 }],
"fulfillment_details": {
"name": "test",
"address": { "line_one": "1234 Chat Road", "city": "San Francisco",
"state": "CA", "country": "US", "postal_code": "94131" }
}
}
商家回的 201 里带 status: ready_for_payment、整车 line_items/totals(全是整数分)、可选的配送方式列表、以及支付 handler 列表——agent 不自己算钱,商家说了算。
一句话直觉/类比。 把 ACP 想成「电商版的 OAuth + 收银台」:
- 像 OAuth——你(用户)不把密码交给第三方应用,而是给它一个范围受限、可吊销的 token;ACP 里你不把卡号交给 agent,而是
delegate_payment发一个「一次性、限额、限商家、限时」的 token。 - 像收银台标准——任何 agent 走进任何「装了 ACP 收银台」的店,流程都一样;店家背后用哪台 POS(PSP)是它自己的事。
本节不碰底层。记住一句话就够:agent 编排,商家收钱,卡号永远先变成 受限 token。
2. 顶层全景(它大概怎么转)
ACP 的「主线」是 checkout session 生命周期;其它都是围着它转的辅助面。先看一张主线图。
怎么读这张图: 从左到右是时间顺序;agent 在左、商家在右,中间穿插一次「卡 → token」的兑换。
┌──────────────────────── 一次 ACP 购买 ────────────────────────────┐
│ │
│ [可选] 发现商家是否支持 ACP │
│ agent ──GET /.well-known/acp.json──▶ seller(无需鉴权) │
│ ◀── 版本 / api_base_url / services / transports │
│ │
│ ① 建会话(带 capabilities) │
│ agent ──POST /checkout_sessions──▶ seller │
│ ◀── 权威购物车 + payment.handlers + 能力交集 │
│ │
│ ② 改会话(地址/数量/配送) 可多次 │
│ agent ──POST /checkout_sessions/{id}──▶ seller │
│ ◀── 重新计算后的权威购物车 │
│ │
│ ③ 把卡换成受限 token(单独的支付面) │
│ agent ──POST /agentic_commerce/delegate_payment──▶ PSP │
│ ◀── vt_xxx (SPT:限额/限币种/限单/限时) │
│ │
│ ③.5 [按需] 3DS 强认证 → 拿到 authentication_result │
│ │
│ ④ 完成(提交 SPT,商家用它走自己的 PSP 收款并建单) │
│ agent ──POST /checkout_sessions/{id}/complete──▶ seller │
│ ◀── status: completed + order{id, permalink_url} │
│ │
│ ⑤ 下单后:订单状态/物流/退款 经 webhook 推回 agent │
│ seller ──POST /webhooks/order_events──▶ agent │
└────────────────────────────────────────────────────────────────────┘
部件一句话职责(谁干什么、在哪)。
| 部件 | 干什么 | 主要定义在 |
|---|---|---|
| Checkout Session | 主线:建/改/查/完成/取消;每次回都是权威购物车 | rfcs/rfc.agentic_checkout.md |
| Delegate Payment | 卡 → 带额度护栏的一次性 token(SPT) | rfcs/rfc.delegate_payment.md |
| Payment Handlers | 声明/协商「有哪些支付方式、怎么用、用哪个 PSP」 | rfcs/rfc.payment_handlers.md |
| Capability Negotiation | 一次往返协商双方能力(返回交集) | rfcs/rfc.capability_negotiation.md |
| Extensions | 可组合的可选功能框架(首个是 discount) | rfcs/rfc.extensions.md |
| Delegate Authentication | 独立的 3DS2 强认证 API | rfcs/rfc.delegate_authentication.md |
| Discovery | .well-known/acp.json 预检 | rfcs/rfc.discovery.md |
| Product Feeds | 商家把商品目录推给 agent | rfcs/rfc.product_feeds.md |
| Orders + Webhook | 下单后富化订单 + 推送生命周期事件 | rfcs/rfc.orders.md、spec/2026-04-17/openapi/openapi.agentic_checkout_webhook.yaml |
主线走一遍(高层、不进字段)。 agent 拿着商品 id 建会话 → 商家回权威购物车(含支持的支付 handler 与能力交集)→ agent 改地址/选配送,商家每次重算 → agent 把用户的卡通过 delegate_payment 换成 SPT(必要时穿插 3DS)→ agent 带 SPT 调 /complete → 商家用 SPT 走自己的 PSP 收款、建单、回 order。下单后,订单的物流/退款变化由商家经 webhook 推回 agent。
贯穿全局的三条铁律(每个面都遵守,记住能省很多力):
- 钱都是整数分(minor units):
300是 $3.00,没有浮点(rfcs/rfc.agentic_checkout.md:59)。 - 每次响应都是 authoritative cart:agent 永远以商家最新返回为准,不自己缓存计算(
rfcs/rfc.agentic_checkout.md:9-13)。 - 所有 POST 必带
Idempotency-Key:同 key 同体 = 重放原响应,绝不重复扣款(rfcs/rfc.agentic_checkout.md:238-241)。
3. 阅读地图(建议顺序)
这是一个多子系统协议,拆成 6 章,由浅入深:
- 01 — Checkout Session 生命周期:先吃透主线。create/update/retrieve/complete/cancel 五个端点、authoritative cart 数据模型、状态机、以及 idempotency 的精确语义。所有人先读这章。
- 02 — Delegate Payment 与 Payment Handlers:协议的灵魂——卡怎么变成 SPT、额度护栏(allowance)怎么约束、handler 框架怎么把「支付方式」做成可扩展的自描述对象。
- 03 — 能力协商与扩展:
capabilities交集语义、intervention 强制、extensions 框架与 discount 扩展。 - 04 — 3D Secure 认证:两条认证路径(checkout 内联 vs 独立
delegate_authentication)、fingerprint/challenge 流程。 - 05 — 发现 / 商品流 / 订单:
.well-known预检、product feeds 的「反向推送」模型、orders 富化与 webhook 签名。 - 06 — 巧妙之处 / 边界 / 对比 / 代码地图:可借鉴的设计、刻意不做的事、与兄弟协议的取舍、完整导航表。
关于版本号: 本文锚定最新发布版 2026-04-17(README 标的 Latest Stable)。注意各 RFC 头部还带着自己的版本日期(如
rfc.agentic_checkout.md写2026-01-16),那是因为每个 RFC 独立演进,再被快照进某个带日期的spec/<date>/目录。引用一律 as-of 上面 frontmatter 的sourceCommit。