接口说明
接口名称:alipay.trade.price.query
支持第三方代理调用:本接口支持第三方开发者代用户发起调用。
适用场景
价格查询接口。
公共请求参数
参数 类型 是否必选 最大长度 描述 示例值 app_idString 必选 32 支付宝分配给开发者的应用 ID 2014072300007148methodString 必选 128 接口名称 alipay.trade.price.queryformatString 可选 40 仅支持JSON JSONcharsetString 必选 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8sign_typeString 必选 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2signString 必选 344 商户请求参数的签名串,详见签名 详见示例timestampString 必选 19 发送请求的时间,格式”yyyy-MM-dd HH:mm
” 2014-07-24 03:07:50versionString 必选 3 调用的接口版本,固定为:1.0 1.0app_auth_tokenString 可选 40 详见应用授权概述 - biz_contentString 必选 - 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 -
业务请求参数
参数 类型 是否必选 最大长度 描述 注意事项/枚举值 示例值 price_idString 必选 32 价格 ID - 202603240020000001001query_optionsString 可选 32 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持: product:商品信息 - ["product"]
常见请求示例
Java
package com.java.sdk.demo;
import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.response.AlipayTradePriceQueryResponse;
import com.alipay.api.request.AlipayTradePriceQueryRequest;
import com.alipay.api.domain.AlipayTradePriceQueryModel;
import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;
public class AlipayTradePriceQuery {
public static void main ( String [] args ) throws AlipayApiException {
// 初始化SDK
AlipayClient alipayClient = new DefaultAlipayClient ( getAlipayConfig ());
// 构造请求参数以调用接口
AlipayTradePriceQueryRequest request = new AlipayTradePriceQueryRequest ();
AlipayTradePriceQueryModel model = new AlipayTradePriceQueryModel ();
// 设置价格id
model. setPriceId ( "202603240020000001001" );
// 设置查询选项
List< String > queryOptions = new ArrayList< String >();
queryOptions. add ( "product" );
model. setQueryOptions (queryOptions);
request. setBizModel (model);
// 第三方代调用模式下请设置app_auth_token
// request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");
AlipayTradePriceQueryResponse response = alipayClient. execute (request);
System.out. println (response. getBody ());
if (response. isSuccess ()) {
System.out. println ( "调用成功" );
} else {
System.out. println ( "调用失败" );
// sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
// String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
// System.out.println(diagnosisUrl);
}
}
private static AlipayConfig getAlipayConfig () {
String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->" ;
String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->" ;
AlipayConfig alipayConfig = new AlipayConfig ();
alipayConfig. setServerUrl ( "https://openapi.alipay.com/gateway.do" );
alipayConfig. setAppId ( "<-- 请填写您的AppId,例如:2019091767145019 -->" );
alipayConfig. setPrivateKey (privateKey);
alipayConfig. setFormat ( "json" );
alipayConfig. setAlipayPublicKey (alipayPublicKey);
alipayConfig. setCharset ( "UTF-8" );
alipayConfig. setSignType ( "RSA2" );
return alipayConfig;
}
}
PHP
<? php
require_once '../aop/AopClient.php' ;
require_once '../aop/AopCertClient.php' ;
require_once '../aop/AopCertification.php' ;
require_once '../aop/AlipayConfig.php' ;
require_once '../aop/request/AlipayTradePriceQueryRequest.php' ;
// 初始化SDK
$alipayClient = new AopClient ( getAlipayConfig ());
// 构造请求参数以调用接口
$request = new AlipayTradePriceQueryRequest ();
$model = array ();
// 设置价格id
$model[ 'price_id' ] = "202603240020000001001" ;
// 设置查询选项
$queryOptions = array ();
$queryOptions[] = "product" ;
$model[ 'query_options' ] = $queryOptions;
$request -> setBizContent ( json_encode ($model, JSON_UNESCAPED_UNICODE ));
// 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌)
$responseResult = $alipayClient -> execute ($request, null , "<-- 请填写应用授权令牌 -->" , null );
$responseApiName = str_replace ( "." , "_" ,$request -> getApiMethodName ()) . "_response" ;
$response = $responseResult -> $responseApiName;
if ( ! empty ($response -> code) && $response -> code == 10000 ){
echo ( "调用成功" );
}
else {
echo ( "调用失败" );
}
function getAlipayConfig ()
{
$privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->' ;
$alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->' ;
$alipayConfig = new AlipayConfig ();
$alipayConfig -> setServerUrl ( 'https://openapi.alipay.com/gateway.do' );
$alipayConfig -> setAppId ( '<-- 请填写您的AppId,例如:2019091767145019 -->' );
$alipayConfig -> setPrivateKey ($privateKey);
$alipayConfig -> setFormat ( 'json' );
$alipayConfig -> setAlipayPublicKey ($alipayPublicKey);
$alipayConfig -> setCharset ( 'UTF-8' );
$alipayConfig -> setSignType ( 'RSA2' );
return $alipayConfig;
}
C#
using System ;
using System . Collections . Generic ;
using Aop . Api ;
using Aop . Api . Request ;
using Aop . Api . Response ;
using Aop . Api . Domain ;
using Aop . Api . Util ;
namespace SdkDemoTest
{
public class AlipayTradePriceQuery
{
public static void Main ( string [] args )
{
// 初始化SDK
IAopClient alipayClient = new DefaultAopClient ( GetAlipayConfig ());
// 构造请求参数以调用接口
AlipayTradePriceQueryRequest request = new AlipayTradePriceQueryRequest ();
AlipayTradePriceQueryModel model = new AlipayTradePriceQueryModel ();
// 设置价格id
model.PriceId = "202603240020000001001" ;
// 设置查询选项
List < String > queryOptions = new List < String >();
queryOptions. Add ( "product" );
model.QueryOptions = queryOptions;
request. SetBizModel (model);
// 第三方代调用模式下请设置app_auth_token
// request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");
AlipayTradePriceQueryResponse response = alipayClient. Execute (request);
if ( ! response.IsError)
{
Console. WriteLine ( "调用成功" );
}
else
{
Console. WriteLine ( "调用失败" );
}
}
private static AlipayConfig GetAlipayConfig ()
{
string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->" ;
string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->" ;
AlipayConfig alipayConfig = new AlipayConfig ();
alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do" ;
alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->" ;
alipayConfig.PrivateKey = privateKey;
alipayConfig.Format = "json" ;
alipayConfig.AlipayPublicKey = alipayPublicKey;
alipayConfig.Charset = "UTF-8" ;
alipayConfig.SignType = "RSA2" ;
return alipayConfig;
}
}
}
cURL
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \
-F 'app_auth_token=${app_auth_token}' \
-F 'biz_content={
"price_id":"202603240020000001001",
"query_options":[
"product"
]
}'
公共响应参数
参数 类型 是否必选 描述 示例值 code String 必选 网关返回码,详见文档 40004 msg String 必选 网关返回码描述,详见文档 Business Failed sub_code String 可选 业务返回码,参见具体的 API 接口文档 - sub_msg String 可选 业务返回码描述,参见具体的 API 接口文档 - sign String 必选 签名,详见文档 DZXh8eeTuAHoYE3w1J…
业务响应参数
参数 类型 是否必选 最大长度 描述 注意事项/枚举值 示例值 idString 必选 32 价格 ID - 202603240020000001001activeBoolean 必选 10 该价格实例是否可用 - trueproduct_idString 必选 32 关联商品 ID - 202603240020000001001unit_amountNumber 特殊可选 100000000 单位金额,单位:分,当 custom_unit_amount 为空时必选 当 custom_unit_amount 为空时必选 1000custom_unit_amountCustomUnitAmount 特殊可选 - 自定义单价,当 unit_amount 为空时必选 当 unit_amount 为空时必选 - custom_unit_amount.enableBoolean 必选 10 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 - truecustom_unit_amount.presetNumber 可选 32 预设的自定义价格(单位:分),灵活定价开启后可设置 - 88888custom_unit_amount.maximumNumber 可选 32 可自定义的最大金额(单位:分),灵活定价开启后可设置 - 1000000000custom_unit_amount.minimumNumber 可选 32 可自定义的最小金额(单位:分),灵活定价开启后可设置 - 100productNexusPayProduct 可选 - 关联的商品信息 - - product.idString 必选 32 商品 ID - 20260324001001product.nameString 必选 255 商品名称 - Gold 会员product.descriptionString 必选 255 商品描述 - 基础权益product.activeBoolean 必选 10 是否可用 - trueproduct.default_price_idString 可选 32 商品的默认价格 ID - 20260324001001product.default_priceNexusSimplePrice 可选 - 默认价格信息 - - product.default_price.idString 必选 32 价格 ID - 20260324001001product.default_price.activeBoolean 必选 10 是否可用 - trueproduct.default_price.typeString 必选 32 价格类型 订阅:recurring 单次支付:one_time recurringproduct.default_price.unit_amountNumber 必选 32 单位金额,单位:分 - 1000product.default_price.recurringRecurring 必选 - 订阅周期信息 - - product.default_price.recurring.intervalString 可选 16 订阅周期类型,目前支持DAY跟MONTH 月:MONTH 天:DAY MONTHproduct.default_price.recurring.interval_countNumber 可选 32 订阅周期数量,目前周期单位只支持月或日 - 1product.default_price.recurring.usage_typeString 可选 16 计费模式 固定计费:licensed 按量计费:metered licensedproduct.default_price.recurring.trial_period_daysNumber 可选 32 试用期天数 - 10product.default_price.metadataString 可选 2000 价格信息元数据 - {"key":"value"}product.default_price.custom_unit_amountCustomUnitAmount 可选 - 自定义单价,当 unit_amount 为空时必选 - - product.default_price.custom_unit_amount.enableBoolean 必选 10 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 - trueproduct.default_price.custom_unit_amount.presetNumber 可选 32 预设的自定义价格(单位:分),灵活定价开启后可设置 - 88888product.default_price.custom_unit_amount.maximumNumber 可选 32 可自定义的最大金额(单位:分),灵活定价开启后可设置 - 1000000000product.default_price.custom_unit_amount.minimumNumber 可选 32 可自定义的最小金额(单位:分),灵活定价开启后可设置 - 100product.metadataString 可选 2000 商品信息元数据,通过商品创建接口传入 - {"key":"value"}product.gmt_createString 必选 64 创建时间 - 2026-03-24 18:00:00typeString 必选 32 价格类型 订阅:recurring 单次支付:one_time recurringrecurringRecurringConfig 可选 - 循环计价配置,用于订阅等场景 - - recurring.intervalString 必选 32 计价周期单位,和interval_count组合使用 月:MONTH 年:YEAR 日:DAY MONTHrecurring.interval_countNumber 必选 32 计价周期间隔,和interval组合使用 - 1eligibility_typeString 可选 32 只有满足该类型的身份才可以购买。具体的枚举值待支付宝侧分配 - "student"eligibility_expire_timeString 可选 32 满足了eligibility_type的身份购买后,失效的时间。如3d = 3天, 3m = 3月 - "3d"metadataString 必选 2000 商户需要保存在价格模型中的元数据 - {"key":"value"}gmt_createString 必选 64 创建时间 - 2026-03-24
响应示例
正常示例
{
"alipay_trade_price_query_response" :{
"code" : "10000" ,
"msg" : "Success" ,
"id" : "202603240020000001001" ,
"active" : true ,
"product_id" : "202603240020000001001" ,
"unit_amount" : 1000 ,
"custom_unit_amount" :{
"enable" : true ,
"preset" : 88888 ,
"maximum" : 1000000000 ,
"minimum" : 100
},
"product" :{
"id" : "20260324001001" ,
"name" : "Gold 会员" ,
"description" : "基础权益" ,
"active" : true ,
"default_price_id" : "20260324001001" ,
"default_price" :{
"id" : "20260324001001" ,
"active" : true ,
"type" : "recurring" ,
"unit_amount" : 1000 ,
"recurring" :{
"interval" : "MONTH" ,
"interval_count" : 1 ,
"usage_type" : "licensed" ,
"trial_period_days" : 10
},
"metadata" : "{ \" key \" : \" value \" }" ,
"custom_unit_amount" :{
"enable" : true ,
"preset" : 88888 ,
"maximum" : 1000000000 ,
"minimum" : 100
}
},
"metadata" : "{ \" key \" : \" value \" }" ,
"gmt_create" : "2026-03-24 18:00:00"
},
"type" : "recurring" ,
"recurring" :{
"interval" : "MONTH" ,
"interval_count" : 1
},
"eligibility_type" : " \" student \" " ,
"eligibility_expire_time" : " \" 3d \" " ,
"metadata" : "{ \" key \" : \" value \" }" ,
"gmt_create" : "2026-03-24"
},
"sign" : "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
异常示例
{ "alipay_trade_price_query_response" :{ "code" : "20000" , "msg" : "Service Currently Unavailable" , "sub_code" : "isp.unknow-error" , "sub_msg" : "系统繁忙" }, "sign" : "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" }
业务错误码
错误码 错误描述 解决方案 SYSTEM_ERROR系统繁忙 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 INVALID_PARAMETER参数有误 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 APP_ID_NOT_MATCH应用 ID与价格所属应用不匹配 应用 ID与价格所属应用不匹配,请检查传入的价格ID是否正确 PRICE_NOT_EXIST价格不存在 请检查传入的价格ID是否正确