
为 API、数据集、付费页面或 MCP 工具收费,并不需要把每个资源都改造成传统的结账流程。借助 x402,HTTP 流程本身就可以表明需要付款、描述可接受的选项,并让兼容的客户端授权访问。真正的挑战远不止返回一个 402 状态码:而是要在不暴露源站的前提下,设计好规则、验证、执行、结算、计量和对账。
本指南以 Cloudflare 的发布公告和该协议的现行文档为技术参考,说明如何设计一个可与 x402 互操作的 Monetization Gateway。本文并不声称文中描述的所有能力都已在 AZPay 或 Cloudflare 上对任何账户开放。可用性、网络、资产、facilitator(协调方)和商业条款都需要在所选环境中确认。
x402 解决了什么问题
HTTP 早就有 `402 Payment Required` 状态码,但历史上它本身并没有定义服务器如何传达价格、网络、资产、收款方或授权。x402 增加了对象和请求头,让服务器描述付款要求,让客户端返回签名授权。在第 2 版中,响应使用 `PAYMENT-REQUIRED`,付费请求使用 `PAYMENT-SIGNATURE`,两者都携带 Base64 编码的数据。
基本流程很简单。客户端请求资源。网关返回 402 和付款选项。客户端选择一个选项,签署授权,然后重新发送请求。网关或 facilitator 验证授权,资源按照方案(scheme)的语义执行,付款完成结算。之后客户端才会收到付费内容的响应。
这种简单性很有力量,因为它与 API 走的是同一个通道。但它不会把任何浏览器变成钱包,也不会免除身份、授权、源站保护和客户支持方面的责任。
Monetization Gateway 是控制层,而不只是付费墙
变现网关必须为每个请求回答五个问题:访问的是哪个资源、谁可以访问、价格是多少、如何验证付款,以及执行之后会发生什么。一条规则可以组合域名、路径、HTTP 方法、受众、请求头、参数和调用方属性。
控制平面应保存资源、源站、带版本的规则、收款钱包、网络、环境和审计事件。数据平面在边缘评估规则,在需要时返回 402,保护源站,并记录整个周期中的事实。将这两个平面分开,可以在不重新部署每个应用的情况下发布新策略,但这需要带版本的快照、明确的优先级和回滚能力。
好的编辑器会区分付费路由和未变现的路由。它还会显示哪条规则生效、某个请求为何被放行或拦截,以及收费在哪个环境中生效。“发布”和“回滚”按钮必须真正修改配置;一个只是看起来可以操作的界面,会给产品和财务带来风险。
`exact` 与 `upto`:固定价格与消费上限
在 `exact` 方案中,授权金额必须与要求的价格一致。它适用于价格在执行前就已确定的页面、API 调用或工具。
在 `upto` 模式中,客户端授权一个上限,当实现方和 facilitator 支持这种语义时,服务器可以报告实际消耗的金额。这适用于按 token、字节、返回记录数或可变处理量计费的场景,但需要可靠的计量。上限并不意味着可以随意收费:源站必须报告真实消耗,网关必须防止结算金额超出授权。
不要把按请求计价与订阅、预付余额或事后计费混为一谈。每种模式都有自己的状态和对账方式。成熟的运营会把意图、授权、验证、执行、计量金额、结算、已交付的响应以及可能的失败记录为相互关联的事实,而不是只用一列“已付款”。
源站仍然在安全模型之内
在边缘验证付款可以减轻源站的负担,但并不意味着可以绕过源站。网关必须阻止直接绕过访问,保留必要的上下文,并在适用时发送经过签名的上下文供源站验证。如果源站只信任任何客户端都能伪造的请求头,付费资源依然是暴露的。
面向客户端的 x402 请求头与网关和源站之间的内部请求头有重要区别。客户端不应伪造应用所依赖的信任上下文。源站还需要知道这次收费是固定的还是可变的,以及执行语义是什么:先验证后结算,还是使用方案定义的其他流程。
在某些产品中,源站返回的 401 可以被转化为一次付款机会。这必须是明确的策略。已登录用户不应因为规则配置错误而丢失会话,未登录的买家也不应仅仅因为网关把任何错误都变成 402 就获得访问权限。
Facilitator、网络与环境
Facilitator 是为兼容的方案和网络提供验证与结算操作的组件。不应把它当作看不见的细节:可用性、签名方、资产、限额、过期时间、成本和责任都各不相同。
使用测试网来验证技术契约。把开发、测试网和生产环境清楚地分开。在测试网络上确认的付款只能证明那个测试流程跑通了;它不能证明商业接入、主网支持、兑换为法定货币、合规性,也不能证明在某个国家可用。
在 x402 v2 中,网络使用 CAIP-2 标识符,付款要求包含 `scheme`、`network`、`asset`、`amount`、`payTo` 和 `maxTimeoutSeconds` 等字段。客户端应使用兼容的库,而不是照着旧示例手动拼装签名。发布规则之前,应先查看 facilitator 的能力列表。
Pix 适用于哪里,又不适用于哪里
Pix 和 x402 解决的是相关的问题,但它们不是同一个协议。Pix 是巴西的支付体系,有自己的收款请求、二维码、确认和对账机制。x402 是一种在 HTTP 交互中表示和授权付款的约定,其方案和网络由具体实现定义。
企业可以为兼容 x402 的买家保护一个 API,同时为个人用户保留独立的 Pix 结账流程。它也可以提供一个巴西本地资源,只有在 Pix 收款确认后才放行交付。无论哪种情况,都不应假装二维码就是 x402 签名,也不应假装 x402 钱包自动就是 Pix 账户。
对于 Pix,可靠的确认仍然来自支付参与机构和所签约的集成,而不是客户端的某个界面。
一个架构示例
设想一家出售实时货运数据的公司。`GET /datasets/frete` 按次收费,`GET /datasets/frete?regiao=sudeste` 采用不超过上限的可变价格。客户端请求该端点。网关评估方法、路径和环境,并返回付款要求。客户端签署所接受的选项。Facilitator 验证授权。源站计算实际交付的数据集,在方案允许时报告金额,并返回数据集。网关完成结算、记录收据并交付响应。
这个流程需要幂等性。如果连接在执行后中断,客户端应先查询结果或收据,再决定是否重复一个具有资金影响的操作。如果源站在验证之后失败,系统必须记录失败并按方案语义处理;不能因为付款看起来有效,就把交易标记为成功。
响应不是即时返回时会发生什么?
一次变现操作可能存在中间状态。在源站仍在处理请求时,授权可能已经有效。结算可能依赖后续确认。客户端可能在资源执行之后、收到响应之前断开连接。在所有这些情况下,“我没有收到响应”并不自动等于“没有扣款”。
至少要为四个相互关联的视图建模:访问尝试、出示的授权、执行结果和结算。一个稳定的标识符应能在不创建新操作的情况下查询状态。网关还需要把重复请求与首次尝试区分开,并在操作语义允许时返回已知的结果。
对于会产生外部影响的工具,这一点尤为重要。查询类操作重复执行的风险较低;而创建记录、发送消息或预留资源的操作,需要严格得多的重试策略。一次调用的价格既不能替代幂等性,也不能替代业务授权。
如何按资源设计访问策略?
首先要确定买家得到的单位是什么。“API 访问”过于宽泛,无法据此定义一条好的规则。要具体说明价值是在一份报告、一组记录、一次转换、一个数据时间窗口,还是一次执行的操作中。
然后区分公开资源、受保护资源和付费资源。健康检查端点、文档、集成所需的文件和管理路由,不应仅仅因为位于同一域名下就被通用规则捕获。优先级必须明确:公开例外应优先于宽泛的收费规则,而付费路由即使在客户端修改参数时也必须保持受保护。
还应明确每个环境中会发生什么。开发环境和测试网应使用与生产环境分离的钱包、网络和源站。已发布的规则需要显示其生效环境、版本以及生效时间。这样可以避免把一次成功的测试误认为真实收入,或把价格调整误认为具有追溯效力。
如何衡量变现是否奏效?
收入很重要,但不是唯一的指标。要理解整个漏斗,需要跟踪访问尝试、402 响应、出示的授权、已验证的授权、已完成的执行、结算和已交付的资源。每个比率都需要清晰的分母。
从 402 到授权之间出现下降,可能说明付款要求不清楚,或者客户端不支持所发布的选项。从已验证授权到交付之间出现下降,可能说明源站故障、超时或执行不兼容。结算与已交付资源之间的差异,需要进行运营调查,并有明确的补偿或重试策略。
仪表盘应帮助回答具体问题:哪条路由带来需求、哪条规则带来转化、正在使用哪个环境、哪些故障反复出现、哪些付款仍待对账。没有这种视图,企业可能把流量误当成收入,把授权误当成实际交付的价值。
不可忽视的安全与限制
网关获得的权限不应超过其履行职责所需。钱包、密钥、机密信息、源站上下文和运营权限都需要分开管理。切勿把 facilitator 的机密信息放在公开页面上,或放在客户端可以查看的请求中。
验证方法、路径、域名、环境、金额、网络、资产、收款方和过期时间。拒绝已过期的授权、低于要求的金额、重复的 nonce 以及不匹配的上下文。记录每个决定的原因,但不要存储不必要的买家数据。
保护措施还包括可用性限制。付费资源可能因重复调用、高成本查询或放大消耗的参数而被滥用。限流、执行限制、在安全前提下的缓存,以及针对有副作用操作的专门控制,都是价格规则的补充,而不能替代付款。
什么时候 x402 不是最佳选择?
x402 并不是适用于所有商业体验的通用方案。如果买家是需要分期付款、Pix、客服支持、发票或可视化同意流程的个人,传统结账可能更合适。如果资源由少数客户以可预测的量来使用,合同或周期性套餐可能会让运营更简单。
当意图是程序化的、价值单位可以在一次请求中描述,并且客户端能够理解并响应付款要求时,x402 最有意义。它可以与其他渠道共存:一个 API 可以通过 x402 服务智能体,同时通过身份认证和结账服务人类用户;一个产品可以为个人提供 Pix,为程序化客户端提供兼容的钱包。
智能体在商店中的购物还会走另一条路径:卡组织网络。例如,Visa 已将智能体发起交易的测试扩展到收单机构和 PSP。
Monetization Gateway 上线检查清单
在启用规则之前,确认资源已明确所有者、价格、源站和受众。检查源站不接受绕过访问、规则不会捕获公开路由,并且钱包、网络、资产和 facilitator 与环境兼容。
测试未付款的调用、有效授权、金额错误、网络不兼容、授权过期、nonce 重复、源站不可用、超时、安全重试和延迟结算。然后对网关、源站和支付组件中发生的情况进行对账。
最后,编写客户支持策略。需要有人能够解释为什么某次调用收到 402、为什么某个授权被拒绝、资源是否已执行,以及资金状态如何。只有当团队能够在不依赖猜测的情况下调查异常时,变现体验才算准备就绪。
让规则上线的检查清单
从资源和域名所有权开始。确认不经过网关就无法访问源站。先定义最具体的规则,并记录优先级。只有在确定金额的计算方式之后,再选择 `exact` 或 `upto`。
接着固定协议版本、网络、资产、钱包、facilitator 和环境。测试未付款的请求、有效授权、过期授权、金额错误、nonce 重复、结算失败、超时和安全重试。记录源站收到了什么,以及买家收到了什么。
最后,对四个视图进行对账:访问尝试、授权、链上结算和已交付资源。如果其中任何一个无法通过稳定的标识符关联起来,支持团队将很难解释一笔扣款或一次失败的访问。
常见问题
x402 会取代面向个人的结账吗?
不会。x402 尤其适用于能够理解付款要求并签署授权的程序化客户端、智能体和应用。面向个人的结账可能需要不同的流程、无障碍支持、身份认证以及 Pix 等本地支付方式。
我可以用一条规则为任何页面收费吗?
从技术上讲,一条宽泛的规则可以匹配许多 URL,但这并不意味着它是好的策略。先从价格、源站、受众和交付方式都定义清楚的资源开始。利用优先级和测试,避免对健康检查端点、公开文件或不应收费的方法收费。
发布公告能证明产品已经可用吗?
不能。公告描述的是一项提议和某个特定阶段。能启用什么,取决于现行文档、账户权限、网络、facilitator 和适用的合同。凡是未在你的环境中测试过的能力,都应视为尚未确认。
下一步
最好的第一个交付成果不是装饰性的付费墙,而是一条可测试的规则:有受保护的源站、兼容的客户端、独立的环境,以及能解释每一步的日志。流程得到验证后,再扩展到多个资源、可变价格、智能体和本地集成,同时不要把技术授权、收款和交付混在一起。

原则很直接:将 HTTP 资源变现,就是在意图、付款和访问之间建立一道可验证的边界。技术打开了这道边界;状态、安全和对账方面的工程能力让它保持可靠。如需了解该产品的商业方案,另请参阅AZPay Monetization Gateway:将任何数字资源转化为付费访问。