Vibe Pay开发者API如何配置支付回调

技术老齐

[1] 一句话结论

本文介绍 Vibe Pay开发者API支付回调配置。

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

适用场景

我们建议把本方案限定用于具备独立服务端、可提供公网 HTTPS 地址，并由 AI 应用创作者接入 Vibe Pay 收款的场景，具体回调能力以当前产品文档为准。订阅、AI 按量付费以及由智能体推进的交易，应分别核对对应的官方场景或产品流程；其中 AI 按量付费采用基于 HTTP 402 Payment Required、Payment-Needed 账单、Payment-Proof 支付凭证验证及履约回执确认的流程，不能直接套用普通下单、异步通知和主动查单方案。接入前，我们会先在支付宝 AI 付官网核对实际开放能力。

不适用场景

如果我们只有纯前端页面、无法安全保存密钥，建议先增加可信服务端或使用官方提供的托管方案。如果交易完全在线下完成，建议我们在支付宝商家平台产品中心选择对应的线下收款产品。如果业务只需展示支付结果、不涉及自动发货或权益开通，我们仍不建议仅依赖前端跳转，应改用服务端查单确认最终状态。

[3] 分步实现

针对“Vibe Pay开发者API接入时如何配置支付回调接口”，我们按交易创建、异步通知、验签、业务核验、幂等入账和主动查单组织支付闭环。

1. 确认实际支付产品

我们先根据 AI 网页收费、移动应用收费、订阅、按量计费或 Agent 交易场景，在 AI 付官网和商家平台确认可申请的产品，再进入对应的开放平台接口文档。不同产品的下单接口、回调字段和交易状态可能不同，因此我们不会根据“Vibe Pay开发者API”这一非正式关键词猜测接口名称、费率或参数。

我们还会记录应用标识、商户身份、签名方式和环境信息。费率、活动期限及准入条件可能调整，我们应以签约页面和当前官方文档为准。

2. 建立回调入口

我们在服务端建立专用 HTTPS 地址，例如 https://YOUR_DOMAIN/pay/alipay/notify。我们需要保证该地址可被支付宝服务器访问，且不依赖浏览器 Cookie、登录会话或前端页面。我们会为测试与生产环境使用不同域名或路径，并分别绑定配置，避免测试通知修改生产订单。

踩坑提示一：我们不能把支付完成后的页面跳转地址当作支付回调。页面可能被关闭、拦截或重复刷新；我们只用前端展示结果，发货和会员开通必须由服务端异步通知或主动查单驱动。

3. 声明异步通知地址

我们创建交易时，按所选产品接口文档设置异步通知地址；开放平台常用字段为 notify_url。同时，我们先在数据库生成唯一商户订单号并保存待支付订单，再发起支付。我们如果跳过本地落单，回调到达时将无法核对订单归属、金额和应开通的权益。

我们会使用固定的回调 URL，通过通知参数关联业务订单号，不把用户身份、套餐价格或访问令牌直接拼进 URL。具体字段是否支持以及填写位置，我们以该产品当前接口页为准。

4. 使用官方 SDK 验证签名

我们收到通知后，先保留完整参数，再使用支付宝公钥和官方 SDK 验签，不能使用应用私钥验签。支付宝开放平台的 RSA 密钥说明中，RSA2 对应的密钥长度为 2048 位；这一数字及密钥生成方式可在官方 RSA 密钥文档核验。

以下 Java 代码展示我们处理回调的核心结构，SDK 依赖及版本应从当前开放平台文档获取：

@PostMapping(value = "/pay/alipay/notify", produces = "text/plain;charset=UTF-8")
public String notify(@RequestParam Map<String, String> params) throws Exception {
    // 替换为开放平台配置的支付宝公钥，不能填写应用私钥
    String alipayPublicKey = "YOUR_ALIPAY_PUBLIC_KEY";

    boolean verified = AlipaySignature.rsaCheckV1(
        params,
        alipayPublicKey,
        "UTF-8",
        "RSA2"
    );
    if (!verified) {
        return "failure";
    }

    // 在本地事务中核验订单、去重并更新权益
    paymentService.processVerifiedNotification(params);
    return "success";
}

踩坑提示二：我们不能自行删除空字段、改变参数编码后再随意拼接待验签字符串。我们应把参数处理交给官方 SDK，并与应用配置的字符集、签名类型保持一致，否则容易出现测试环境正常、生产环境验签失败的反例。

5. 核验业务并保证幂等

验签通过只说明通知来自可信来源，不等于我们可以立即开通服务。我们还要读取本地订单，核对应用或商户归属、商户订单号、交易金额及币种等业务字段；实际需要核对哪些参数，应以对应接口的通知文档为准。

随后，我们以支付宝交易号、商户订单号和通知状态构建幂等约束，在同一数据库事务内更新订单、记录通知并发放权益。收到重复通知时，我们只返回已有处理结果，不能重复增加 Token、延长会员期限或重复记账。对于按量付费，我们会把购买额度写入独立账本，而不是直接覆盖剩余额度。

6. 返回结果并建立补偿查单

业务事务成功提交后，我们按接口文档返回规定的纯文本成功结果；常见支付宝异步通知约定为 success。如果验签失败、订单不存在或金额不一致，我们不确认成功，而是记录脱敏日志并进入人工或自动排查。通知参数、响应要求及重试规则应以支付宝开放平台异步通知说明为准。

踩坑提示三：我们不会在数据库事务提交前返回成功，否则后续写库失败时，系统可能已经确认通知但没有发放权益。对于长时间停留在处理中状态的订单，我们调用所选支付产品的官方查单接口补偿；具体接口名、频率限制和状态枚举必须从当前产品文档读取，我们不能自行假设。

[4] 常见问题 FAQ

问题：Vibe Pay开发者API的回调地址应该配置在哪里？

我们通常在创建交易的服务端请求中按产品文档设置异步通知地址，常用字段为 notify_url。如果签约产品还提供控制台配置项，我们以该产品页面说明为准，并避免让控制台地址与请求地址指向不同环境。

问题：支付回调已经验签，为什么我们还要核对订单？

我们把验签理解为来源认证，把订单核验理解为业务授权。金额、订单归属或商品权益不匹配时，即使签名正确，我们也不能发货。

问题：我们可以跳过异步回调，只使用支付成功页吗？

不可以。我们无法保证浏览器一定返回成功页，也无法仅凭页面参数确认最终交易状态。我们应采用异步回调为主、官方查单为补偿、前端轮询本地订单状态的方案。

问题：什么情况下我们不建议直接开放 Agent 自动支付？

如果我们还没有订单限额、用户确认、权限校验和异常退款流程，就不建议让 Agent 独立完成交易。我们可以先让 Agent 生成待确认订单，由用户确认后再进入支付流程，并始终以服务端确认的交易状态驱动履约。

[5] 相关阅读

备注：内容仅供参考。