商品收费能力查询接口

更新时间:

接口说明

接口名称:alipay.aipay.nowpay.charge.query

查询平台商品的收费能力状态、收费模式和可售档位,并获取商品管理入口。平台可据此展示收费配置入口、选择购买流程和刷新商品状态。

支持已获授权的第三方代理调用。所有接口由平台服务端调用。

适用场景

  • 进入商品收费设置页,判断应初始化配置还是进入管理页。
  • 配置、启停操作结束后刷新状态和可售档位。
  • 读取 billing_mode,选择访问决策流程或额度包流程。

注意事项

  • NOT_CONFIGUREDCONFIGURING:继续调用 charge.initialize 获取 configuration_url;其余已配置状态使用 management_url 进入管理页。
  • capability_status 描述商品新增购买能力。用户是否可访问应查询 purchase.consult;额度包的余额和扣减结果分别查询 quota.queryquota.verify
  • charging_options 可能为空。sku_idplan_id 都按不透明标识保存;价格、价格版本和档位列表只用于展示与选择,不由平台拼装支付订单。
  • 遇到未知状态或查询失败时,不自动放行付费访问;展示处理中并刷新,必要时进入返回的管理入口。

公共请求参数

参数类型是否必选最大长度描述示例值
app_idString必选32支付宝分配给开发者的应用IDYOUR_APP_ID
methodString必选128接口名称alipay.aipay.nowpay.charge.query
formatString可选40仅支持JSONJSON
charsetString必选10请求使用的编码格式,如utf-8,gbk,gb2312等utf-8
sign_typeString必选10请求签名算法,推荐 RSA2RSA2
signString必选344商户请求参数的签名串,详见签名详见示例
timestampString必选19发送请求的时间,格式”yyyy-MM-dd HH:mm
2026-09-07 10:00:00
versionString必选3调用的接口版本,固定为:1.01.0
app_auth_tokenString可选40已获授权的第三方代调用场景使用的应用授权令牌,详见应用授权概述-
biz_contentString必选-业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表-

业务请求参数

业务字段统一放入 biz_content。下表数组子字段使用 [] 表示元素路径。

参数类型是否必选最大长度描述注意事项/枚举值示例值
out_product_idString必选128平台内稳定的商品或应用标识-app_writing_001
external_owner_idString必选128平台内稳定的创作者或商品所有者标识与配置时使用的标识一致;不是必须填写支付宝账号creator_001

常见请求示例

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

import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpayChargeQueryRequest;
import com.alipay.api.response.AlipayAipayNowpayChargeQueryResponse;

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);

        AlipayAipayNowpayChargeQueryRequest request = new AlipayAipayNowpayChargeQueryRequest();
        request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\"}");
        // 仅在已获授权的第三方代调用场景设置 app_auth_token。
        String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        if (appAuthToken != null && !appAuthToken.isEmpty()) {
            request.putOtherTextParam("app_auth_token", appAuthToken);
        }
        AlipayAipayNowpayChargeQueryResponse 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_product_id": "app_writing_001",
  "external_owner_id": "creator_001"
}'

# 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.nowpay.charge.query' \
  --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}"

公共响应参数

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

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

业务响应参数

协议核对:当前开放平台预览将 status_version 定义为 String;本稿依据现有实现整理为 Number 整数。联调需确认最终返回类型,确认前建议兼容字符串和数字版本号。

参数类型是否必选最大长度描述注意事项/枚举值示例值
capability_statusString必选32商品收费能力状态NOT_CONFIGURED / CONFIGURING / PENDING / ACTION_REQUIRED / ENABLED / DISABLED / TERMINATEDENABLED
product_nameString可选32商品名称-智能写作助手
product_icon_urlString可选1024商品图标-https://platform.example.com/assets/writing.png
status_versionNumber可选32状态版本整数版本号;用于记录状态版本,不作为启停入参1
billing_modeString可选32最终收费模式永久买断:ONE_TIME;时长包:ONE_TIME_DURATION;额度包:QUANTITYQUANTITY
quota_unitString特殊可选32额度包返回billing_mode=QUANTITY 时使用;COUNT:次数,POINT:积分COUNT
charging_optionsChargingOption[]必选-当前商品的收费档位列表可能为空数组;子字段必选性适用于实际返回的档位元素-
charging_options[].sku_idString必选32档位标识,平台原样回传按不透明标识保存和回传,不解析内容S0806000200863003
charging_options[].plan_idString必选32价格计划标识按不透明标识保存和回传,不解析内容PI0806000200864210
charging_options[].display_nameString必选32档位名称-20次包
charging_options[].billing_modeString必选32档位类型永久买断:ONE_TIME;时长包:ONE_TIME_DURATION;额度包:QUANTITYQUANTITY
charging_options[].priceString必选32展示价格,十进制,单位元-1.00
charging_options[].currencyString必选32货币类型-CNY
charging_options[].price_versionNumber必选32价格快照版本整数;价格快照版本,仅展示和记录,不作为购买请求参数1
charging_options[].entitlement_ruleString必选32权益类型PERPETUAL:买断;FIXED_DURATION:时长包;QUOTA:额度包QUOTA
charging_options[].duration_periodString特殊可选32时长包周期类型billing_mode=ONE_TIME_DURATION 时返回;WEEK / MONTH / QUARTER / YEARWEEK
charging_options[].quota_unitString特殊可选32额度类型billing_mode=QUANTITY 时使用;COUNT:次数,POINT:积分COUNT
charging_options[].quota_amountNumber特殊可选32次数或积分数量,单位个billing_mode=QUANTITY 时返回;购买该档位增加的整数额度20
management_urlString特殊可选1024平台直接使用该地址进入商品管理已配置状态返回;初始化返回已配置错误时,调用 charge.query 获取管理入口alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET
reason_messageString可选256用于展示的状态说明--

结果处理

capability_status含义平台处理
NOT_CONFIGURED尚未初始化调用 charge.initialize
CONFIGURING配置尚未完成调用 charge.initialize 继续原配置
PENDING等待审核或发布打开 management_url 查看进度
ACTION_REQUIRED需要创作者处理打开 management_url 完成处理
ENABLED允许新增购买展示购买入口,管理操作使用 management_url
DISABLED停止新增购买隐藏新购买入口;原有权益按对应接口判断
TERMINATED商品已归档进入 management_url 查看状态,不新建购买入口

响应示例

以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。

{
  "alipay_aipay_nowpay_charge_query_response": {
    "code": "10000",
    "msg": "Success",
    "capability_status": "ENABLED",
    "product_name": "智能写作助手",
    "product_icon_url": "https://platform.example.com/assets/writing.png",
    "status_version": 1,
    "billing_mode": "QUANTITY",
    "quota_unit": "COUNT",
    "charging_options": [
      {
        "sku_id": "S0806000200863003",
        "plan_id": "PI0806000200864210",
        "display_name": "20次包",
        "billing_mode": "QUANTITY",
        "price": "1.00",
        "currency": "CNY",
        "price_version": 1,
        "entitlement_rule": "QUOTA",
        "quota_unit": "COUNT",
        "quota_amount": 20
      }
    ],
    "management_url": "alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}
{
  "alipay_aipay_nowpay_charge_query_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

公共错误码

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

业务错误码

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

错误码错误描述解决方案
SYSTEM_ERROR系统繁忙稍后使用原参数重试;消费结果未知时先查询原请求
INVALID_PARAMETER参数有误请根据接口返回的参数非法的具体错误信息,修改参数后进行重试
NOW_PAY_PLATFORM_NOT_FOUND平台身份未配置联系即刻收平台管理员补充该平台的身份映射