文档中心 > 开放平台

支付宝卡券API详细说明

更新时间:2016/08/09 访问次数:16311

创建模板接口

接口调用说明

接口名称: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对象,由pass.json、icon、logo、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_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 必须 {“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
返回
顶部