商品收费能力查询接口
更新时间:
接口说明
接口名称:alipay.aipay.nowpay.charge.query
查询平台商品的收费能力状态、收费模式和可售档位,并获取商品管理入口。平台可据此展示收费配置入口、选择购买流程和刷新商品状态。
支持已获授权的第三方代理调用。所有接口由平台服务端调用。
适用场景
- 进入商品收费设置页,判断应初始化配置还是进入管理页。
- 配置、启停操作结束后刷新状态和可售档位。
- 读取
billing_mode,选择访问决策流程或额度包流程。
注意事项
NOT_CONFIGURED、CONFIGURING:继续调用charge.initialize获取configuration_url;其余已配置状态使用management_url进入管理页。capability_status描述商品新增购买能力。用户是否可访问应查询purchase.consult;额度包的余额和扣减结果分别查询quota.query、quota.verify。charging_options可能为空。sku_id、plan_id都按不透明标识保存;价格、价格版本和档位列表只用于展示与选择,不由平台拼装支付订单。- 遇到未知状态或查询失败时,不自动放行付费访问;展示处理中并刷新,必要时进入返回的管理入口。
公共请求参数
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
app_id | String | 必选 | 32 | 支付宝分配给开发者的应用ID | YOUR_APP_ID |
method | String | 必选 | 128 | 接口名称 | alipay.aipay.nowpay.charge.query |
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” | 2026-09-07 10:00:00 |
version | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | 1.0 |
app_auth_token | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见应用授权概述 | - |
biz_content | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - |
业务请求参数
业务字段统一放入 biz_content。下表数组子字段使用 [] 表示元素路径。
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
|---|---|---|---|---|---|---|
out_product_id | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | app_writing_001 |
external_owner_id | String | 必选 | 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}"公共响应参数
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
code | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | 10000 |
msg | String | 必选 | - | 网关返回码说明 | Success |
sub_code | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - |
sub_msg | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - |
sign | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - |
响应业务对象名为 alipay_aipay_nowpay_charge_query_response。先完成验签并判断 code,再读取业务结果。
业务响应参数
协议核对:当前开放平台预览将
status_version定义为 String;本稿依据现有实现整理为 Number 整数。联调需确认最终返回类型,确认前建议兼容字符串和数字版本号。
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
|---|---|---|---|---|---|---|
capability_status | String | 必选 | 32 | 商品收费能力状态 | NOT_CONFIGURED / CONFIGURING / PENDING / ACTION_REQUIRED / ENABLED / DISABLED / TERMINATED | ENABLED |
product_name | String | 可选 | 32 | 商品名称 | - | 智能写作助手 |
product_icon_url | String | 可选 | 1024 | 商品图标 | - | https://platform.example.com/assets/writing.png |
status_version | Number | 可选 | 32 | 状态版本 | 整数版本号;用于记录状态版本,不作为启停入参 | 1 |
billing_mode | String | 可选 | 32 | 最终收费模式 | 永久买断:ONE_TIME;时长包:ONE_TIME_DURATION;额度包:QUANTITY | QUANTITY |
quota_unit | String | 特殊可选 | 32 | 额度包返回 | billing_mode=QUANTITY 时使用;COUNT:次数,POINT:积分 | COUNT |
charging_options | ChargingOption[] | 必选 | - | 当前商品的收费档位列表 | 可能为空数组;子字段必选性适用于实际返回的档位元素 | - |
charging_options[].sku_id | String | 必选 | 32 | 档位标识,平台原样回传 | 按不透明标识保存和回传,不解析内容 | S0806000200863003 |
charging_options[].plan_id | String | 必选 | 32 | 价格计划标识 | 按不透明标识保存和回传,不解析内容 | PI0806000200864210 |
charging_options[].display_name | String | 必选 | 32 | 档位名称 | - | 20次包 |
charging_options[].billing_mode | String | 必选 | 32 | 档位类型 | 永久买断:ONE_TIME;时长包:ONE_TIME_DURATION;额度包:QUANTITY | QUANTITY |
charging_options[].price | String | 必选 | 32 | 展示价格,十进制,单位元 | - | 1.00 |
charging_options[].currency | String | 必选 | 32 | 货币类型 | - | CNY |
charging_options[].price_version | Number | 必选 | 32 | 价格快照版本 | 整数;价格快照版本,仅展示和记录,不作为购买请求参数 | 1 |
charging_options[].entitlement_rule | String | 必选 | 32 | 权益类型 | PERPETUAL:买断;FIXED_DURATION:时长包;QUOTA:额度包 | QUOTA |
charging_options[].duration_period | String | 特殊可选 | 32 | 时长包周期类型 | billing_mode=ONE_TIME_DURATION 时返回;WEEK / MONTH / QUARTER / YEAR | WEEK |
charging_options[].quota_unit | String | 特殊可选 | 32 | 额度类型 | billing_mode=QUANTITY 时使用;COUNT:次数,POINT:积分 | COUNT |
charging_options[].quota_amount | Number | 特殊可选 | 32 | 次数或积分数量,单位个 | billing_mode=QUANTITY 时返回;购买该档位增加的整数额度 | 20 |
management_url | String | 特殊可选 | 1024 | 平台直接使用该地址进入商品管理 | 已配置状态返回;初始化返回已配置错误时,调用 charge.query 获取管理入口 | alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET |
reason_message | String | 可选 | 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 | 平台身份未配置 | 联系即刻收平台管理员补充该平台的身份映射 |