文档中心 > 开放平台

开放平台

支付宝卡包API详细说明

更新时间：2017/05/25 访问次数：102217

创建模板接口

接口调用说明

接口名称：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

保存错误

重试或联系技术支持

发放卡券接口

接口调用说明

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

接口描述：支付宝卡券发放卡券接口

使用场景介绍：根据创建模板流程获取模板ID和动态参数；此后，商户将模版ID及模版中设置的动态参数值作为参数，调用发放卡券接口把卡券发放给支付宝用户。

业务请求参数说明

业务主体参数（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
有用(12) 我要提问
文档标签:
卡券
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号