AlipayHKAlipayHKDOCS

1. Create Template

POST /api/open/alipay/v1/ipass/template/manage/createTemplate

Use this interface to create template of redeemable card / ticket.

General Headers

Name

Description

Type

Sample

Client-Id

REQUIRED

An ID provided by AlipayHK, used to identify partner and application system.

String

4Q5Y8W0WSG45P907917

Content-Type

REQUIRED

The RFC 2616 media type of the request body, the charset should be as same as the one used for cryptographic operations. 

String

application/json; charset=UTF-8

Signature

REQUIRED

A key-value pairs string separated by commas (,), which keys and values are joined by equal signs (key=value). 

Valid keys include: 

  • algorithm: The digital signature algorithm used in generating the signature, RSA256 or ECC224, uses RSA256 by default. 
  • keyVersion: The key version of the signing key configured with Client-Id, uses the latest version by default. 
  • signature: The signature value of this request. 

String

algorithm=RSA256,keyVersion=1,signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

Encrypt

REQUIRED when message content needs to be encrypted. 

A key-value pairs string separated by commas (,), which keys and values are joined by equal signs (key=value). 

Valid keys include: 

  • algorithm: The symmetric key algorithm used in encryptingthe signature, only RSA_AES is supported. 
  • keyVersion: The key version of the signing key configured with Client-Id, uses the latest version by default.
  • symmetricKey: The encrypted symmetric key.

String

algorithm=RSA_AES,keyVersion=1,symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93

Request-only Headers

Name

Description

Type

Sample

Request-Time

REQUIRED

The ISO-8601 datetime of this API request with timezone.

String

2024-05-22T06:42:21+05:30

Response-only Headers

Name

Description

Type

Sample

Response-Time

REQUIRED

The ISO-8601 datetime of this API response with timezone.

String

2024-05-22T06:42:21+05:30

Tracer-Id

An ID for tracing this request.

String

abcdefg135202000000000263818


Request parameters

requestId string  REQUIRED

​An unique ID of this request.​

More information:

  • Maximum length: 32 characters

merchantId string  REQUIRED

Merchant ID provided by AlipayHK.

startDate number  REQUIRED

Active datetime of the template in milliseconds.

endDate number  REQUIRED

Expiry datetime of the template in milliseconds.

type string  REQUIRED

Type of template.

  • COUPON: Redeemable card scenarios.
  • TICKET: Ticket scenarios.

product string  REQUIRED

Product type based on type.

Type

Value

COUPON

GIFT_CARD: Redeemable cards, i.e. coupon / gift card / membership card.

TICKET

PASS: Admission ticket.

MOVIE: Movie ticket.

AIR_TICKET: Flight ticket.

TRAIN_TICKET: Train ticket.

BUS_TICKET: Bus ticket.

SHIP_TICKET: Ship ticket.


codeType string  REQUIRED

Type of display code.

  • barcode: Display barcode.
  • qrcode: Display QR code.
  • promocode: Display promotion code.
  • none: Do not display code.

codeStandard string  REQUIRED

Standard of the display code.

  • CODE128: Linear barcode symbology defined in ISO/IEC 15417:2007.
  • EAN-13: European Article Number barcode.
  • QRCODE: QR code.

imageUrl string  REQUIRED

An URL referencing an image in square scale 1:1, 350 x 350 px.

image.png

Make sure the core information is displayed within the top 2/3 of the image, the bottom 1/3 maybe cropped in some scenarios.


More information:

  • Maximum length: 512 characters
  • Value range: <100 KB

button Button  REQUIRED

An extended object information for button setup.

Show child parameters

localeInfo LocaleInfo  REQUIRED

An extended card information object of current ​​type​ based on different locale, i.e. zh_HK, en_US.

Select scenario

An URL referencing the merchant logo.

More information:

  • Maximum length: 512 characters
  • Value range: <100KB

currentAmountCent number  

Selling price in cents (i.e. 100 = 1 HKD).

More information:

  • Value range: 0 - 100000000

originalAmountCent number  

Original price in cents (i.e. 100 = 1 HKD).

More information:

  • Value range: 0 - 100000000

currencyCode string  

A 3-letter ISO 4217 currency code, i.e. HKD

stock number  

Quantity in stock.

REQUIRED when type == ​COUPON​.

More information:

  • Value range: 1 - 1000000

orderPageLink string  

An URL redirect to the product / purchase page of this product.

  • Link should start with alipayhk://

REQUIRED if any condition met:

  • type == COUPON
  • product == PASS / MOVIE

More information:

  • Maximum length: 512 characters

detailLink string  

An URL redirect to the product description page.

  • Link should start with alipayhk://

REQUIRED when product == PASS / MOVIE

More information:

  • Maximum length: 512 characters

categories Array<string>  REQUIRED

Filter labels for classification in AlipayHK.

For tickets / SKU display, please refer to the category table and use the label with greatest depth as appropriate.

For normal coupons, please refer to table below.

Code Value

Chinese Description

English Description

Food

餐飲

Food & Beverage

CoffeeAndTea

咖啡茶飲

Coffee & Tea

Medical

醫療保健

Medical

Cosmetics

美容化妝

Cosmetics

Groceries

生活百貨

Groceries

Ecommerce

網購

Ecommerce

Electronics

電子產品

Electronics

Games

遊戲娛樂

Electronic Games

Clothing

服飾配件

Clothing & Accessories

Jewellery

珠寶鐘錶

Jewellery & Watches

Entertainment

休閒娛樂

Entertainment

Education

教育

Education

Transportation

交通出行

Transportation

Others

其它

Others

More information:

  • Maximum size: 2 elements

bizMids Array<string>  

List of associated merchant IDs of this redeemable card, allowing them to display in the relevant merchant selling areas, i.e. brand channel.

Only effective when ​​type​ == ​​COUPON.

More information:

  • Maximum size: 30 elements

exposure string  

Display status of the redeemable card / ticket in AlipayHK designated in-app areas.

  • exposed
  • hidden​: default when ​​type == TICKET​

REQUIRED if any condition met:

  • type == COUPON
  • product == PASS / MOVIE

passExtInfo PassExtInfo  

An extended information object of the redeemable card / ticket.

REQUIRED when product == MOVIE / ​​PASS​

Select scenario

Response parameters

resultInfo ResultInfo  REQUIRED

A metadata object indicates the result of the request.

Show child parameters

templateCode string  

ID of the template.

status string  

Status of the template.

API Explorer

Request

Case
COUPON
Request Body

Response

Response Body

UI Reference

Please be aware below UI snapshots may not be the latest and you take the actual APP UI as the final version.

image.png

Result/Error codes

CodeValueMessage
SUCCESSSSuccess
PARAM_ILLEGALFRequest is invalid, usually missing parameters.
PASS_TEMPLATE_BTN_URL_ILLEGALFTemplate button URL is invalid.
PASS_TEMPLATE_IMAGE_URL_ILLEGALFTemplate image URL is invalid.
PASS_TEMPLATE_NAME_ILLEGALFTemplate name format illegally.
PASS_TEMPLATE_DESCRIPTION_ILLEGALFTemplate description format illegally
PASS_TEMPLATE_BRAND_NAME_ILLEGALFTemplate brand name format illegally.
PASS_TEMPLATE_SHOP_ILLEGALFTemplate shops format illegally.
PASS_TEMPLATE_TAG_LABEL_ILLEGALFTemplate custom label format illegally.
PASS_TEMPLATE_TAG_VALUE_ILLEGALFTemplate custom value format illegally.
PASS_TEMPLATE_START_TIME_LESS_CURRENTFTemplate start date is less than the current timestamp.
PASS_TEMPLATE_START_TIME_EXCEEDFThe start time of gift card template exceeds the allowable range.
PASS_TEMPLATE_TIME_INTERVAL_ILLEGALFThe start and end time interval of gift card template is illegal.
PASS_TEMPLATE_END_TIME_EXCEEDFThe end time of gift card template exceeds the allowable range.
PASS_TEMPLATE_IMAGE_INVALIDFThe picture of the gift card template contains sensitive content.
PASS_TEMPLATE_CUSTOMTAB_URL_INVALIDFThe custom url of the gift card template contains sensitive content.
PASS_TEMPLATE_BTN_URL_INVALIDFThe button url of the gift card template contains sensitive content.
PASS_TEMPLATE_CONTENT_INVALIDFThe gift card template text contains sensitive content.