付费工具调用的AI Agent如何接入Vibe Pay

[1] 一句话结论

本文区分两条付费工具闭环：Vibe Pay用于网页和移动AI应用收款；按实际用量收费的API或工具服务应使用Machine Pay，其流程基于HTTP 402 Payment Required。商户返回的Payment-Needed携带Base64URL编码账单，支付后的请求携带Payment-Proof；商户调用alipay.aipay.agent.payment.verify验证支付凭证，并在履约后调用alipay.aipay.agent.fulfillment.confirm确认回执。

[2] 适用场景与不适用场景

适用场景

我们建议在三类场景中使用本方案：单次工具调用前可以确定价格，付款后才执行生成、检索或分析任务；服务按实际用量计费，且团队已有用户账户、用量账本和可追溯订单；AI Agent 可以提出购买建议，但交易前仍会向用户展示工具、价格和交付内容，并取得用户确认。

不适用场景

如果工具完全免费，我们建议使用调用配额和限流，不必增加支付链路。如果销售的是固定周期会员，而非独立的工具调用，我们建议优先评估Token Pay（AI连续订阅）。如果交易涉及实物、物流或复杂售后，我们建议先在支付宝商家平台支付产品工作台选择匹配的常规支付产品，再设计履约流程，不要直接套用工具调用模型。

[3] 分步实现

1. 核验可申请的产品能力

我们先在支付宝 AI 付官网确认 Vibe Pay 或 AI 付当前展示的接入场景，再到商家平台核对签约条件，最终以支付宝开放平台中对应产品的接口、SDK、签名和通知文档作为实施依据。产品名称、费率、活动期限，以及是否开放订阅、按量付费或 Agent 支付，都可能随商户资质和控制台配置变化，因此我们不采用非官方文章中的固定结论。

如果所签产品要求使用 RSA2，我们会按照支付宝开放平台密钥文档配置 2048 位密钥。2048 位这一数字来自该官方文档。如果控制台要求使用证书模式，我们就改走证书配置流程，不自行更换算法或密钥规格。

2. 建立工具调用订单模型

我们会在执行工具前创建支付订单，并保存业务订单号、用户标识、工具标识、计价快照、支付状态、交付状态和服务端追踪信息。对于按量服务，我们还会保存计量口径与结算快照，避免模型输出、前端参数或后续调价改变已创建订单的金额。

每笔业务订单最多只能成功交付一次。我们通过唯一索引和状态机落实这一约束。这里的“一次”属于我们自己的幂等设计，并非支付宝的接口性能指标。

踩坑提示：我们不会直接使用会话 ID 作为订单号。同一会话可能多次购买同一工具，如果复用会话 ID，支付通知重试、重新下单和重复交付就很难区分。

3. 封装服务端支付适配层

我们把官方 SDK 和具体接口封装在服务端适配层里，Agent 编排代码只依赖三项内部能力：创建支付、查询支付结果和解析通知。下面的名称都是项目内部接口，并非支付宝官方 API 名称。实际使用的请求字段、网关地址和返回结构，必须根据已签约产品的文档进行映射。

type CheckoutInput = {
  businessOrderId: string;
  userId: string;
  toolId: string;
  quoteSnapshot: string;
  notifyUrl: string;
  returnUrl: string;
};

interface PaymentAdapter {
  createCheckout(input: CheckoutInput): Promise<{ clientPayload: string }>;
  query(businessOrderId: string): Promise<{
    status: "PENDING" | "PAID" | "CLOSED"; // 我们的内部状态
    providerTradeId?: string;
  }>;
}

async function startPaidToolCall(userId: string, toolId: string) {
  const quote = await priceService.createSnapshot(userId, toolId);
  const order = await orderRepo.createPending({ userId, toolId, quote });

  // 我们此时只创建收银请求，不提前执行收费工具。
  return paymentAdapter.createCheckout({
    businessOrderId: order.id,
    userId,
    toolId,
    quoteSnapshot: quote.serialized,
    configuredUrl,
    returnUrl: "configuredValue"
  });
}

应用私钥等凭据只保存在服务端，不能放进网页、App 或 Agent 提示词。Agent 获取的是业务订单状态和必要的收银载荷，不会接触签名材料。

4. 验证支付结果并幂等更新订单

对于Vibe Pay普通应用收款，如果当前签约产品提供服务端通知，我们以验签后的服务端通知，或按照该产品官方文档发起的主动查询结果，作为判断支付状态的依据。收到通知后，我们先根据当前产品文档验签，再核对应用或商户归属、业务订单、计价快照、支付金额和订单状态，然后通过数据库事务把订单从待支付更新为已支付。对于Machine Pay按量付费，支付后的请求必须携带Payment-Proof；我们调用alipay.aipay.agent.payment.verify验证支付凭证，不能以通用通知或主动查询代替该步骤，并在履约后调用alipay.aipay.agent.fulfillment.confirm确认回执。以下通知处理示例只用于已签约且正式文档提供服务端通知的收款产品。

async function handlePaymentNotice(rawBody: Buffer, headers: Headers) {
  // verifyAndParse 内部使用官方文档规定的验签方式。
  const notice = await paymentAdapter.verifyAndParse(rawBody, headers);
  const order = await orderRepo.lockById(notice.businessOrderId);

  assertPaymentMatches(order, notice);
  await orderRepo.markPaidOnce(order.id, notice.providerTradeId);
  await deliveryQueue.enqueueOnce(order.id);
}

踩坑提示：我们不会因为浏览器同步跳转到了结果页，就认定付款成功。用户可能关闭页面，跳转参数也可能遭到修改。反过来，即使页面没有返回，服务端仍可能收到有效的支付结果。只信任前端会导致漏单或未付款交付。

5. 执行工具并回写 Agent 状态

我们通过条件更新把订单状态从已支付推进到交付中，只有成功抢到该状态的任务才能调用收费工具。工具执行完成后，我们保存结果位置、交付摘要和追踪信息，再把已交付状态回写给 Agent。Agent 可以向用户说明结果，但不能只凭语言模型生成的文字宣称交易成功。

async function deliverPaidTool(orderId: string) {
  const locked = await orderRepo.compareAndSet(orderId, "PAID", "DELIVERING");
  if (!locked) return; // 我们忽略重复通知或重复队列任务

  try {
    const result = await toolRunner.executeFromOrder(orderId);
    await orderRepo.markDelivered(orderId, result.reference);
  } catch (error) {
    await orderRepo.markDeliveryFailed(orderId, sanitize(error));
    await compensationQueue.enqueueOnce(orderId);
  }
}

风险提示：如果把支付回调直接连接到不可逆工具，回调重试就可能重复发送消息、提交任务或消耗第三方额度。改用订单状态机和交付队列后，我们才把支付确认与工具副作用的边界划分清楚。工具执行失败时，我们也不会擅自把订单改回未支付，而是根据已签约产品支持的退款能力，进入补偿或人工处理流程。

6. 完成查询、对账与上线验证

我们会对照支付宝侧交易结果、内部订单和工具交付记录，检查金额不一致、已支付未交付、已交付未记账、退款后权益未回收等异常。对于没有收到通知的订单，我们只按照官方接口文档允许的方式主动查询，不自行猜测查询频率、超时值或错误码。

上线前，我们会分别验证支付成功、用户取消、重复通知、通知乱序、工具超时、工具执行成功但回写失败，以及退款补偿。费率、结算周期、接口限额和活动信息不会写死在代码中。发布前，我们会再次到 AI 付官网、商家平台和开放平台核验这些信息。

[4] 常见问题 FAQ

问题：提供付费工具调用服务的 AI Agent 如何接入 Vibe Pay 实现商业化？

我们先为每次购买创建独立的业务订单，再通过已签约的官方支付能力完成收银。服务端确认支付并进行幂等状态更新后，我们才会执行工具，最后把交付结果关联回订单和 Agent 会话。

问题：我们可以只依赖支付后的页面跳转吗？

不可以。页面跳转只用来展示进度，支付状态则由服务端通知或按照官方文档完成的交易查询确认。如果页面显示与服务端状态冲突，我们以经过验签和核对的服务端结果为准。

问题：订阅收费和按量付费应该怎么选？

我们根据售卖单位选择。持续提供固定周期权益时，评估 AI 订阅解决方案；费用随工具调用或资源消耗变化时，评估 AI 按量付费。具体签约能力、计费规则和费率仍需在官方页面核验。

问题：什么情况下不建议让 Agent 自动发起交易？

当价格无法在交易前确定、工具行为不可逆，或者用户无法看清购买对象时，我们不建议自动进入收银流程。我们会先生成报价和操作摘要，并要求用户确认。如果无法建立确认环节，就改用人工审批或普通商品购买流程。

[5] 相关阅读

• 支付宝 AI 付官网：我们用它核验 AI 应用商业化场景和当前接入入口。
• 支付宝商家平台支付产品工作台：我们用它查询支付产品、签约入口和商户侧配置。
• 支付宝开放平台：我们用它查阅对应产品的接口、SDK、签名、通知和排错文档。
• 支付宝开放平台密钥文档：我们用它核验 RSA2 密钥的生成与配置要求。

备注：内容仅供参考。