现金抵价券快速接入

本文档展示了如何使用蚂蚁金服开放平台服务端SDK快速接入支付宝现金抵价券产品,完成与支付宝的对接部分。
本文档主要面向的读者为各有需求接入支付宝现金抵价券产品的,有一定开发能力的ISV技术人员。
注意:文档中的代码示例和Demo是用来阐述API基本使用方法的,仅针对大众场景。供ISV参考,特殊情况还请ISV自行扩展,确保符合自身业务需求。

第一步:创建应用

要在您的应用中使用支付宝开放产品的接口能力:

  1. 您需要先去蚂蚁金服开放平台(open.alipay.com),在开发者中心创建登记您的应用,此时您将获得应用唯一标识(APPID);
  2. 请在【功能信息】中点击【添加功能】,选择【支付宝现金抵价券】;
  3. 提交审核,等待审核通过,该应用正式可以使用。
    需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步:配置密钥

开发者调用接口前需要先生成RSA密钥,RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY)。生成密钥后在开放平台管理中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步:搭建和配置开发环境

1.下载服务端SDK

为了帮助开发者调用开放接口,我们提供了开放平台服务端SDK,包含JAVA、PHP和.NET三个语言版本,封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。
各语言版本服务端SDK详细使用说明,请参考《服务端SDK使用说明

2.接口调用配置

在SDK调用前需要进行初始化,代码如下:

AlipayClient alipayClient = new DefaultAlipayClient(URL,APP_ID,APP_PRIVATE_KEY,FORMAT,CHARSET,ALIPAY_PUBLIC_KEY,SIGN_TYPE);

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关(固定) https://openapi.alipay.com/gateway.do
APPID APPID即创建应用后生成 获取见上面【创建应用】
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面【配置秘钥】
FORMAT 参数返回格式,只支持json json(固定)
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面【配置秘钥】
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2

接下来,就可以用alipayClient来调用具体的API了。alipayClient只需要初始化一次,后续调用不同的API都可以使用同一个alipayClient对象。

TIPS:ISV/开发者可以通过“第三方应用授权”得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力;具体方法请参考第三方应用授权

第四步:接口调用

场景:创建现金抵价券模板

场景描述

在商户产生针对支付宝用户的现金券发放需求时,需先调用该接口进行现金券的创建。

接口调用流程

image.png

上图接入流程中,商户如果与开发者为同一角色,可省略掉授权环节。

使用SDK快速接入

创建支付宝现金抵价券接口:alipay.marketing.cashvoucher.template.create

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCashvoucherTemplateCreateRequest request = new AlipayMarketingCashvoucherTemplateCreateRequest();//创建API对应的request类
request.setBizContent("{" +
"\"voucher_type\":\"FIX_VOUCHER\"," +
"\"voucher_use_scene\":\"ALIPAY_RECHARGE\"," +
"\"fund_account\":\"13040045386\"," +
"\"brand_name\":\"支付宝\"," +
"\"publish_start_time\":\"2017-12-01 00:00:01\"," +
"\"publish_end_time\":\"2017-12-29 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\":\\\"ABSOLUTE\\\",\\\"start\\\":\\\"2017-01-1000:00:00\\\",\\\"end\\\":\\\"2017-01-1323:59:59\\\"}\"," +
"\"floor_amount\":50.0," +
"\"voucher_description\":\"[\\\"1、本券不可兑换现金,不可找零。\\\",\\\"2、每个用户最多可以领取1张。\\\",\\\"3、如果订单发生退款,优惠券无法退还。\\\"]\"," +
"\"out_biz_no\":\"20170101000001654bb46ba\"," +
"\"amount\":8.8," +
"\"voucher_quantity\":1000000," +
"\"redirect_uri\":\"https://www.yourdomain.com/alipay/pay/success\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"," +
"\"rule_conf\":\"{\\\"PID\\\":\\\"2088512417841101,2088512417841102\\\",\\\"STORE\\\":\\\"123456,678901\\\"}\"," +
"\"extension_info\":\"{\\\"useMode\\\":\\\"H5\\\",\\\"useModeData\\\":{\\\"url\\\":\\\"http://www.yourdomian.com/yourusepage.htm\\\",\\\"signType\\\":\\\"RSA2\\\"}}\"" +
"}");//设置业务参数
AlipayMarketingCashvoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称
参数说明
voucher_type
券类型。可枚举,暂时只支持"代金券"(FIX_VOUCHER),使用示例voucher_type=FIX_VOUCHER
voucher_use_scene
券使用场景。可枚举,目前支持“支付宝充值中心话费流量通用现金券”(ALIPAY_RECHARGE),“支付宝缴费业务代金券”(ALIPAY_FEE),“支付宝通用现金代金券”(ALIPAY_COMMON)。场景值会关联当前券的展示模板,默认描述等信息,若需特殊场景接入,请联系技术支持。
fund_account
出资人登录账号。用于发券的资金会从该账号划拨到发券专用账户上
brand_name
创建券模板时录入的品牌信息,由商户自定义,在通用模板中展示在券LOGO下方。根据券使用场景的不同,该信息的展示位置可能会有不同。
 
publish_start_time
发放开始时间,早于该时间不能发券。发放开始时间不能晚于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss
publish_end_time
发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss
voucher_valid_period
券有效期。有两种类型:绝对时间和相对时间。使用JSON字符串表示。绝对时间有3个key:type、start、end,type取值固定为"ABSOLUTE",start和end分别表示券生效时间和失效时间,格式为yyyy-MM-dd HH:mm:ss。绝对时间示例:{"type": "ABSOLUTE", "start": "2017-01-10 00:00:00", "end": "2017-01-13 23:59:59"}。相对时间有3个key:type、duration、unit,type取值固定为"RELATIVE",duration表示从发券时间开始到往后推duration个单位时间为止作为券的使用有效期,unit表示有效时间单位,有效时间单位可枚举:MINUTE, HOUR, DAY。示例:{"type": "RELATIVE", "duration": 1 , "unit": "DAY" },如果此刻发券,那么该券从现在开始生效1(duration)天(unit)后失效。
floor_amount
最低额度。设置券使用门槛,只有订单金额大于等于最低额度时券才能使用。币种为人民币,单位为元。该数值不能小于0,小数点以后最多保留两位。
voucher_description
券使用说明。JSON数组字符串,最多可以有10条,每条最多50字。如果未传入该字段,将填充为默认描述,默认描述同示例值。
out_biz_no
外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号返回相同的模板ID
amount
面额。每张代金券可以抵扣的金额。币种为人民币,单位为元。该数值不能小于0,小数点以后最多保留两位。
voucher_quantity
拟发行券的数量。单位为张。该数值必须是大于0的整数。
redirect_uri
重定向地址。支付成功后需要重定向的地址,如果为空则不做重定向。
notify_uri
券变动异步通知地址,传入此字段后,券的核销将会进行异步通知,通知具体内容见下方触发异步通知字段描述
rule_conf
规则配置,JSON字符串,格式为K-V模式,当同一个KEY下规则为多个值时,用英文逗号进行分隔。目前支持的规则KEY有:核销商户ID(PID),核销内部门店ID(STORE),指定收款账户(payeeUserId),子产品交易码(bizProduct),缴费机构/类型(CUSTOMBUSINESS),缴费户号(EBPPUSERNUM)。一旦商户设置了规则,当前券实例必须满足指定规则才能进行核销。了解更多规则相关具体属性,请联系技术支持。
extension_info
扩展字段,JSON字符串。目前支持使用模式扩展:{"useMode":"H5","useModeData":{"url":"http://www.yourdomian.com/yourusepage.htm","signKeys":"voucherId,userId,tag","charset":"UTF-8","signType":"RSA2","tag":"this is my tag"}}
其中如果useMode表示自定义的使用模式类型,目前仅支持"H5",表示在券详情页按钮跳转至自定义H5页面,当传入useMode参数后,将会检查useModeData对象数据,其中的url为必传参数;url字段表示自定义使用按钮跳转链接,传入该字段后在券详情使用时点击效果将会跳转此链接,链接将进行白名单过滤,如果无法接入成功请联系技术支持;signKeys字段表示跳转至自定义链接时的加签字段,如果不传默认为voucherId,userId,tag;signType为加签类型,目前支持RSA及RSA2,如果不传则不会加签;charset为链接编码格式,不传默认为UTF-8;tag为自定义参数,会直接透传回使用链接;当传入合法加签信息后,券使用链接将为http://www.yourdomain.com/yourusepage.htm?voucherId=当前券id&userId=当前用户id&tag=传入tag&sign=对应算法及key生成的加签数据

关键出参:

参数名称 参数说明
template_id 券模板ID
fund_order_no 资金订单号
confirm_uri 模板支付确认链接

场景:向用户发放支付宝现金抵价券

场景描述:

在商户或开发者完成支付宝现金抵价券模板创建,并付款激活后,即可向用户发放该现金抵价券用于营销支持。

接口调用流程:

image.png

上图流程中,若开发者已通过其他渠道获取到了用户账号/ID,可跳过授权流程,用户信息授权

使用SDK快速接入

发放支付宝券接口:alipay.marketing.voucher.send

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherSendRequest request = new AlipayMarketingVoucherSendRequest();//创建API对应的request类
request.setBizContent("{" +
"\"template_id\":\"20140601000730010040000000EB\"," +
"\"login_id\":\"13196215350\"," +
"\"taobao_nick\":\"yue54333\"," +
"\"user_id\":\"2088302001456115\"," +
"\"out_biz_no\":\"2016122814164328aadaee_1aee_4\"," +
"\"amount\":9.99," +
"\"memo\":\"优酷3个月兑换券\"" +
"}");//设置业务参数
AlipayMarketingVoucherSendResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
template_id 券模板ID
login_id 支付宝登录ID,手机或邮箱。user_id, login_id, taobao_nick不能同时为空,优先级依次降低
taobao_nick 淘宝昵称。user_id, login_id, taobao_nick不能同时为空,优先级依次降低
user_id 支付宝用户ID。user_id, login_id, taobao_nick不能同时为空,优先级依次降低
out_biz_no 外部业务订单号,用于幂等控制
amount 券金额。浮点数,格式为#.00,单位是元。红包发放时填写,其它情形不能填
memo 发券备注

关键出参:

参数名称 参数说明
voucher_id 券ID
user_id 支付宝用户ID

场景:修改现金抵价券模板

场景描述:

当创建的现金券模板草稿信息有误,或需要提前进行已激活的券模板过期,可进行券模板信息修改。

接口调用流程:

image.png

使用SDK快速接入

修改支付宝券接口:alipay.marketing.cashvoucher.template.modify

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCashvoucherTemplateModifyRequest request = new AlipayMarketingCashvoucherTemplateModifyRequest();//创建API对应的request类
request.setBizContent("{" +
"\"template_id\":\"20140601000730010040000000EB\"," +
"\"slogan\":\"四川移动\"," +
"\"publish_start_time\":\"2017-01-01 00:00:01\"," +
"\"publish_end_time\":\"2017-01-29 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\":\\\"ABSOLUTE\\\",\\\"start\\\":\\\"2017-01-1000:00:00\\\",\\\"end\\\":\\\"2017-01-1323:59:59\\\"}\"," +
"\"out_biz_no\":\"2017000xxx_modify\"" +
"}");//设置业务参数
AlipayMarketingCashvoucherTemplateModifyResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
template_id 模板ID
user_id 支付宝用户ID
template_id 券模板ID
publish_start_time 发放开始时间,早于该时间不能发券。发放开始时间不能晚于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss。仅草稿状态可修改。仅草稿状态可修改
publish_end_time 发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss。草稿状态和生效状态可修改
voucher_valid_period 券有效期。有两种类型:绝对时间和相对时间。使用JSON字符串表示。绝对时间有3个key:type、start、end,type取值固定为"ABSOLUTE",start和end分别表示券生效时间和失效时间,格式为yyyy-MM-dd HH:mm:ss。绝对时间示例:{“type”: “ABSOLUTE”, “start”: “2017-01-10 00:00:00”, “end”: “2017-01-13 23:59:59”}。相对时间有3个key:type、duration、unit,type取值固定为"RELATIVE",duration表示从发券时间开始到往后推duration个单位时间为止作为券的使用有效期,unit表示有效时间单位,有效时间单位可枚举:MINUTE, HOUR, DAY。示例:{“type”: “RELATIVE”, “duration”: 1 , “unit”: “DAY” },如果此刻发券,那么该券从现在开始生效1(duration)天(unit)后失效。
out_biz_no 外部业务单号,用作幂等控制,相同template_id下相同out_biz_no视为同义次修改

关键出参:

参数名称 参数说明
status 模板修改后的状态,I表示草稿状态所有入参都修改了,S表示生效状态仅修改了publish_end_time

场景:查询券模板详情

场景描述:

查询模板的详细信息,包含准实时的汇总信息。

接口调用流程:

image.png

使用SDK快速接入

查询支付宝券模板接口:alipay.marketing.voucher.templatedetail.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherTemplatedetailQueryRequest request = new AlipayMarketingVoucherTemplatedetailQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"template_id\":\"20140601000730010040000000EB\"" +
"}");//设置业务参数
AlipayMarketingVoucherTemplatedetailQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
template_id 模板ID

关键出参:

参数名称 参数说明
template_id 券模板ID
voucher_type 券类型。可枚举,暂时只支持"代金券"(FIX_VOUCHER)
voucher_name 券名称
publish_start_time 发放开始时间,格式为:yyyy-MM-dd HH:mm:ss
publish_end_time 发放结束时间,格式为:yyyy-MM-dd HH:mm:ss
status 模板状态,可枚举。分别为‘草稿’(I)、‘生效’(S)、‘删除’(D)和‘过期’(E)
voucher_valid_period 券有效期。有两种类型:绝对时间和相对时间。使用JSON字符串表示。绝对时间有3个key:type、start、end,type取值固定为"ABSOLUTE",start和end分别表示券生效时间和失效时间,格式为yyyy-MM-dd HH:mm:ss。绝对时间示例:{“type”: “ABSOLUTE”, “start”: “2017-01-10 00:00:00”, “end”: “2017-01-13 23:59:59”}。相对时间有3个key:type、duration、unit,type取值固定为"RELATIVE",duration表示从发券时间开始到往后推duration个单位时间为止作为券的使用有效期,unit表示有效时间单位,有效时间单位可枚举:MINUTE, HOUR, DAY。示例:{“type”: “RELATIVE”, “duration”: 1 , “unit”: “DAY” },如果此刻发券,那么该券从现在开始生效1(duration)天(unit)后失效。
floor_amount 最低额度。券的最低使用门槛金额,只有订单金额大于等于最低额度时券才能使用。币种为人民币,单位为元。该数值不小于0,小数点以后最多保留两位。
voucher_description 券使用说明
amount 面额。每张代金券可以抵扣的金额。币种为人民币,单位为元。该数值不小于0,小数点以后最多两位。
voucher_quantity 拟发行券的数量。单位为张。该数值是大于0的整数。
total_amount 总金额面额。币种为人民币,单位为元。该数值不小于0,小数点以后最多两位。仅代金券
publish_count 已发放张数。单位为张。该数值是大于0的整数。
publish_amount 已发放总金额。币种为人民币,单位为元。该数值不小于0,小数点以后最多两位。
used_count 已使用张数。单位为张。该数值是大于0的整数。
used_amount 已使用总金额。币种为人民币,单位为元。该数值不小于0,小数点以后最多两位。
recycle_amount 退回金额。币种为人民币,单位为元。该数值不小于0,小数点以后最多两位。

场景:查询券模板列表

场景描述:

分页查询当前PID下的所有模板。

接口调用流程:

image.png

使用SDK快速接入

分页查询支付宝券模板接口:alipay.marketing.voucher.templatelist.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherTemplatelistQueryRequest request = new AlipayMarketingVoucherTemplatelistQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"create_start_time\":\"2017-01-0100:00:01\"," +
"\"create_end_time\":\"2017-01-2923:59:59\"," +
"\"page_num\":1," +
"\"page_size\":20" +
"}");//设置业务参数
AlipayMarketingVoucherTemplatelistQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
create_start_time 模板创建开始时间,格式为:yyyy-MM-dd HH:mm:ss
create_end_time 模板创建结束时间,格式为:yyyy-MM-dd HH:mm:ss
page_num 页码,必须为大于0的整数,1表示第一页,2表示第2页,依次类推。
page_size 每页记录条数,必须为大于0的整数,最大值为30

关键出参:

参数名称 参数说明
total_pages 总页数
current_page 当前页码,页码从1开始
items_per_page 每页条数
total_items 总条数
voucher_templates 券模板列表
└ template_id 券模板ID
└ voucher_name 券名称
└ publish_start_time 券模板发放开始时间。格式为:yyyy-MM-dd HH:mm:ss
└ publish_end_time 发放结束时间。格式为:yyyy-MM-dd HH:mm:ss
└ status 模板状态,可枚举。分别为‘草稿’(I)、‘生效’(S)和‘过期’(E)
└ create_time 模板创建时间。格式为:yyyy-MM-dd HH:mm:ss
└ activate_time 模板激活时间。草稿状态的模板该项为空,格式为:yyyy-MM-dd HH:mm:ss

场景:商户外部门店查询接口

场景描述:

在创建券使用规则时,查询当前商户所有外部门店数据。

接口调用流程:

image.png

使用SDK快速接入

分页查询商户外部门店接口:ant.merchant.expand.merchant.storelist.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AntMerchantExpandMerchantStorelistQueryRequest request = new AntMerchantExpandMerchantStorelistQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"pid\":\"2088202967380463\"," +
"\"is_include_cognate\":\"false\"," +
"\"page_num\":1," +
"\"page_size\":20" +
"}");//设置业务参数
AntMerchantExpandMerchantStorelistQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称
参数说明
pid
指定的商户pid,如果指定,只返回此pid的店铺信息。(此pid必须是商户自己的)
is_include_cognate
可选: true / false。
当is_include_cognate = true,指定pid为空,查询商户下所有pid的店铺
当is_include_cognate = true,指定pid不为空时,查询指定pid的店铺
当is_include_cognate = false,指定pid为空时,查询当前商户pid的店铺
当is_include_cognate = false,指定pid不为空时,查询指定pid的店铺
page_num
页码,必须为大于0的整数,1表示第一页,2表示第2页,依次类推。
page_size
每页记录条数,必须为大于0的整数,最大值为30

关键出参:

参数名称 参数说明
total_pages 总页数
page_num 当前页码,页码从1开始
page_size 每页条数
total_size 总条数
merchant_stores 复杂类型ShopQueryInfo,商户门店列表
└ pid 商户pid
└shop_id 内部门店ID
└ store_id 外部门店ID
└ name 门店名称
└address 门店地址
└ shop_type 门店类型
└ longitude 经度
└ latitude 纬度
└ is_include_cognate 是否包含同mid下的其他pid的店铺

场景:删除现金抵价券模板

场景描述:

可以删除处于草稿状态的券模板。

接口调用流程:

image.png

使用SDK快速接入

删除支付宝券模板接口:alipay.marketing.voucher.template.delete

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherTemplateDeleteRequest request = new AlipayMarketingVoucherTemplateDeleteRequest();//创建API对应的request类
request.setBizContent("{" +
"\"template_id\":\"20140601000730010040000000EB\"" +
"}");//设置业务参数
AlipayMarketingVoucherTemplateDeleteResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
template_id 模板ID

场景:查询现金券列表

场景描述:

查询当前PID创建的某个模板给某用户发送的所有的券。

接口调用流程:

image.png

使用SDK快速接入

查询券列表接口:alipay.marketing.voucher.list.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherListQueryRequest request = new AlipayMarketingVoucherListQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"template_id\":\"20140601000730010040000000EB\"," +
"\"user_id\":\"2088512417841101\"" +
"}");//设置业务参数
AlipayMarketingVoucherListQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
template_id 模板ID
user_id 支付宝用户ID

关键出参:

参数名称 参数说明
vouchers 券列表
└ template_id 模板ID
└ voucher_id 券ID
└ status 券状态,可枚举,分别为“可用”(ENABLED)和“不可用”(DISABLED)
└ send_time 发券时间,格式为:yyyy-MM-dd HH:mm:ss

场景:券查询

场景描述:

发放给用户的券实例查询。

接口调用流程:

image.png

使用SDK快速接入

券查询接口:alipay.marketing.voucher.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingVoucherQueryRequest request = new AlipayMarketingVoucherQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"voucher_id\":\"20170616000730020041006ZYE2V\"" +
"}");//设置业务参数
AlipayMarketingVoucherQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
voucher_id 券ID(券唯一标识,发券接口返回参数)

关键出参:

参数名称 参数说明
voucher_id 券ID(同入参券ID)
name 券名称(用户看到券名称)
user_id 券所属用户ID
template_id 券模板ID(模板唯一标识,创建模板返回)
gmt_active 券激活时间(券可以使用起始时间)
gmt_expired 券过期时间(券可以使用截止时间)
total_amount 券面额(元)
available_amount 券余额(元)
status 券状态(ENABLED:可用,DISABLED:不可用,DELETE:删除状态,TRANS:发放中,TRANSFER:已转赠,UNC:未领取,USED:已使用,USING:使用中,REFUNDED:已退款,REFUNDING:退款中,UNACTIVE:未激活,EXPIRED:已过期)
gmt_create 券创建时间(券发券时间)
extend_info 扩展信息,JSON格式
bill_details 复杂类型VoucherBillDetail,券交易账单信息(核销交易信息、交易退款信息等可能存在多条)
└trade_no 券ID(券唯一标识,发券接口返回参数)
└amount 券核销/退款金额
└status 交易状态(I:处理中, S:成功)
└partner_id 交易合作伙伴ID
└partner_name 商户名称
└biz_type 账单类型(V_USE:支付,V_REFUND:退款)
└gmt_create 交易时间

场景:商户使用场景规则PID查询

场景描述:

查询商户可用于使用场景规则的PID。

接口调用流程:

image.png

使用SDK快速接入

商户使用场景规则PID查询:alipay.marketing.userule.pid.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingUserulePidQueryRequest request = new AlipayMarketingUserulePidQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"\"pid\":\"2088202967380463\"" +
"}");//设置业务参数
AlipayMarketingUserulePidQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API,获得对应的response类
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
pid 合作伙伴ID,传入ID比如与当前APPID所属合作伙伴ID一致,否则会报权限不足

关键出参:

参数名称 参数说明
pids 满足条件的所有pid,多个pid使用英文逗号隔开

场景:现金抵价券核销异步通知

场景描述:

在商户现金抵价券被核销时,将对券创建的开发者设置的服务地址进行异步调用通知。

异步调用流程:

image.png

回调参数:

参数名称 参数说明
alipay_biz_no 核销交易的支付宝业务号
biz_time 业务发生时间
flux_amount 变动金额
voucher_id 被核销的券id
partner_id 核销对应商户id
partner_name 核销对应商户名称
onlineServer