商品额度核销接口

最后更新于

商品额度核销接口

接口说明

接口名称:alipay.aipay.nowpaydirect.quota.verify

按应用提供的消费请求号直接核销指定数量的次数或积分。核销成功即正式扣减;应用需结合服务交付时点调用,并保存消费请求与核销结果的对应关系。

适用场景

  • 一次服务需要正式消耗次数或积分。
  • 同一消费请求因网络异常需要重试。

注意事项

  • amount 必须显式传入正整数;一次扣 1 次时传 1,不依赖服务端默认补值。积分按应用服务规则计算后传入。
  • 先检查 code,再读取 consume_status。只有 SUCCEEDED 表示扣减成功;PROCESSING、网络超时或系统错误都不能直接当作失败换号重扣。
  • 余额不足可能通过业务错误码 NOW_PAY_QUOTA_INSUFFICIENT 返回;也需兼容 consume_status=FAILED 的结果表达。额度不足整笔失败,不按部分扣减处理。
  • 核销成功后不提供核销撤销、或服务失败自动返还。商户应事先确定服务交付与核销的时点,并对服务执行本身做好幂等。

公共请求参数

参数 类型 是否必选 长度/取值 描述 示例值
app_id String 必选 32 支付宝分配给开发者的应用ID YOUR_APP_ID
method String 必选 128 接口名称 alipay.aipay.nowpaydirect.quota.verify
format String 可选 40 仅支持JSON JSON
charset String 必选 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 必选 10 请求签名算法,推荐 RSA2 RSA2
sign String 必选 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 必选 19 发送请求的时间,格式”yyyy-MM-dd HH:mm:ss” 2026-09-27 10:00:00
version String 必选 3 调用的接口版本,固定为:1.0 1.0
app_auth_token String 可选 40 已获授权的第三方代调用场景使用的应用授权令牌,详见应用授权概述 -
biz_content String 必选 - 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 -

业务请求参数

参数 类型 是否必选 长度/取值 描述 注意事项/枚举值 示例值
out_request_no String 必选 128 商户生成的幂等请求号 重试保持原值与原业务参数;不同请求使用不同值 consume_20260927_000001
out_product_id String 必选 128 直连商品的外部商品 ID,从管理小程序商品详情页复制 使用当前商户创建的商品;不要自行生成或使用内部商品号 np_d_f83a7c91
external_buyer_id String 必选 128 应用内稳定的权益受益人标识 与应用登录用户绑定;不等同于付款账号 user_001
amount Number 必选 99999999 本次核销数量,单位次数或积分 显式传入正整数;COUNT 单次扣减传 1;当前预览“长度/取值”为 99999999 1
consume_reason String 必选 256 本次业务消费的简洁原因文本 普通文本 生成一篇文章

常见请求示例

示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。

import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpaydirectQuotaVerifyRequest;
import com.alipay.api.response.AlipayAipayNowpaydirectQuotaVerifyResponse;

public class NowpayExample {
    public static void main(String[] args) throws Exception {
        AlipayConfig config = new AlipayConfig();
        config.setServerUrl("https://openapi.alipay.com/gateway.do");
        config.setAppId(System.getenv("ALIPAY_APP_ID"));
        config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY"));
        config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY"));
        config.setFormat("json");
        config.setCharset("UTF-8");
        config.setSignType("RSA2");
        AlipayClient client = new DefaultAlipayClient(config);

        AlipayAipayNowpaydirectQuotaVerifyRequest request = new AlipayAipayNowpaydirectQuotaVerifyRequest();
        request.setBizContent("{\"out_request_no\":\"consume_20260927_000001\",\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\",\"amount\":1,\"consume_reason\":\"生成一篇文章\"}");
        // 仅在已获授权的第三方代调用场景设置 app_auth_token。
        String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        if (appAuthToken != null && !appAuthToken.isEmpty()) {
            request.putOtherTextParam("app_auth_token", appAuthToken);
        }
        AlipayAipayNowpaydirectQuotaVerifyResponse response = client.execute(request);
        if (!response.isSuccess()) {
            // 按 code/sub_code 处理;结果未知时保留原业务请求号。
            System.out.println(response.getCode() + ":" + response.getSubCode());
            return;
        }
        // 网关成功后,按本页“结果处理”读取业务字段。
        System.out.println(response.getBody());
    }
}
biz_content='{
  "out_request_no": "consume_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001",
  "amount": 1,
  "consume_reason": "生成一篇文章"
}'

# app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。
curl --request POST 'https://openapi.alipay.com/gateway.do' \
  --data-urlencode "app_id=${app_id}" \
  --data-urlencode 'method=alipay.aipay.nowpaydirect.quota.verify' \
  --data-urlencode 'format=json' \
  --data-urlencode 'charset=UTF-8' \
  --data-urlencode 'sign_type=RSA2' \
  --data-urlencode "timestamp=${timestamp}" \
  --data-urlencode 'version=1.0' \
  --data-urlencode "biz_content=${biz_content}" \
  --data-urlencode "sign=${sign}"

公共响应参数

参数 类型 是否必选 长度/取值 描述 示例值
code String 必选 - 网关返回码;10000 表示接口调用成功 10000
msg String 必选 - 网关返回码说明 Success
sub_code String 可选 - 业务错误码;仅用于接口失败处理 -
sub_msg String 可选 - 业务错误说明;不用于编写固定业务分支 -
sign String 必选 - 响应签名,位于响应根对象;由 SDK 按配置验签 -

响应业务对象名为 alipay_aipay_nowpaydirect_quota_verify_response。先完成验签并判断 code,再读取业务结果。

业务响应参数

参数 类型 是否必选 长度/取值 描述 注意事项/枚举值 示例值
consume_status String 必选 32 核销状态 成功:SUCCEEDED;失败:FAILED;进行中:PROCESSING SUCCEEDED
consume_reason String 必选 512 消费原因 商户应持久化原始原因;查询结果可能不返回 生成一篇文章
quota_unit String 必选 32 额度类型 COUNT:次数;POINT:积分 COUNT
consumed Number 特殊可选 99999999 本次实际扣减量,单位次数或积分 SUCCEEDED 时使用;PROCESSING 时可能缺失,不补零、不推断扣减结果 1
remaining Number 特殊可选 99999999 本次核销成功时,原子扣减后的可消费余额 仅 SUCCEEDED 时使用;不是当前实时余额 19
update_time String 特殊可选 32 更新时间;格式 yyyy-MM-dd HH:mm:ss,时区 Asia/Shanghai SUCCEEDED时返回 2026-09-27 10:05:00

结果处理

情况 应用处理
code=10000 且 consume_status=SUCCEEDED 确认本次扣减,保存原请求号、consumed、remaining;避免重复交付
code=10000 且 consume_status=FAILED 不标记核销成功,结合原消费记录排查;本接口未定义失败原因字段
code=10000 且 consume_status=PROCESSING 保留原请求号,调用 quota.refresh 查询
余额不足业务错误 提示购买或补充额度,不标记消费成功
超时、系统错误、未知状态 标记本地待确认,使用原请求查询或重试,不换号

code=10000 不能单独作为扣减成功依据;同样不能只处理 consume_status 而忽略网关失败。

响应示例

以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。

{
  "alipay_aipay_nowpaydirect_quota_verify_response": {
    "code": "10000",
    "msg": "Success",
    "consume_status": "SUCCEEDED",
    "quota_unit": "COUNT",
    "consumed": 1,
    "remaining": 19,
    "update_time": "2026-09-27 10:05:00",
    "consume_reason": "生成一篇文章"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}
{
  "alipay_aipay_nowpaydirect_quota_verify_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

余额不足错误示例

{
  "alipay_aipay_nowpaydirect_quota_verify_response": {
    "code": "40004",
    "msg": "Business Failed",
    "sub_code": "NOW_PAY_QUOTA_INSUFFICIENT",
    "sub_msg": "额度不足"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}

处理中示例

扣减量和余额可能缺失;保留原请求号继续查询,不把缺失值补为零后判定失败。

{
  "alipay_aipay_nowpaydirect_quota_verify_response": {
    "code": "10000",
    "msg": "Success",
    "consume_status": "PROCESSING",
    "quota_unit": "COUNT",
    "consume_reason": "生成一篇文章"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}

公共错误码

参见支付宝公共错误码。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。

业务错误码

以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。

错误码 错误描述 解决方案
SYSTEM_ERROR 系统繁忙 稍后使用原参数重试;消费结果未知时先查询原请求
INVALID_PARAMETER 参数有误 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试
BILLING_MODE_NOT_SUPPORTED 商品不是额度包模式 请核对入参参数相关的商品配置信息
NOW_PAY_BINDING_INVALID 商品绑定无效 请检查商品id是否属于本次请求的商户账号
NOW_PAY_QUOTA_CONSUME_CONFLICT 额度消费请求幂等冲突 检查核销请求out_request_no是否已被使用
NOW_PAY_QUOTA_INSUFFICIENT 额度不足 提示购买或补充额度;本次不记为核销成功