# 商品收费能力查询接口

## 接口说明

接口名称：`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 | 商户请求参数的签名串，详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` |
| `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 | 已获授权的第三方代调用场景使用的应用授权令牌，详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - |
| `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串，字段使用 snake_case；详见下表 | - |

## 业务请求参数

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

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`，从管理小程序商品详情页复制 | 使用当前商户创建的商品；不要自行生成或使用内部商品号 | `np_d_f83a7c91` |

## 常见请求示例

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

::::aipay-tabs{defaultActiveKey="Java"}

:::aipay-tab{key="Java" title="Java"}
```java
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());
    }
}
```
:::

:::aipay-tab{key="cURL" title="cURL"}
```bash
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` | 商品已归档 | 不新增购买，在小程序查看状态 |

## 响应示例

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

::::aipay-tabs{defaultActiveKey="正常示例"}

:::aipay-tab{key="正常示例" title="正常示例"}
```json
{
  "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"
}
```
:::

:::aipay-tab{key="异常示例" title="异常示例"}
```json
{
  "alipay_aipay_nowpaydirect_charge_query_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

::::

## 公共错误码

参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时，按原请求查询或重试；写操作不能在结果未确认时更换幂等号。

## 业务错误码

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

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