商品收费配置初始化接口

更新时间：2026-09-08 22:24:06

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

接口说明

接口名称：alipay.aipay.nowpay.charge.initialize

为平台商品创建或复用收费配置申请，返回支付宝托管配置页入口。创作者在托管页完成账号绑定、收费模式与档位配置；平台在配置结束后查询最新收费能力。

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

适用场景

创作者首次为平台应用开通收费。
收费状态为 NOT_CONFIGURED 或 CONFIGURING，需要进入或继续完成配置。

注意事项

先调用 charge.query；仅在 NOT_CONFIGURED 或 CONFIGURING 时初始化。配置完成后再次初始化可能返回 NOW_PAY_ALREADY_CONFIGURED，应重新查询并使用 management_url。
pricing_mode_list 描述初始化时提供的收费模式提示，价格与实际档位由创作者在托管页设置。同一商品最终采用一种收费模式，可在该模式下配置多个档位。平台应以配置后的 charge.query 结果为准。
按公开请求协议传入非空 pricing_mode_list，QUANTITY 项传入 quota_unit。price 为兼容字段，本产品接入时不传；初始化成功不表示收费能力已启用。
使用稳定的 out_product_id 和 external_owner_id；重试保持请求一致。配置尚未完成时复用原申请；已配置商品的启停使用 charge.modify。
callback_url 是配置完成后的页面返回地址，不是服务端异步通知地址。返回后调用 charge.query 确认状态。配置页链接与二维码使用本次接口实际返回值。

公共请求参数

参数	类型	是否必选	最大长度	描述	示例值
`app_id`	String	必选	32	支付宝分配给开发者的应用ID	`YOUR_APP_ID`
`method`	String	必选	128	接口名称	`alipay.aipay.nowpay.charge.initialize`
`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`
`product_name`	String	必选	128	商品名称	-	`智能写作助手`
`product_icon_url`	String	可选	1024	商品图标链接地址	-	`https://platform.example.com/assets/writing.png`
`product_url`	String	可选	1024	商品详情页	-	`https://platform.example.com/apps/app_writing_001`
`callback_url`	String	可选	1024	配置完成返回平台地址	页面返回地址，不是异步通知地址；返回后重新查询状态	`https://platform.example.com/nowpay/config-return`
`pricing_mode_list`	PricingMode[]	必选	-	初始化收费模式提示列表	按公开协议至少传一项；实际模式与价格以托管页配置及后续查询为准	-
`pricing_mode_list[].billing_mode`	String	必选	32	计费模式	永久买断:`ONE_TIME`；时长包:`ONE_TIME_DURATION`；额度包:`QUANTITY`	`QUANTITY`
`pricing_mode_list[].quota_unit`	String	特殊可选	32	`QUANTITY` 必填：`COUNT`/`POINT`	`billing_mode`=`QUANTITY` 时使用；`COUNT`：次数，`POINT`：积分	`COUNT`
`pricing_mode_list[].price`	String	可选	32	兼容保留的价格字段，单位元	本产品初始化时不传；价格在托管配置页设置	-

常见请求示例

示例商品、用户、域名及请求号均为演示值。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.AlipayAipayNowpayChargeInitializeRequest;
import com.alipay.api.response.AlipayAipayNowpayChargeInitializeResponse;

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

        AlipayAipayNowpayChargeInitializeRequest request = new AlipayAipayNowpayChargeInitializeRequest();
        request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"product_name\":\"智能写作助手\",\"product_icon_url\":\"https://platform.example.com/assets/writing.png\",\"product_url\":\"https://platform.example.com/apps/app_writing_001\",\"callback_url\":\"https://platform.example.com/nowpay/config-return\",\"pricing_mode_list\":[{\"billing_mode\":\"QUANTITY\",\"quota_unit\":\"COUNT\"}]}");
        // 仅在已获授权的第三方代调用场景设置 app_auth_token。
        String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        if (appAuthToken != null && !appAuthToken.isEmpty()) {
            request.putOtherTextParam("app_auth_token", appAuthToken);
        }
        AlipayAipayNowpayChargeInitializeResponse 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",
  "product_name": "智能写作助手",
  "product_icon_url": "https://platform.example.com/assets/writing.png",
  "product_url": "https://platform.example.com/apps/app_writing_001",
  "callback_url": "https://platform.example.com/nowpay/config-return",
  "pricing_mode_list": [
    {
      "billing_mode": "QUANTITY",
      "quota_unit": "COUNT"
    }
  ]
}'

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

业务响应参数

参数	类型	是否必选	最大长度	描述	注意事项/枚举值	示例值
`configuration_url`	String	特殊可选	1024	需要继续配置时返回	配置未完成时返回	`alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fconfig%2Findex%3Fticket%3DSAMPLE_TICKET`
`configuration_qr_code`	String	特殊可选	1024	配置入口二维码	配置未完成时返回	`https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE`
`management_url`	String	特殊可选	1024	已完成配置时返回	已配置状态返回；初始化返回已配置错误时，调用 `charge.query` 获取管理入口	`alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET`

结果处理

收到成功响应后打开 configuration_url，或展示 configuration_qr_code 引导创作者操作。返回平台后调用查询收费能力和档位；只有状态为 ENABLED 才展示新的购买入口。已配置错误需走查询获取管理入口，不能依赖失败响应中的链接。

响应示例

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

{
  "alipay_aipay_nowpay_charge_initialize_response": {
    "code": "10000",
    "msg": "Success",
    "configuration_url": "alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fconfig%2Findex%3Fticket%3DSAMPLE_TICKET",
    "configuration_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}

{
  "alipay_aipay_nowpay_charge_initialize_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

公共错误码

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

业务错误码

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

错误码	错误描述	解决方案
`SYSTEM_ERROR`	系统繁忙	稍后使用原参数重试；消费结果未知时先查询原请求
`INVALID_PARAMETER`	参数有误	请根据接口返回的参数非法的具体错误信息，修改参数后进行重试
`NOW_PAY_ALREADY_CONFIGURED`	商品已完成初始化配置，无法重复配置	调用 `charge.query`，获取 `management_url` 进入管理页