基础功能
整体交互时序图
流程简介
用户端流程
svPage : 全屏样式单张优惠券（H5页面）。
第一步：设计券模板
设计券模板样式
1.
**说明：**卡券背景图 strip 、logo 等图片内容可在平台设计时上传验证是否合规，后续创建模板时需传入图片 URL 地址。
2.
3.
修改券模板参数
修改渠道属性（platform）节点
1.
1.
修改文件属性（fileInfo）节点
增加商家属性（merchant）节点
1.
2.
修改基础属性（evoucherInfo）节点
1.
2.
3.
"startDate":"$validStartDate$" ，则跳转至领券详情页及发券接口动态参数赋值需以占位符为 key 即 "validStartDate"："2020-08-24 00:00:00"。完成以上修改后的 pass.json 数据
{
"evoucherInfo":{
"title":"上优酷，看世界杯优酷VIP会员3天",
"type":"marketVoucher",
"product":"free",
"startDate":"$validStartDate$",
"endDate":"$validEndDate$",
"operation":[
{
"format":"url",
"message":"$url$",
"altText":"立即激活"
}
],
"einfo":{
"logoText":"3天",
"secondLogoText":"64场高清直播，进球就下红包雨",
"auxiliaryFields":[
],
"customFields":[
{
"label":"详细说明",
"value":"",
"type":"url",
"more":{
"url":"http://xxxxxxxxxxxx"
}
}
],
"useLimitDesc":"优酷VIP会员",
"brandName":"上优酷，看世界杯",
"originPrice":"",
"banner":{
"bannerImg":"",
"url":""
},
"passImg":"https://tfsimg.alipay.com/images/alipassprod/TB17fLOXB8rDuNk6Xejwu2EYXXa",
"passImgRatio":"2.79"
}
},
"platform":{
"channelID":"2018041602567779"
},
"style":{
"backgroundColor":"RGB(233,16,78)"
},
"fileInfo":{
"formatVersion":"4",
"canShare":true,
"canBuy":false,
"canPresent":false,
"serialNumber":"$serialNumber$"
},
"source":"alipassprod",
"merchant":{
"mname":"优酷视频",
"mcallbackUrl":"https://test.callback.com/alipay/callback.htm"
}
}第二步：创建券模板
示例代码
package com.java.sdk.demo;
import com.alipay.v3.ApiClient;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiResponse;
import com.alipay.v3.Configuration;
import com.alipay.v3.util.GenericExecuteApi;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.util.model.CustomizedParams;
import com.alipay.v3.util.model.OpenApiGenericRequest;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class GenericExecute {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数（全局设置一次）
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
GenericExecuteApi api = new GenericExecuteApi();
OpenApiGenericRequest request = new OpenApiGenericRequest();
// body参数
Map<String, Object> bizParams = new HashMap<>();
bizParams.put("unique_id", "20140709150010");
bizParams.put("tpl_content", "{\"logo\": \"\",\"strip\": null,\"icon\": null,\"content\": {}}");
request.setBodyParams(bizParams);
try {
ApiResponse<Object> response = api.execute("/v3/alipay/pass/template/add", "POST", request);
System.out.println(response.getData());
} catch (ApiException e) {
System.out.println("调用失败，code：" + e.getCode() + "，body：" + e.getResponseBody());
}
}
}入参说明
响应示例
{
"code":"unknow-error",
"message":"系统繁忙"
}响应参数说明
"startDate":"$validStartDate$" ，则跳转至领券详情页及发券接口动态参数赋值需以占位符为 key 即 "validStartDate"："2020-08-24 00:00:00"。第三步：用户跳转至领券预览页
通过 Scheme URL 方式跳转
String tpl_id = "your_tpl_id";
// 动态参数赋值并Encode
String params = "{\"validStartDate\":\"2020-08-20 00:00:00\",\"validEndDate\":\"2020-09-10 00:00:00\"}";
// key值可查看 创建模板 > 响应参数说明 获取
String encodeParams = URLEncoder.encode(params,"utf-8");
// 拼接原始链接并Encode
String mid = "/www/voucher.html?__webview_options__=abv%3dNO%26ttb%3dauto&bizType=svPage&templateId="+tpl_id+"&templateParams="+encodeParams;
String encodeMid = URLEncoder.encode(mid,"utf-8");
// 生成完整链接
String url = "alipays://platformapi/startapp?appId=68687143&url="+encodeMid;
// alipays://platformapi/startapp?appId=68687143 为固定值，请勿修改
System.out.println(url);alipays://platformapi/startapp?appId=68687143&url=%2Fwww%2Fvoucher.html%3F__webview_options__%3Dabv%253dNO%2526ttb%253dauto%26bizType%3DsvPage%26templateId%3DtemplateId%26templateParams%3D%257B%2522startDate%2522%253A%25222020-08-10%2B00%253A00%253A00%2522%252C%2522endDate%2522%253A%25222020-09-10%2B00%253A00%253A00%2522%257D参数说明
{"startDate":"$validStartDate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validStartDate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。// extInfo对应的值 a=b&c=d，则经过2次编码后为：
extInfo=a%253db%2526c%253dd通过 H5 API 方式跳转
示例代码
<script src="https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.inc.min.js"></script>
<button id="J_btn" class="btn btn-default">发放优惠券</button>
<script>
var btn = document.querySelector('#J_btn');
btn.addEventListener('click', function(){
//此处 templateId 只是示例,并非真实的数据
ap.call('addCoupon', {
templateId: '2019110615261633866806432',
bizType:'svPage',
templateParams:''
}, function (res) {
console.log('res === ' + JSON.stringify(res));
});
});
</script>参数说明
svPage：全屏样式单张优惠券（H5页面）。
{"startDate":"$validStartDate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validStartDate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。通过小程序 JSAPI 方式跳转
示例代码
my.call('addCoupon',{
templateId: '2019110615261633866806432',
bizType:'svPage',
templateParams:'{模板json字符串}'
}, function(result) {
console.log('小程序 call addCoupon'+JSON.stringify(result));
});参数说明
svPage：全屏样式单张优惠券（H5页面）。
{"startDate":"$validStartDate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validStartDate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。错误码
| error | 说明 |
|---|---|
| 17000 | 通用错误码，发券失败 |
| 17001 | 重复调用错误，同时只能允许运行一个发券任务 |
| 17002 | 参数错误，必填项为空等 |
| 17003 | 用户主动取消领券操作 |
第四步：发券组件回调 callback
回调 callback url 的样例
https://test.callback.com/alipay/callback.htm?templateId=2019041914323202306418702&token=b18ca3975872e092e5ded56a6e0884b9×tamp=1559133415273返回发券结果
{"success":"true","passId":"your_passId","resultDesc":"发券成功"}参数说明
第五步：调用接口发券
示例代码
package com.java.sdk.demo;
import com.alipay.v3.ApiClient;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiResponse;
import com.alipay.v3.Configuration;
import com.alipay.v3.util.GenericExecuteApi;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.util.model.CustomizedParams;
import com.alipay.v3.util.model.OpenApiGenericRequest;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class GenericExecute {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数（全局设置一次）
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
GenericExecuteApi api = new GenericExecuteApi();
OpenApiGenericRequest request = new OpenApiGenericRequest();
// body参数
Map<String, Object> bizParams = new HashMap<>();
bizParams.put("recognition_info", "{\"recognition_info\":{\"user_id\":\"2088402021319452\"}}");
bizParams.put("tpl_id", "f038871a4b1151e8038bb9277c3d52e3");
bizParams.put("tpl_params", "{\"title\":\"券标题\",\"channelID\":\"xxx\",\"serialNumber\":\"xxxx\"}");
bizParams.put("recognition_type", "2");
request.setBodyParams(bizParams);
try {
ApiResponse<Object> response = api.execute("/v3/alipay/pass/instance/add", "POST", request);
System.out.println(response.getData());
} catch (ApiException e) {
System.out.println("调用失败，code：" + e.getCode() + "，body：" + e.getResponseBody());
}
}
}入参说明
serialNumber 必须为动态参数入值，其它参数根据商家业务决定进行传值。响应示例
{
"code":"unknow-error",
"message":"系统繁忙"
}发券结果说明
更新卡券实例
核销卡券功能
HTTP 请求源码示例
https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D×tamp=2015-06-24+21%3A09%3A20&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.instance.update&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&
biz_content={
"user_id": "xxxx",
"status": "USED"
"channel_id": "102014022600003526",
"serial_number": "4333673662446155"
}客户端示例图
失效卡券功能
HTTP 请求源码示例
https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D×tamp=2015-06-24+21%3A09%3A20&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.instance.update&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&
biz_content={
"user_id": "xxxx",
"status": "CLOSED",
"channel_id": "102014022600003526",
"serial_number": "4333673662446155"
}更新卡券内容功能
HTTP 请求源码示例
https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D×tamp=2015-06-24+21%3A09%3A20&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.instance.update&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&
biz_content={
"user_id": "xxxx",
"channel_id": "102014022600003526",
"serial_number": "4333673662446155",
"tpl_params":{"discountInfo": "凭此券即可打5折","logoText": "四季风情5折优惠券"}
}客户端示例图
