商品收费能力查询接口

更新时间：2026-09-29 15:22:37

以 Markdown 格式查看 LLM请查看llms.txt

商品收费能力查询接口

接口说明

接口名称：alipay.aipay.nowpaydirect.charge.query

查询当前商户在管理小程序中创建的直连商品，获取收费状态、收费模式、档位与商品管理入口。商品配置和上下架由商户在管理小程序操作。

适用场景

商品完成小程序配置后，验证商品 ID、收费状态和档位。
在应用中展示商品价格、选择购买档位。
商户在小程序处理审核或上下架后，刷新商品状态。

注意事项

out_product_id 从管理小程序商品详情页复制，商品需属于本次请求的商户。直连模式无需调用收费初始化或启停 OpenAPI。
只有 ENABLED 表示允许新增购买。NOT_CONFIGURED 时核对商品 ID 和商户账号；CONFIGURING、PENDING、ACTION_REQUIRED 时到管理小程序继续配置或处理审核。
capability_status 描述商品新增购买能力。用户是否可访问查询 purchase.consult；额度余额与扣减分别使用 quota.query、quota.verify。
charging_options 按数组处理，可能为空；商品不可售时也可能保留档位，不能仅凭档位非空展示新购买入口。billing_mode 从查询到的档位得出，未配置或档位缺失时可能为空。
management_url 供商户管理商品；终端用户购买应使用 purchase.consult 或 purchase.create 返回的入口。

公共请求参数

参数	类型	是否必选	最大长度	描述	示例值
`app_id`	String	必选	32	支付宝分配给开发者的应用ID	`YOUR_APP_ID`
`method`	String	必选	128	接口名称	`alipay.aipay.nowpaydirect.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-27 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	直连商品的外部商品 `ID`，从管理小程序商品详情页复制	使用当前商户创建的商品；不要自行生成或使用内部商品号	`np_d_f83a7c91`

常见请求示例

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

import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpaydirectChargeQueryRequest;
import com.alipay.api.response.AlipayAipayNowpaydirectChargeQueryResponse;

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

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

# 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.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_nowpaydirect_charge_query_response。先完成验签并判断 code，再读取业务结果。

业务响应参数

参数	类型	是否必选	最大长度	描述	注意事项/枚举值	示例值
`capability_status`	String	必选	32	商品收费能力状态	`NOT_CONFIGURED` / `CONFIGURING` / `PENDING` / `ACTION_REQUIRED` / `ENABLED` / `DISABLED` / `TERMINATED`	`ENABLED`
`product_name`	String	特殊可选	32	商品名称	配置尚不存在时可能缺省，不因缺少名称认定收费已启用	`智能写作助手`
`product_icon_url`	String	可选	1024	商品图标	-	`https://app.example.com/assets/writing.png`
`billing_mode`	String	可选	32	最终收费模式	永久买断:`ONE_TIME`；时长包:`ONE_TIME_DURATION`；额度包:`QUANTITY`	`QUANTITY`
`quota_unit`	String	特殊可选	32	额度包单位	`billing_mode`=`QUANTITY` 时使用；`COUNT`：次数，`POINT`：积分	`COUNT`
`charging_options`	Object[]	必选	-	当前商品的收费档位列表	可能为空数组；子字段必选性适用于实际返回的档位元素	-
`charging_options[].sku_id`	String	必选	32	档位标识	按不透明标识保存和回传，不解析内容	`S0806000200863003`
`charging_options[].display_name`	String	必选	128	档位名称	-	`20次包`
`charging_options[].price`	String	必选	32	展示价格，十进制，单位元	-	`1.00`
`charging_options[].duration_period`	String	特殊可选	32	时长包周期类型	`billing_mode`=`ONE_TIME_DURATION` 时返回；`WEEK` / `MONTH` / `QUARTER` / `YEAR`	`WEEK`
`charging_options[].quota_amount`	Number	特殊可选	32	额度数量	`billing_mode`=`QUANTITY` 时返回；购买该档位增加的整数额度	`20`
`management_url`	String	可选	1024	使用该地址进入商品管理	供商品所有者进入管理小程序；不要作为面向购买用户的购买入口	`alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET`

结果处理

capability_status	含义	应用或商户处理
`NOT_CONFIGURED`	未找到收费配置	核对当前商户及小程序复制的商品 ID，在小程序完成配置
`CONFIGURING`	配置尚未完成	商户在小程序继续配置
`PENDING`	等待审核或发布	在小程序查看进度
`ACTION_REQUIRED`	需要商户处理	在小程序处理认证、签约或商品资料
`ENABLED`	允许新增购买	展示购买入口
`DISABLED`	停止新增购买	隐藏新购买入口；已有权益按权益或额度接口判断
`TERMINATED`	商品已归档	不新增购买，在小程序查看状态

响应示例

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

{
  "alipay_aipay_nowpaydirect_charge_query_response": {
    "code": "10000",
    "msg": "Success",
    "capability_status": "ENABLED",
    "product_name": "智能写作助手",
    "product_icon_url": "https://app.example.com/assets/writing.png",
    "billing_mode": "QUANTITY",
    "quota_unit": "COUNT",
    "charging_options": [
      {
        "sku_id": "S0806000200863003",
        "display_name": "20次包",
        "price": "1.00",
        "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_nowpaydirect_charge_query_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

公共错误码

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

业务错误码

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

错误码	错误描述	解决方案
`SYSTEM_ERROR`	系统繁忙	稍后使用原参数重试；消费结果未知时先查询原请求
`INVALID_PARAMETER`	参数有误	请根据接口返回的参数非法的具体错误信息，修改参数后进行重试