1. Create Ticket Template
1. API Path
/api/open/alipay/v1/ipass/template/manage/createTemplate
Production domain: https://open.alipay.hk
Endpoint：https://open.alipay.hk/api/open/alipay/v1/ipass/template/manage/createTemplate
2. API Request
2.1 Request
2.1.1 Header
Name | Type | Required | Description | Sample |
client-id | String | M | Client ID | 2110200000000044 |
signature | String | M | Message signature information | algorithm=sha256withrsa,keyVersion=2,signature=xxxxxxxxxxxyyyyyyyyyyyyyyzzzzzzzzz== |
encrypt | String | O | Message encryption information | algorithm=rsa, keyVersion=2 |
Content-type | String | M | Http content type | application/json; charset=UTF-8 |
2.1.2 Body
Name | Type | Length | Required | Description | Sample |
requestId | String | 32 | Y | Request unique ID | 62021122800135202000000000263818 |
merchantId | String | 64 | Y | Merchant id | 2160120041113167 |
startDate | Date | / | Y | Template start date time in millisecond timestamp format | 1640970061000 |
endDate | Date | / | Y | Template end date time in millisecond timestamp format | 1640970061000 |
type | String | 32 | Y | Template type (Fixed Value) TICKET | TICKET |
product | String | 32 | Y | Product type PASS - admission ticket MOVIE - movie ticket AIR_TICKET - flight ticket TRAIN_TICKET - train ticket BUS_TICKET - bus ticket SHIP_TICKET - ship ticket | PASS |
codeType | String | 16 | Y | code type barcode - Barcode qrcode - QR Code promocode - Promotion Code none - do not display code | barcode |
codeStandrad | String | 16 | Y | Code standard CODE128 - Default barcode standard EAN-13 - Barcode standard QRCODE - QR Code | CODE128 |
imageUrl | String | 512 | Y | Image URL square Scale 1:1 Recommend Image size: 350px(W)x350px(H) Safe area: Safe area is the top 2/3 part as shadowed with red in the above sample picture. To ensure the perfect display, please place the main information of the product or service within the safe area. The part out of the safe area might be cropped in some scenarios. |
|
button | Object | / | Y | Button setup information | |
localeInfo | Object | / | Y | Multi-language info | |
merchantLogo | String | 512 | Y | logo image URL | |
currentAmountCent | Long | 0~100000000 | O | Sell price (unit: cents) | 1000 = 10.00HKD |
originalAmountCent | Long | 0~100000000 | O | Original price (unit: cents) | 1000 = 10.00HKD |
currencyCode | String | 16 | O | Currency , HKD, CNY,USD,JPY, etc | HKD |
stock | Integer | 1~1000000 | O | Amount in Stock | 100000 |
orderPageLink | String | 512 | C When product field is set to below value, this field is mandatory
| Product sales link. Configure the link to jump to product purchase page
| alipayhk://platformapi/startapp?appId=2160003634300010&page=pages%2Fvouchers%2Fdetail%2Fdetail%3Fsource%3Dcampaign%26couponId%3D184056 |
detailLink | String | 512 | C When product field is set to below value, this field is mandatory
| Product introduction page
| |
categories | LIst<String> | max 2 | Y | Labeling for industry classification | ["Medical","Food"] 2.1.6 for enumeration values |
exposure | String | 16 | C When product field is set to below value, this field is mandatory
| Exposure label. Allow template to be displayed in AlipayHK designated in-app areas. Enumerations: exposed - exposure hidden - hide from exposure It is default to be hidden if not defined. | exposed |
passExtInfo | JSON | / | C When product field is set to below value, this field is mandatory
| Movie sorting info, to determine movie display order on in-app designated page. 2.1.7 for value explanations | { "artificialSortNo": 1, "sessionTotal": 2000 } |
2.1.3 Button
Name | Type | Length | Required | Description | Sample |
btnType | String | 8 | Y | Button Type none - do not display usage - use immediately payment - redirect to wallet payment QR code page | usage |
urlType | String | 16 | Y | URL Type: CODE_PAY_BTN - Payment QR code page SCAN_PAY_BTN - Scan to pay page CUSTOM_BTN - Custom URL | SCAN_PAY_BTN |
btnUrl | String | 512 | O | Custom URL (When urlType=CUSTOM_BTN, this field is mandatory) | |
browserOpen | boolean | / | O | open from Browser （ Only for A+ Merchant ） Values： false - by default true | false |
2.1.4 LocaleInfo
Name | Type | Length(CN/EN) | Required | Description | Sample |
name | String | 100/150 | Y | Ticket/movie name Will be posted on AlipayHK in-app public areas. | 香港迪士尼樂園一日入場票 |
subName | String | 400/400 | C When product field is set to below value, this field is mandatory
| Short descriptions of a Ticket/movie Will be posted on AlipayHK in-app public areas. | 香港迪士尼度假樂園特價票 |
description | String | 4000/3000 | Y | Usage descriptions | |
terms | String | 4000/3000 | O | Terms and conditions | |
shops | String | 1000/800 | O | Applicable stores | |
brandName | String | 32/64 | Y | Supplier name/cinema name/sponsor name | A+Rewards MCL China Airline 香港迪士尼樂園 |
address | String | 200/200 | O | Locations | |
customTabs | List<CustomTab> | / | O | custom tab list | |
localeExtInfo | JSON | / | O | multi-language extend info | { "level": "I", "movieCategory": "动作片、科幻片", "director": "麥克米曹", "actor": "積伯克 奥卡菲纳 奥维拉戴维斯 德斯汀荷夫曼 吴漢章 拜仁鈞士頓 伊安麥聖 關繼威" } |
2.1.5 CustomTab
Name | Type | Length | Required | Description | Sample |
label | String | 20/40 | Y | tab name | tab name 1 |
type | String | 16 | Y | Custom Tab Type url - when the tag is clicked, the screen will open the specified URL | url |
value | String | 256 | Y | url to be opened |
2.1.6 categories
Chinese | English | code |
餐飲 | Food & Beverage | Food |
咖啡茶飲 | Coffee & Tea | CoffeeAndTea |
醫療保健 | Medical | Medical |
美容化妝 | Cosmetics | Cosmetics |
生活百貨 | Groceries | Groceries |
網購 | Ecommerce | Ecommerce |
電子產品 | Electronics | Electronics |
遊戲娛樂 | Electronic Games | Games |
服飾配件 | Clothing & Accessories | Clothing |
珠寶鐘錶 | Jewellery & Watches | Jewellery |
休閒娛樂 | Entertainment | Entertainment |
教育 | Education | Education |
交通出行 | Transportation | Transportation |
其它 | Others | Others |
展覽 | Exhibition | Exhibition |
電影 | Movie | Movie |
景點 | Attraction | Attraction |
2.1.7 passExtInfo
Name | Type | Length | Required | Description | Sample |
artificialSortNo | Long | / | N | Manual sorting weight, used to manupulate movie ordering | 1 |
sessionTotal | Long | / | N | Total number of movie sessions， used to manupulate movie ordering | 50 |
2.1.8 localeExtInfo
Name | Type | Length | Required | Description | Sample |
level | String | 16/16 | N | Movie level | I、IIA |
movieCategory | String | 200/200 | N | Movie classifications | |
director | String | 200/200 | N | Name of directors | |
actor | String | 200/200 | N | Name of actors/actress |
2.2 Response
Name | Type | Length | Description | Sample |
resultInfo | Object | / | Result code | |
templateCode | String | 32 | Template Id | |
status | String | 16 | Template status |
2.2.1 ResultInfo
Name | Type | Length | Description | Sample |
resultCode | String | Result code | SUCCESS | |
resultStatus | String | Result Status F - Failed S - Success | S | |
resultMsg | String | Result message | SUCCESS |
2.2.2 ResultCode
ResultCode | resultStatus | resultMessage |
SUCCESS | S | success |
PARAM_ILLEGAL | F | request parameter illegal |
PASS_TEMPLATE_BTN_URL_ILLEGAL | F | pass template button url format illegal |
PASS_TEMPLATE_IMAGE_URL_ILLEGAL | F | pass template image url format illegal |
PASS_TEMPLATE_NAME_ILLEGAL | F | pass template name format illegal |
PASS_TEMPLATE_DESCRIPTION_ILLEGAL | F | pass template description format illegal |
PASS_TEMPLATE_BRAND_NAME_ILLEGAL | F | pass template brand name format illegal |
PASS_TEMPLATE_SHOP_ILLEGAL | F | pass template shops format illegal |
PASS_TEMPLATE_TAG_LABEL_ILLEGAL | F | pass template custom label format illegal |
PASS_TEMPLATE_TAG_VALUE_ILLEGAL | F | pass template custom value format illegal |
PASS_TEMPLATE_START_TIME_LESS_CURRENT | F | pass template start date less than the current time |
PASS_TEMPLATE_START_TIME_EXCEED | F | The start time of gift card template exceeds the allowable range |
PASS_TEMPLATE_TIME_INTERVAL_ILLEGAL | F | The start and end time interval of gift card template is illegal |
PASS_TEMPLATE_END_TIME_EXCEED | F | The end time of gift card template exceeds the allowable range |
PASS_TEMPLATE_IMAGE_INVALID | F | The picture of the gift card template contains sensitive content |
PASS_TEMPLATE_CUSTOMTAB_URL_INVALID | F | The custom url of the gift card template contains sensitive content |
PASS_TEMPLATE_BTN_URL_INVALID | F | The button url of the gift card template contains sensitive content |
PASS_TEMPLATE_CONTENT_INVALID | F | The gift card template text contains sensitive content |
3. Request Sample
3.1 Request - Traffic Ticket
{
"requestId": "1263848959000000000",
"type": "TICKET",
"product": "AIR_TICKET",
"codeType": "none",
"codeStandard": "QRCODE",
"endDate": 4079233562000,
"startDate": 1712478362838,
"imageUrl": "https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*4VyzRq3j5KMAAAAAAAAAAAAADgeDAQ/original",
"merchantLogo":"https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*GKczQIIw5ToAAAAAAAAAAAAADgeDAQ/original",
"merchantId":"2160120041113167",
"categories":["Transportation"],
"button": {
"btnType": "none",
"btnUrl": "",
"urlType": ""
},
"localeInfo": {
"zh_HK": {
"customTabs": [
{
"label": "自定义tag1",
"type": "url",
"value": "https://alipay.com/glory111"
}
],
"description": "1.請向入口職員展示以上電子票2.每張電子票只限一人使用及使用一次2.持電子票人士可於指定特別通道換領幸運卡乙張",
"terms":"Lorem ipsum dolor坐amet，consectetur adipiscing elit，sed do eiusmod tempor incididunt ut labore et dolore magna aliqua。乌特尼姆和最小的威尼斯人，诺斯特鲁德·埃克劳姆科的工作人员，尼西和阿利奎普的前任。Duis aute irure dolor in reprechenderit in volupate velit esse cillum dolore eu fugiat nulla pariatur。除非你偶尔会做出不利于你的决定，否则你就不会因为工作而受到惩罚",
"name": "香港至上海經濟艙機票",
"brandName": "國泰航空",
"address":"香港迪士尼公园12号"
},
"en_US": {
"customTabs": [
{
"label": "DIY tag 1",
"type": "url",
"value": "https://alipay.com/glory111"
}
],
"description": "Please display the above electronic tickets to the entrance staff. Each electronic ticket is limited to one person and can be used once. Holders of electronic tickets can redeem one lucky card at the designated special channel",
"terms":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum",
"name": "Flight ticket from HK to Shanghai",
"brandName": "Cathay Pacific Airways",
"address":"12 Disneyland Park, Hong Kong"
}
}
}3.2 Request - Movie Ticket
{
"requestId": "1263848959000000000",
"type": "TICKET",
"product": "MOVIE",
"codeType": "qrcode",
"codeStandard": "QRCODE",
"endDate": 4079233562000,
"startDate": 1712478362838,
"imageUrl": "https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*4VyzRq3j5KMAAAAAAAAAAAAADgeDAQ/original",
"merchantLogo": "https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*GKczQIIw5ToAAAAAAAAAAAAADgeDAQ/original",
"orderPageLink":"alipayhk://platformapi/startapp?appId=2160003634301234&page=pages%2Fvouchers%2Fdetail%2Fdetail%3Fsource%3Dcampaign%26couponId%3D184056",
"merchantId": "2160120041113167",
"currentAmountCent":"996",
"originalAmountCent":"990",
"currencyCode":"HKD",
"categories":["Movie"],
"button": {
"btnType": "none",
"btnUrl": "",
"urlType": ""
},
"localeInfo": {
"zh_HK": {
"customTabs": [{
"label": "自定义tag1",
"type": "url",
"value": "https://alipay.com/glory111"
}],
"description": "1.請向入口職員展示以上電子票2.每張電子票只限一人使用及使用一次2.持電子票人士可於指定特別通道換領幸運卡乙張",
"terms": "Lorem ipsum dolor坐amet，consectetur adipiscing elit，sed do eiusmod tempor incididunt ut labore et dolore magna aliqua。乌特尼姆和最小的威尼斯人，诺斯特鲁德·埃克劳姆科的工作人员，尼西和阿利奎普的前任。Duis aute irure dolor in reprechenderit in volupate velit esse cillum dolore eu fugiat nulla pariatur。除非你偶尔会做出不利于你的决定，否则你就不会因为工作而受到惩罚",
"name": "功夫熊貓4",
"shops": "",
"brandName": "ACX",
"address": "北角匯2期2樓211-213號鋪",
"subName": "動畫 喜劇 冒險",
"localeExtInfo": {
"level": "I",
"movieCategory": "动作、喜剧",
"director": "麥克米曹",
"actor": "積伯克 奥卡菲纳 奥维拉戴维斯 德斯汀荷夫曼 吴漢章 拜仁鈞士頓 伊安麥聖 關繼威"
}
},
"en_US": {
"customTabs": [{
"label": "DIY tag 1",
"type": "url",
"value": "https://alipay.com/glory111"
}],
"description": "Please display the above electronic tickets to the entrance staff. Each electronic ticket is limited to one person and can be used once. Holders of electronic tickets can redeem one lucky card at the designated special channel",
"terms": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum",
"name": "Kung Fu Panda 4",
"shops": "",
"brandName": "ACX",
"address": "Harbour North Phase 2,North Point, Java Rd,",
"subName": "Animation Comedy Adventure",
"localeExtInfo": {
"level": "I",
"movieCategory": "Comedy",
"director": "Mike Mitchell",
"actor": "Jack Black,Dustin Hoffman,Angelina Jolie,Ian McShane,Seth Rogen,Lucy Liu,David Cross,Randall Duk Kim,James Hong,Jackie Chan"
}
}
},
"detailLink": "alipayhk://www.ll.com",
"passExtInfo": {
"artificialSortNo": 10,
"sessionTotal": 10
},
"exposure": "exposed"
}3.3 Request - Admission Ticket
{
"requestId": "1263848959000000000",
"type": "TICKET",
"product": "PASS",
"codeType": "qrcode",
"codeStandard": "QRCODE",
"endDate": 4079233562000,
"startDate": 1712478362838,
"imageUrl": "https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*4VyzRq3j5KMAAAAAAAAAAAAADgeDAQ/original",
"merchantLogo": "https://mdn.alipayobjects.com/huamei_xfceij/afts/img/A*GKczQIIw5ToAAAAAAAAAAAAADgeDAQ/original",
"orderPageLink":"alipayhk://platformapi/startapp?appId=2160003634301234&page=pages%2Fvouchers%2Fdetail%2Fdetail%3Fsource%3Dcampaign%26couponId%3D184056",
"merchantId": "2160120041113167",
"currentAmountCent":"996",
"originalAmountCent":"990",
"currencyCode":"HKD",
"categories":["Exhibition"],
"button": {
"btnType": "none",
"btnUrl": "",
"urlType": ""
},
"localeInfo": {
"zh_HK": {
"customTabs": [{
"label": "自定义tag1",
"type": "url",
"value": "https://alipay.com/glory111"
}],
"description": "1.請向入口職員展示以上電子票2.每張電子票只限一人使用及使用一次2.持電子票人士可於指定特別通道換領幸運卡乙張",
"terms": "Lorem ipsum dolor坐amet，consectetur adipiscing elit，sed do eiusmod tempor incididunt ut labore et dolore magna aliqua。乌特尼姆和最小的威尼斯人，诺斯特鲁德·埃克劳姆科的工作人员，尼西和阿利奎普的前任。Duis aute irure dolor in reprechenderit in volupate velit esse cillum dolore eu fugiat nulla pariatur。除非你偶尔会做出不利于你的决定，否则你就不会因为工作而受到惩罚",
"name": "香港迪士尼樂園一日入場票",
"shops": "",
"brandName": "香港迪士尼樂園",
"address": "香港迪士尼樂園",
"subName": "香港迪士尼樂園特價票",
},
"en_US": {
"customTabs": [{
"label": "DIY tag 1",
"type": "url",
"value": "https://alipay.com/glory111"
}],
"description": "Please display the above electronic tickets to the entrance staff. Each electronic ticket is limited to one person and can be used once. Holders of electronic tickets can redeem one lucky card at the designated special channel",
"terms": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum",
"name": "Hong Kong DisneyLand one-day pass",
"shops": "",
"brandName": "Hong Kong DisneyLand",
"address": "Hong Kong DisneyLand",
"subName": "Hong Kong DisneyLand one-day pass special price",
}
},
"detailLink": "alipayhk://www.ll.com",
"exposure": "exposed"
}3.4 Response
{
"templateCode": "82022031100135000000000000626075",
"status": "valid",
"resultInfo":{
"resultCode": "SUCCESS"
"resultMessage":"success",
"resultStatus": "S"
}
}