创建模板接口

接口调用说明

接口名称：alipay.pass.template.add

接口描述：支付宝卡券新建模版接口

使用场景介绍：商户通过此接口添加用于同步到手机支付宝卡券的模版

第一步：选择券类型

可选券类型

支付宝卡券支持优惠券、票务和行程单三种模板类型，不同模板类型有不同的展示排版结构。

支付宝卡券支持多种产品类型。开发者可以根据自身的业务场景，选择合适的产品类型。产品类型包括：免费券、兑换券、团购券、彩票、电影票、旅游景点门票、酒店、登机牌、机票、火车票及其汽车票。（具体的字段设置可以参考卡券类型）

券示例及其排版结构

不同模板类型有不同的展示排版结构，结构图如下：

1. 优惠券的排版结构

2. 票务的排版结构

3. boardingPass的排版结构

第二步：在线设计卡券

为简化卡券开发，我们提供了所见即所得的卡券模板设计功能，请根据如下步骤来获得模板内容，并在支付宝卡券系统中创建模板。

1. 进入卡券平台（https://alipassprod.alipay.com），选择券类型，点击“编辑”，根据需要设计模板。

2. 查看模板样式效果

商户在网站上设计完成模板之后，点击保存后会获得一个二维码，例如下图。

打开手机支付宝，扫描获得的二维码，会出来一个领取页面，领取券后可以查看最终的券样式是否满足需求。

3. 点击二维码下载模板文件，解压后如下图（如果无法解压，请将后缀名修改为zip即可解压）。

4. 打开pass.json文件，其值即为创建模板的参数tpl_content中content的值。

第三步：配置券模板内容

业务主体参数（biz_content）

参数	参数名称	类型	必填	描述	范例
unique_id	唯一标识	String(64)	否	商户用于控制模版的唯一性。（可以使用时间戳保证唯一性）	20140709150010
tpl_content	模板内容	String(65000)	是	模板内容信息，遵循JSON规范。 详情参见 tpl_content的构成	{"logo": " https://tfsimg.alipay.com/images/kabaoprod/T1uoldXeVlXXaCwpjX","strip": null,"icon": null,"content": {}}

tpl_content为json对象，由content（即pass.json内容，必传）、icon、logo（图片url地址，必传）、strip（图片的url地址），4个元素共同构成tpl_content的json对象。

提取pass.json文件后，就可以构造tpl_content字符串对象，如下：

为了保证卡券展示的灵活扩展，卡券展示使用JSON格式的字符串来存储，其中一些是固定节点，控制在钱包中的展示位置，一部分是用户自定义的展示文案，文案可以是在模板设计时就设计好的固定文案，也可以是变量，使用$var$来表示，等券实例化时再传入具体的var代表的值来替换，其中var为变量名，可以是任何有意义的名称，最好全部由英文字母组成。Content节点里面的内容为pass.json的内容，pass.json对象大体由下面6大部分组成。

结构视图

属性描述

参数	参数名称	类型	必填	描述	范例
evoucherInfo	基础属性	String	是	pass的基础信息，如pass标题、pass类型等	参见基础属性（evoucherInfo）
style	样式属性	String	否	pass在app展现时的样式信息	参见样式属性（style）
fileInfo	文件属性	String	是	Alipass文件的相关信息	参见文件属性（fileInfo）
merchant	主体内容图片url	String	是	pass对应的第三方信息	参见商户属性（merchant）
platform	渠道属性	String	是	pass发布渠道或者平台信息	参见渠道属性（platform）
appInfo	应用属性	String	否	第三方手机客户端应用信息	参见应用属性（appInfo）

基础属性（evoucherInfo）

结构视图

属性描述

参数	参数名称	类型	必填	描述	范例
goodsId	商品ID	String(64)	否	pass对应商品的id	--
title	pass名称	String(256)	是	pass的名称，如优惠券的名称	**优惠券
type	卡券大类型(展示模板)	String(16)	是	支付宝当前支持pass的类型（不同类型会有不同的详情展示模板）	coupon
product	卡券子类型(产品业务)	String(16)	是	支付宝当前支持pass的子类型，与type字段结合确定pass的准确类型	free
startDate	开始时间	String(16)	是	pass生效时间(起飞时间)，YYYY-MM-dd HH:mm:ss格式字符串	2016-6-30 15:44:11
endDate	结束时间	String(19)	是	pass失效时间（落地时间）（可与startDate相同），需要精确到秒，如：2013年5月1日到期，则到结束时间需要设置成2013-05-01 23：59：59	2013-05-01 23:59:59
einfo	pass特性	EInfo(4000)	是	不同类型pass对应的特定属性	["wave","text"]
operation	操作信息	Operation(1000)	是	支持文本、二维码、声波等核销内容展示，也可作为启动应用操作
remindInfo	提醒信息	RemindInfo	100	用于在pass 生效或截止前提示用户，可设置时间提前量、提醒的内容

卡券类型（type和product）

支付宝卡券支持以下3种 type类型，不同模板类型有不同的展示模板排版结构。

序号	模板类型名称	模板描述
1	coupon	优惠券类默认展示模板
2	eventTicket	事件票务类默认展示模板
3	boardingPass	登车、船、飞机票务等默认展示模板

支付宝卡券支持以下11种产品业务类型。接口调用方可以根据自身的业务场景，选择合适的产品类型。product分类如下

序号	产品业务类型	描述
1	free	免费券
2	price	兑换券
3	groupon	团购券
4	lottery	彩票
5	movie	电影票
6	tourist	旅游景点门票等
7	hotel	酒店
8	boarding	登机牌
9	air	机票
10	train	火车票
11	bus	汽车票

卡券属性设置（einfo）

einfo数据是alipass的主体信息，主要用于展示给用户。如：电影票、登机牌、优惠券等均有自有行业特定的信息。 第三方可根据实际需要按照约定的JSON数据格式将内容进行组装。这些数据最终会按照组装顺序显示在alipass的详情中（正面和背面均支持）。目前主要包含：headFields、primaryFields、secondaryFields、auxiliaryFields、backFields几大块区域。

einfo结构区域描述（einfo） 

序号	Key	字段名	描述	可空
1	logo	PassLogo	从alipass文件包中获取：即logo.png	Y
2	logoText	Logo旁白	logo旁白区域	N
3	secendLogoText	辅助Logo旁白	第二行logo旁白区域（可选）	Y
4	Thumbnail	缩略图	从alipass文件包中获取：即strip.png。	Y
5	headFields	内容	头部右端区域块【EinfoUnit列表】	Y
6	primaryFields	第一区域块	第一区域块需要展示的内容【EinfoUnit列表】	Y
7	secondaryFields	第二区域块	第二区域块需要展示的内容【EinfoUnit列表】	Y
8	auxiliaryFields	辅助区域块	辅助域块需要展示的内容【EinfoUnit列表】	Y
9	backFields	背面区域块	背面区域块需要展示的内容【EinfoUnit列表】	Y

说明：headFields、primaryFields、secondaryFields、auxiliaryFields、backFields区域，至少有一个区域有值。

区块规则（EinfoUnit）

序号	内容	字段名	字段类型	说明	可空
1	key	字段关键字	String	字段关键字	N
2	label	显示名称	String	显示名称	Y
3	value	显示具体值	String	显示具体值	Y
4	type	字段类型	String	可选类型为电话【tel】、网站连接地址【url】、地图【map】、文本【text】(默认)等。根据不同的类型，将在该字段前添加相应的icon，并会根据实际情况相应支持电话拨出、启动浏览器跳转连接地址、启动手机应用客户端、地图等功能；	Y

说明：如果key 的值不为空，则label 和value 必须有一个值非空。

einfo业务必要属性声明

说明：因部分业务需要，除基础属性外在einfo同样有部分特有的关键属性信息（key值固定，显示名称不做限制）不得为空，并且需要保证在einfo中关键业务的key值没有重复，但并不限制排版位置。如下表所示： 

序号	Product业务类型	必要属性名称（名称可自定义）	Key（固定）
1	train(火车票)	出发地	from
		目的地	to
		列车号	trainNo
2	boarding（登机牌）	出发地	from
		目的地	to
		航班号	fltNo
3	air(机票)	出发地	from
		目的地	to
		航班号	fltNo
4	bus(汽车票)	出发地	from
		目的地	to
		车次号	busNo

核销区域设置（Operation）

核销操作区目前支持：wave（声波方式）、qrcode（二维码方式）、barcode（条码方式）、text（文本方式）、应用启动（app）、网页链接（url）、图片（img）

核销方式	模板中核销区（operation）示例	备注
声波方式	"operation": [{ "message": "$ackCode$", "messageEncoding": "UTF-8", "format": "wave", "altText": "$ackCode$" }]	如果是声波类型，message字符长度规则如下 1)16位及以下字符串任意字符传输。(兼容上期版本)eg: !@#$%^&*()|{}12a 2)长度在16位以上字符串，最长长度不超过32位。整个字符串组合为数字或A-F的字母(字母不区分大小写，输出结果统一为大写)，首字符不能为0 eg: 123456789ABCDEF0123456789ABCDEFA 3)不符合规则客户端本地过滤不显示声波核销按钮
二维码方式	"operation": [{ "message": "$ackCode$", "messageEncoding": "UTF-8", "format": "barcode", "altText": "$ackCode$" }]
条码方式	"operation": [{ "message": "$ackCode$", "messageEncoding": "UTF-8", "format": "qrcode", "altText": "$ackCode$" }]
文本方式	"operation": [{ "altText": "兑换码", "message": [{ "label": "序列号",    "value": "$ackCode$" },{ "label": "验证码", "value": "4958" }], "messageEncoding": "utf-8", "format": "text" }]	如果format为文本方式，message需要为json数组
应用方式	"operation": [{ "message": { "android_appid": "androidId", "android_launch": "android启动地址", "android_download": "Android下载地址", "ios_appid": "IOSId", "ios_launch": "ios启动地址", "ios_download": "ios下载地址" }, "format": "app", "messageEncoding": "utf-8", "altText": "按钮文字" }	跳转启动外部应用
图片	"operation": [{ "message": { "img": "*****.png",      "target": "" }, "format": "img", "messageEncoding": "utf-8", "altText": "核销图片" }]
链接	"operation": [{ "format": "url", "message": "https://****", "messageEncoding": "utf-8", "altText": "请使用" }]

提醒信息设置（remindInfo）

结构视图

属性描述

序号	Key	字段名	字段类型	描述	可空
1	offset	提前时间	String	提醒默认的提前秒数，（3600-24×3600秒之间）	Y

提醒文案示例：

1）机票

“您从#from#到#to#的航班将于今（明天）天#startDate#起飞，请提前做好安排。“

2）酒店

“您将于#startDate#入住#title#店，请提前做好安排。“

3）门票

“您预订了#startDate#的#title#门票，请提前做好安排。“

说明：提醒文案中的的变量会从pass的基础属性和einfo中捞取，并会根据实际展示需要进行格式化。

商户属性（merchant）

商户属性是指归属于第三方的最终商户，比如天猫商城是一个第三方，其中深航机票是一个最终商户。

结构视图

属性描述

序号	Key	字段名	字段类型	描述	可空
1	mname	商户全称	String	商户完整名称	N
2	mshortName	商户简称	String	商户的简称	Y
3	maddr	商户地址	String	商户的通讯地址	Y
4	mtel	商户电话	String	商户的服务电话	Y
5	minfo	商户简介	String	商户的介绍	Y

渠道属性（platform）

结构视图

属性描述

序号	Key	字段名	字段类型	长度	描述	可空
1	channelID	渠道商ID	String	32	第三方在支付宝的partnerId 若已入驻蚂蚁金服开放平台则使用对应的appId	N
2	channelScene	渠道场景	String	32	可以设置为public,server，如果设置pubic则当发券时不给用户发PUSH消息，设置server会发PUSH	Y
3	webServiceUrl	渠道商服务地址	String	128	第三方服务url，用于将支付宝相关的信息同步给第三方	N

样式属性（style）

结构视图

属性描述

序号	Key	字段名	描述	可空
1	backgroundColor	背景颜色	整体卡券背景颜色	N

文件属性（fileInfo）

结构视图

属性描述

序号	Key	字段名	字段类型	字段长度	描述	可空
1	formatVersion	Pass文件版本	Integer	10	Alipass的版本，现为2	N
2	canPresent	是否支持转赠	Boolean	10	当设置为可转赠则可以在钱包中点击转赠按钮，将拥有的券转赠给其他用户	Y
3	canShare	是否支持共享	Boolean	10	当前Alipass是否指定到单一用户，如果支持共享则可以有多个用户拥有同一张pass文件	Y
4	serialNumber	Pass文件序列号	String	32	文件序列号，同一第三方提供的序列号需要唯一； 同一用户重复添加的pass，对应的serialNumber要求一致（多份购买行为例外）。	N

应用属性（appInfo）

结构视图

属性描述

序号	Key	字段名	字段类型	描述	可空
1	label	名称	String	在alipass中显示的app应用名称	Y
2	message	应用描述	String	应用的简短描述，可能会展示在alipass的应用信息区。	Y
3	app	应用具体信息	String	应用具体信息,包含： 1：应用ID或包名 2：应用启动地址: 3：应下载地址： (需要区分IOS与android)	Y

公共请求参数说明

HTTPS请求地址：https://openapi.alipay.com/gateway.do 

参数	参数名称	类型	必填	描述	范例
app_id	应用ID	String(32)	是	支付宝分配给开发者的应用ID	2014072300007148
method	接口名称	String(128)	是	接口名称	alipay.pass.template.update
format	数据格式	String(40)	否	仅支持JSON	json
charset	编码格式	String(10)	是	请求使用的编码格式，如UTF-8,GBK,GB2312等	UTF-8
sign_type	签名方式	String(10)	是	商户生成签名字符串所使用的签名算法类型，目前支持RSA	RSA
sign	签名值	String(256)	是	商户请求参数的签名串，详见签名与验签	详见示例
timestamp	请求时间	String(19)	是	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	版本	String(3)	是	调用的接口版本，固定为：1.0	1.0
app_auth_token	授权令牌	String(40)	否	详见应用授权（此链接后继需修改）

 

接口使用示例

1. 进入卡券平台（https://alipassprod.alipay.com），完成在线模板设计。示例如下图。

2. 获取json.pass作为tpl_content中content属性，为了更好的保持模板的灵活通用性，示例将有效时间、描述文案，标题设为变量（validStartDate,validEndDate, discountInfo, logoText,useStateDesc）。调用创建模板接口完成模板创建。

HTTP请求源码示例

https://openapi.alipay.com/gateway.do?sign=uVzuTRpcIvgmDCRfyR9eusJmgNoeRs3OWI2eyrIWqwE7F01ttFRdpzmiqWBfuxI%2FePuFrC1R8bL5V4h82sH5CQ%2F3CuIo6HQO2YC63f7pKdBx5gC%2FxMdTevdC4QCJF5k0xWu5JlssKy%2FKliNUqgFFiQfTLHPPhr%2B8usaZ1UwqSZE%3D&timestamp=2015-06-24+14%3A13%3A49&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.template.add&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&biz_content=
{
  "unique_id": "1435126393468",
  "tpl_content": {
    "logo": "https://alipass.alipay.com//temps/free/logo.png",
    "strip": "https://alipass.alipay.com//temps/free/strip.png",
    "icon": "http://alipassprod.test.alipay.net/temps/free/icon.png",
    "content": {
      "evoucherInfo": {
        "title": "风情优惠券",
        "type": "coupon",
        "product": "free",
        "startDate": "$validStartDate$",
        "endDate": "$validEndDate$",
        "operation": [
          {
            "format": "qrcode",
            "message": "45612346579465",
            "messageEncoding": "UTF-8",
            "altText": "45612346579465"
          },
          {
            "format": "barcode",
            "message": "45612346579465",
            "messageEncoding": "UTF-8",
            "altText": "45612346579465"
          }
        ],
        "einfo": {
          "logoText": "$logoText$",
          "headFields": [
            {
              "key": "status",
              "label": "状态",
              "value": "$useStateDesc$",
              "type": "text"
            }
          ],
          "primaryFields": [
            {
              "key": "strip",
              "label": "",
              "value": "$discountInfo$",
              "type": "text"
            }
          ],
          "secondaryFields": [
            {
              "key": "validDate",
              "label": "有效期至：",
              "value": "$validEndDate$",
              "type": "text"
            }
          ],
          "auxiliaryFields": [
            
          ],
          "backFields": [
            {
              "key": "description",
              "label": "详情描述",
              "value": "1.该优惠有效期：截止至2014年06月18日；\n2.凭此券可以享受以下优惠：\n享门市价优惠\n不与其他优惠同享。详询商家。",
              "type": "text"
            },
            {
              "key": "shops",
              "label": "可用门店",
              "value": "",
              "type": "text"
            },
            {
              "key": "disclaimer",
              "label": "负责声明",
              "value": "除特殊注明外，本优惠不能与其他优惠同时享受； 本优惠最终解释权归商家所有，如有疑问请与商家联系。 提示：为了使您得到更好的服务，请在进店时出示本券。",
              "type": "text"
            }
          ]
        },
        "remindInfo": {
          "offset": "2"
        }
      },
      "merchant": {
        "mname": "hodewu",
        "mtel": "",
        "minfo": ""
      },
      "platform": {
        "channelID": "$channelID$",
        "webServiceUrl": "http://alipassprod.test.alipay.net/builder/syncRecord.htm?tempId=2016062716334639647179025"
      },
      "style": {
        "backgroundColor": "RGB(255,126,0)"
      },
      "fileInfo": {
        "formatVersion": "2",
        "canShare": true,
        "canBuy": false,
        "canPresent": true,
        "serialNumber": "$serialNumber$",
        "supportTaxi": "true",
        "taxiSchemaUrl": "alipays://platformapi/startapp?appId=20000130&sourceId=20000030&showTitleBar=YES&showToolBar=NO&showLoading=NO&safePayEnabled=YES&readTitle=YES&backBehavior=back&url=/www/index.html"
      },
      "appInfo": {
        "app": {
          "android_appid": "com.taobao.ecoupon",
          "ios_appid": "taobaolife://",
          "android_launch": "com.taobao.ecoupon",
          "ios_launch": "taobaolife://",
          "android_download": "http://download.taobaocdn.com/freedom/17988/andriod/Ecoupon_2.0.1_taobao_wap.apk",
          "ios_download": "https://itunes.apple.com/cn/app/id583295537"
        },
        "label": "淘宝券券APP",
        "message": "点击调起APP"
      },
      "source": "alipassprod",
      "alipayVerify": [        
      ]
    }
  }
}

 

响应结果说明

响应结果示例

{
  "alipay_pass_template_add_response": {
    "code": "10000",
    "msg": "Success",
    "result": "{ \"serialNumber\":\"1550547540752564\",\"operate\":\"UPDATE\"}",
    "success": true
  },
  "sign": "hAxz/ahsRObKHxo6d41OcfPyDVMJKaHC77Lp9+uE2ENV9w4tpBQKYim1D1ACPYq1ziN5532oEeBAbV6Wo6YNCRwFiMAKRGO8Fm5UOAHxfr4E35mb1gcihR31N25YLCD/k5fDPY1daezb57fPcq4zDiVAy49jd5gNcC9v85yEtck="

返回参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
success	String	否	必须	true	操作成功标识【true：成功；false：失败】
result	String	否	必须	{“tpl_id”:“f038871a4b1151e8038bb9277c3d52e3”,“tpl_params”:“[title,startDate,channelID,serialNumer]”}	参见下面的模板创建返回结果参数说明

模板创建返回结果参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
tpl_id	String	否	必须	f038871a4b1151e8038bb9277c3d52e3	新创建的模板编号
tpl_params	String	否	必须	[title,startDate]	用户定义的变量的key

错误码说明

名称	描述	解决方案
KP.AE_ALIPASS_TEMPLATE_CONTENT_IS_BLANK	tpl_content为空	tpl_content不能为空
KP.AE_ALIPASS_TEMPLATE_UNIQUE_IS_BLANK	unique_id为空	unique_id不能为空
KP.AE_ALIPASS_TEMPLATE_CONTENT_FORMAT_ERR	模板内容格式错误	检查tpl_content是否json格式
KP.AE_ALIPASS_ESSENTIAL_PARAMS_BLANK	模板内容必填参数缺少	根据错误提示，检查必填参数
KP.AE_ALIPASS_TEMPLATE_UNRECOGNIZE_PROPERTY	模板内容中存在不识别的参数key值	根据错误提示修正
KP.AE_ALIPASS_DATE_ERROR	日期不合法，必须为yyyy-MM-dd HH:mm:ss格式	日期不合法，请检查startDate和endDate
KP.AE_SYSTEM_ERROR	系统错误	重试或联系技术支持
KP.AE_ALIPASS_DATA_CONTAIN_FORBIDDEN_WORD	存在敏感词	修改文本中的敏感词
KP.AE_ALIPASS_TEMPLATE_PARAMS_VALUE_INVAILD	模板存在参数值不合法	模板存在参数值不合法，根据错误提示修改
KP.AE_ALIPASS_TEMPLATE_EXISTED	模板已经存在	幂等控制，确保unique_id的唯一性

更新模板接口

接口调用说明

接口名称：alipay.pass.template.update

接口描述：支付宝卡券更新模版接口

使用场景介绍：商户通过此接口更新已经存在的alipass模版。支付宝卡券通过卡券模板进行发放，因此模板的更新会导致，基于此模板发放的卡券的内容变更。

业务请求参数说明

业务主体参数（biz_content）

参数	参数名称	类型	必填	描述	范例
tpl_id	模版ID	String(32)	是	更新的模板ID	f038871a4b1151e8038bb9277c3d52e3
tpl_content	模板内容	String(65000)	是	模板内容信息，遵循JSON规范，详情参见新建模版中的“tpl_content参数说明”	{"logo": "","strip": null,"icon": null,"content": {}}
logo	logo图片	String(1500)	是	模板logo图片	https://tfs.alipay.net/images/alipassprod/T19XBXXhFXXXaCwpjX

公共请求参数说明

HTTPS请求地址：https://openapi.alipay.com/gateway.do 

参数	参数名称	类型	必填	描述	范例
app_id	应用ID	String(32)	是	支付宝分配给开发者的应用ID	2014072300007148
method	接口名称	String(128)	是	接口名称	alipay.pass.template.update
format	数据格式	String(40)	否	仅支持JSON	json
charset	编码格式	String(10)	是	请求使用的编码格式，如UTF-8,GBK,GB2312等	UTF-8
sign_type	签名方式	String(10)	是	商户生成签名字符串所使用的签名算法类型，目前支持RSA	RSA
sign	签名值	String(256)	是	商户请求参数的签名串，详见签名与验签	详见示例
timestamp	请求时间	String(19)	是	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	版本	String(3)	是	调用的接口版本，固定为：1.0	1.0
app_auth_token	授权令牌	String(40)	否	详见应用授权（此链接后继需修改）

接口使用示例

在创建模板接口示例，完成模板创建的基础上，调用模板修改接口，对模板内容进行修改。

HTTP请求源码示例

https://openapi.alipay.com/gateway.do?sign=ERe8uRix%2BJcJ3%2B4MadVIxPCpJU7Z7%2FxZhd8TKmfAfOQR1oGuXBkvf3ty29VcA7KEGNi1b6Che3iw3zfWjM9Xp8Rdqsui6tkcmPqKaOW8Y%2BbfM7qtB2LfjNaKhNjC%2B1mz2O7ucv4GMpKxm%2BDdzLBKGZW%2BinyBkY4e%2BNrA3%2FOAjcA%3D&timestamp=2015-06-24+16%3A54%3A13&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.template.update&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&biz_content={
  "tpl_id": " 2016062811032240457655570",
  "tpl_content": {
    "logo": "https://alipass.alipay.com//temps/free/logo.png",
    "strip": "https://alipass.alipay.com//temps/free/strip.png",
    "icon": "http://alipassprod.test.alipay.net/temps/free/icon.png",
    "content": {
      "evoucherInfo": {
        "title": "风情优惠券",
        "type": "coupon",
        "product": "free",
        "startDate": "$validStartDate$",
        "endDate": "$validEndDate$",
        "operation": [
          {
            "format": "qrcode",
            "message": "45612346579465",
            "messageEncoding": "UTF-8",
            "altText": "45612346579465"
          },
          {
            "format": "barcode",
            "message": "45612346579465",
            "messageEncoding": "UTF-8",
            "altText": "45612346579465"
          }
        ],
        "einfo": {
          "logoText": "$logoText$",
          "headFields": [
            {
              "key": "status",
              "label": "优惠券状态",
              "value": "$useStateDesc$",
              "type": "text"
            }
          ],
          "primaryFields": [
            {
              "key": "strip",
              "label": "",
              "value": "$discountInfo$",
              "type": "text"
            }
          ],
          "secondaryFields": [
            {
              "key": "validDate",
              "label": "优惠券有效期至：",
              "value": "$validEndDate$",
              "type": "text"
            }
          ],
          "auxiliaryFields": [
            
          ],
          "backFields": [
            {
              "key": "description",
              "label": "详情描述",
              "value": "1.该优惠有效期：截止至2014年06月18日；\n2.凭此券可以享受以下优惠：\n享门市价8.5折优惠\n不与其他优惠同享。详询商家。",
              "type": "text"
            },
            {
              "key": "shops",
              "label": "可用门店",
              "value": "",
              "type": "text"
            },
            {
              "key": "disclaimer",
              "label": "负责声明",
              "value": "除特殊注明外，本优惠不能与其他优惠同时享受； 本优惠最终解释权归商家所有，如有疑问请与商家联系。 提示：为了使您得到更好的服务，请在进店时出示本券。",
              "type": "text"
            }
          ]
        },
        "remindInfo": {
          "offset": "2"
        }
      },
      "merchant": {
        "mname": "hodewu",
        "mtel": "",
        "minfo": ""
      },
      "platform": {
        "channelID": "$channelID$",
        "webServiceUrl": "http://alipassprod.test.alipay.net/builder/syncRecord.htm?tempId=2016062716334639647179025"
      },
      "style": {
        "backgroundColor": "RGB(255,126,0)"
      },
      "fileInfo": {
        "formatVersion": "2",
        "canShare": true,
        "canBuy": false,
        "canPresent": true,
        "serialNumber": "$serialNumber$",
        "supportTaxi": "true",
        "taxiSchemaUrl": "alipays://platformapi/startapp?appId=20000130&sourceId=20000030&showTitleBar=YES&showToolBar=NO&showLoading=NO&safePayEnabled=YES&readTitle=YES&backBehavior=back&url=/www/index.html"
      },
      "appInfo": {
        "app": {
          "android_appid": "com.taobao.ecoupon",
          "ios_appid": "taobaolife://",
          "android_launch": "com.taobao.ecoupon",
          "ios_launch": "taobaolife://",
          "android_download": "http://download.taobaocdn.com/freedom/17988/andriod/Ecoupon_2.0.1_taobao_wap.apk",
          "ios_download": "https://itunes.apple.com/cn/app/id583295537"
        },
        "label": "淘宝券券APP",
        "message": "点击调起APP"
      },
      "source": "alipassprod",
      "alipayVerify": [
        
      ]
    }
  }
}

 

响应结果说明

响应结果示例

{
  "alipay_pass_template_update_response": {
    "code": "10000",
    "msg": "Success",
    "result": "{\"tpl_id\":\"2015062614280547004605924\",\"tpl_params\":[\"filmName\",\"hallName\",\"count\",\"seatsInfo\",\"filmVersion\",\"dayTime\",\"hourTime\",\"secondLogoText\",\"cinemaName\",\"addr\",\"latitude\",\"longitude\",\"relevantText\",\"tel\",\"startDate\",\"endDate\",\"ackCode\",\"serialNumber\",\"channelID\"]}",
    "success": true
    },
  "sign": "hAxz/ahsRObKHxo6d41OcfPyDVMJKaHC77Lp9+uE2ENV9w4tpBQKYim1D1ACPYq1ziN5532oEeBAbV6Wo6YNCRwFiMAKRGO8Fm5UOAHxfr4E35mb1gcihR31N25YLCD/k5fDPY1daezb57fPcq4zDiVAy49jd5gNcC9v85yEtck="

返回参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
success	String	否	必须	true	操作成功标识【true：成功；false：失败】
result	String	否	必须	{"template_id":"989901","tpl_params":"[tile,startDate,channelID,serialNumber]"}	参见下面的“模板更新返回结果参数说明”

模板更新返回结果参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
tpl_id	String	否	必须	989901	更新的模板编号
tpl_params	String	否	必须	[title,startDate,channelID,serialNumer]	商户定义的变量的key

错误码说明

名称	描述	解决方案
KP.AE_ALIPASS_TEMPLATE_CONTENT_IS_BLANK	tpl_content为空	tpl_content不能为空
KP.AE_ALIPASS_TEMPLATE_UNIQUE_IS_BLANK	unique_id为空	unique_id不能为空
KP.AE_ALIPASS_TEMPLATE_CONTENT_FORMAT_ERR	模板内容格式错误	检查tpl_content是否json格式
KP.AE_ALIPASS_ESSENTIAL_PARAMS_BLANK	模板内容中必填参数缺少	根据错误提示，检查必填参数
KP.AE_ALIPASS_TEMPLATE_UNRECOGNIZE_PROPERTY	模板内容中存在不识别的参数key值	根据错误提示修正
KP.AE_ALIPASS_DATE_ERROR	日期不合法，必须为yyyy-MM-dd HH:mm:ss格式	日期不合法，请检查startDate和endDate
KP.AE_ALIPASS_TEMPLATE_NOT_EXIST	模板不存在	检查模板ID是否存在
KP.AE_ALIPASS_DATA_CONTAIN_FORBIDDEN_WORD	存在敏感词	检查模板内容，修改敏感词
KP.AE_SYSTEM_ERROR	保存错误	重试或联系技术支持

业务请求参数说明

业务主体参数（biz_content）

参数	参数名称	类型	必填	描述	范例
tpl_id	模板ID	String(32)	是	支付宝pass模版ID	f038871a4b1151e8038bb9277c3d52e3
tpl_params	参数键值对	String(38000)	是	模版动态参数信息【支付宝pass模版参数键值对JSON字符串】。	{"cardNo":"0000001"} 此处cardNo是业务创建模板时指定的变量
recognition_type	确认身份类型	String(1)	是	Alipass添加对象识别类型：1–订单信息	1
recognition_info	接受者身份信息	String(500)	是	支付宝用户识别信息： 包括partner_id（商户的签约账号）和out_trade_no	{"partner_id":"2088102114633762","out_trade_no":"1234567"}

tpl_params参数说明

动态参数是创建模板时声明的可被替换的数据（调用创建模板接口时返回），如：$cardNo$，如果创建模板时，channelID和serialNumber为动态参数，则创建卡券时要求必填；如果创建模板时，这2个字段为指定参数，则创建卡券时为非必填。此处cardNo是业务创建模板时指定的变量。

公共请求参数说明

HTTPS请求地址：https://openapi.alipay.com/gateway.do 

参数	参数名称	类型	必填	描述	范例
app_id	应用ID	String(32)	是	支付宝分配给开发者的应用ID	2014072300007148
method	接口名称	String(128)	是	接口名称	alipay.pass.template.update
format	数据格式	String(40)	否	仅支持JSON	json
charset	编码格式	String(10)	是	请求使用的编码格式，如UTF-8,GBK,GB2312等	UTF-8
sign_type	签名方式	String(10)	是	商户生成签名字符串所使用的签名算法类型，目前支持RSA	RSA
sign	签名值	String(256)	是	商户请求参数的签名串，详见签名与验签	详见示例
timestamp	请求时间	String(19)	是	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	版本	String(3)	是	调用的接口版本，固定为：1.0	1.0
app_auth_token	授权令牌	String(40)	否	详见第三方应用授权

接口使用实例

HTTP请求源码示例

在创建模板接口示例完成模板创建的基础上，调用发放卡券接口，请求示例。

https://openapi.alipay.com/gateway.do?sign=rzVtT2%2F7LC2rpWIPkz74KhMa%2Fz7YG%2BiCrLtTh5cbMQszUE%2BZe9JYuwO1HWlREgn8CHVdVF7CuHBJI5GV4%2Frp57MzmpNpdOMXX6REm4KgIDBl1ZOEGlPxqUvwbkrTZSFN2Q62%2FcZHoG%2FVC8CD%2B1utl%2BFzx%2B78xecQIcwUGeAF%2BYk%3D&timestamp=2015-06-24+20%3A37%3A44&sign_type=RSA&app_id=102014022600003526&method=alipay.pass.instance.add&version=1.0&alipay_sdk=alipay-sdk-java-dynamicVersionNo&format=json&
biz_content={
  "recognition_type": "1",
  "tpl_id": " 2016062810560547218925408 ",
  "recognition_info": {
    "partner_id": "2088102122069225",
    "out_trade_no": "1393388276383"
  },
  "tpl_params": {
    "validStartDate": "2016-06-30 20:00:00",
    "validEndDate": "2016-07-30 20:00:00",
    "channelID": "102014022600003526",
    "discountInfo": "凭此券即可打8.5折",
    "logoText": "四季风情85折优惠券",
    "serialNumber": "4333673662446155"	
  }
}

支付宝用户收到发放的卡券，详情截图如下：

响应结果说明

响应结果示例

{
  "alipay_pass_instance_add_response": {
    "code": "10000",
    "msg": "Success",
    "result": "{\"passId\":\"5038200176\",\"serialNumber\":\"0336223063413266\",\" operate \":\" ADD \"}",
    "success": true
  },
  "sign": "hAxz/ahsRObKHxo6d41OcfPyDVMJKaHC77Lp9+uE2ENV9w4tpBQKYim1D1ACPYq1ziN5532oEeBAbV6Wo6YNCRwFiMAKRGO8Fm5UOAHxfr4E35mb1gcihR31N25YLCD/k5fDPY1daezb57fPcq4zDiVAy49jd5gNcC9v85yEtck="

返回参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
success	String	否	必须	true	操作成功标识【true：成功；false：失败】
result	String	否	必须	{"serialNumber":"123555123","passId":"209919213","operate":"ADD"}	参见下面的“创建卡券实例信息参数说明”

创建卡券实例信息参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
serialNumber	String	否	必须	123555123	商家指定的卡券唯一标识
passId	String	否	必须	209919213	卡包系统生成的卡券唯一标识
operate	String	否	必须	ADD	操作类型

错误码说明

名称	描述	解决方案
KP.AE_ALIPASS_TEMPLATE_NOT_FOUND	模板不存在	检查tpl_id对应的模板是否存在
KP.AE_ALIPASS_USERID_NOSUPPORT	该用户不支持	该用户在黑名单中，不支持发券
KP.AE_ALIPASS_APPID_NOSUPPORT	该AppId不支持	该appId在黑名单中，不支持发券
KP.AE_ALIPASS_RECOGNITION_TYPE_NOSUPPORT	recognitionType不支持userID方式发券	不支持userID方式发券
KP.AE_ALIPASS_RECOGNITION_TYPE_INVALID	recognitionType不合法	recognitionType类型不合法
KP.AE_ALIPASS_PARAME_IS_NULL	必填参数缺少	根据错误提示，补充必填参数
KP.AE_ALIPASS_PARAMS_FORMAT_ERROR	格式错误。非json格式	检查json格式
KP.AE_ALIPASS_PARAMS_VALUE_INVAILD	参数值不合法	根据错误提示修改
KP.AE_SYSTEM_ERROR	保存失败	重试或联系技术支持
KP.AE_ALIPASS_REPEAT_ADD_ERROR	卡券已经存在	重复添加，幂等控制

更新卡券接口

接口调用说明

接口名称：alipay.pass.instance.update

接口描述：支付宝卡券更新接口

使用场景介绍：对于已经发布的卡券，商户可通过此接口进行更新，更新卡券接口包含三大主要功能：核销卡券、失效卡券、更新卡券样式内容。

核销卡券功能

核销卡券主要描述开发者如何将发放出去的卡券进行核销，使卡券在用户的支付宝客户端展示为已使用状态。对于支付宝卡券而言，核销操作只是将卡券状态变更为USED（已使用），用户客户端展示为已使用状态，未涉及资金流的核销。仅支持核销有效状态的卡券，若卡券处于卡券删除或者已转赠，不可进行核销操作。

核销卡券功能接口调用示例

在发放卡券接口示例，完成卡券发放的基础上，调用更新卡券接口，对卡券进行核销。

HTTP请求源码示例

https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D&timestamp=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={
  "status": "USED",
  "verify_type": "wave",
  "channel_id": "102014022600003526",
  "serial_number": "4333673662446155",
  "verify_code": "1871236321871",
  "tpl_params":{"useStateDesc": "已使用"}
}

调用更新卡券接口核销卡券之后，用户在支付宝客户端展示的卡券，将变成已使用状态，并且进入已失效列表。详情截图如下：

失效卡券功能

失效卡券主要描述开发者如何将发放出去的卡券进行作废，让卡券在用户的支付宝客户端消失的过程。

HTTP请求源码示例

https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D&timestamp=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={
	"status": "CLOSED"
  "channel_id": "102014022600003526",
  "serial_number": "4333673662446155"
}

更新卡券内容功能

更新卡券样式内容，包括内容、logo、背景图、样式等（要支持更新，必须在模板中将对应字段设置成可变参数）。

更新卡券内容功能接口调用示例

在发放卡券接口示例，完成卡券发放的基础上，调用更新卡券接口（更新优惠描述信息和logoText），对卡券进行更新。

HTTP请求源码示例

https://openapi.alipay.com/gateway.do?sign=fNqP42dy3mgKGIBY20L9Ie2%2FOeVuZcw55Q7jzOFXxHyBDs3uDA4iZIwQLYyO10GARbCkPV%2BhRYdjnepQW7haTvnjuwuyghXdDUYwYADAYG5y0RvimDuQeYS%2BSKGqmEDYneapfWYZoP5acp7dxl7dkcK6byIaYloE5WFxj1RTmEY%3D&timestamp=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={
    "channel_id": "102014022600003526",
    "serial_number": "4333673662446155",
    "tpl_params":{"discountInfo": "凭此券即可打5折","logoText": "四季风情5折优惠券"}
}

支付宝用户卡券详情截图如下：

业务请求参数说明

业务主体参数（biz_content）

参数	参数名称	类型	必填	描述	范例
serial_number	卡券序列号	String(256)	是	商户指定卡券唯一值	209919213
channel_id	商户ID	String(32)	是	代理商代替商户发放卡券后，再代替商户更新卡券时，此值为商户的pid/appid	208891827377109
tpl_params	变量键值对	String(38000)	否	模版动态参数信息【支付宝pass模版参数键值对JSON字符串】	{"title":"xxx会员卡","startDate":"2014-04-10 10:00:00"}
status	更新的状态	String(10)	否	券状态，支持更新为USED、CLOSED两种状态 tpl_params和status必填其一	USED
verify_code	核销码	String(30)	否	核销码串值【当状态变更为USED时，建议传】	8612231273
verify_type	核销方式	String(2)	否	核销方式，目前支持：wave（声波方式）、qrcode（二维码方式）、barcode（条码方式）、input（文本方式，即手工输入方式）。pass和verify_type不能同时为空	wave

公共请求参数说明

HTTPS请求地址：https://openapi.alipay.com/gateway.do 

参数	参数名称	类型	必填	描述	范例
app_id	应用ID	String(32)	是	支付宝分配给开发者的应用ID	2014072300007148
method	接口名称	String(128)	是	接口名称	alipay.pass.template.update
format	数据格式	String(40)	否	仅支持JSON	json
charset	编码格式	String(10)	是	请求使用的编码格式，如UTF-8,GBK,GB2312等	UTF-8
sign_type	签名方式	String(10)	是	商户生成签名字符串所使用的签名算法类型，目前支持RSA	RSA
sign	签名值	String(256)	是	商户请求参数的签名串，详见签名与验签	详见示例
timestamp	请求时间	String(19)	是	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	版本	String(3)	是	调用的接口版本，固定为：1.0	1.0
app_auth_token	授权令牌	String(40)	否	详见应用授权

响应结果说明

响应结果示例

{
  "alipay_pass_instance_add_response": {
    "code": "10000",
    "msg": "Success",
    "result": "{ \"serialNumber\":\"1550547540752564\",\"operate\":\"UPDATE\"}",
    "success": true
  },
  "sign": "hAxz/ahsRObKHxo6d41OcfPyDVMJKaHC77Lp9+uE2ENV9w4tpBQKYim1D1ACPYq1ziN5532oEeBAbV6Wo6YNCRwFiMAKRGO8Fm5UOAHxfr4E35mb1gcihR31N25YLCD/k5fDPY1daezb57fPcq4zDiVAy49jd5gNcC9v85yEtck="

返回参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
success	String	否	必须	true	操作成功标识【true：成功；false：失败】
result	String	否	必须	{"pass_id":"989901","serialNumber":"209919213","operate":"UPDATE"}	参见下面的“更新卡券实例信息参数说明”

更新卡券实例信息参数说明

名称	类型	是否列表类型	是否必须	示例值	描述
serialNumber	String	否	必须	123555123	商家指定的卡券唯一标识
operate	String	否	必须	UPDATE	操作类型

错误码说明

名称	描述	解决方案
KP.AE_ALIPASS_PARAMS_FORMAT_ERROR	格式错误，非json格式	检查json格式
KP.AE_MOBILE_ALIPASS_NOTEXIST	alipass券不存在	检查serialNumber，channelID组合是否存在
KP.AE_ALIPASS_PARAMS_VALUE_INVAILD	参数值不合法	根据错误提示修改
KP.AE_ALIPASS_PARAME_IS_NULL	必填参数缺少	根据错误提示，补充必填参数
KP.AE_ALIPASS_UPDATE_ERROR	更新失败	重试或联系技术支持
KP.AE_SYSTEM_ERROR	系统错误	重试或联系技术支持
KP.AE_ALIPASS_PARAMS_FORMAT_ERROR	格式错误。非json格式	检查json格式
KP.AE_MOBILE_ALIPASS_NOTEXIST	alipass券不存在	检查serialNumber，channelID组合是否存在
KP.AE_ALIPASS_PARAMS_VALUE_INVAILD	参数值不合法	根据错误提示修改

 

FAQ

关于此文档暂时还没有FAQ