AlipayHKAlipayHKDOCS

1. Create Card Template

1 API Path

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

Sample: https://open.alipay.hk/api/open/alipay/v1/ipass/template/manage/createTemplate

2 API Request

2.1 Request

2.1.1 Header

Name

Description

Type

Length

Required

Remarks

Sample

client-id

Client ID

String

M

211020000000000000044

signature

Message signature information

String

M

algorithm=RSA256,keyVersion=2,signature=xxxxxxxxxxxyyyyyyyyyyyyyyzzzzzzzzz==

encrypt

Message encryption information

String

O

algorithm=rsa, keyVersion=2

Content-type

Http content type

String

M

application/json; charset=UTF-8

request-time

Request time

String

M

2023-12-18T02:33:31Z

2.1.2 Body

Field

Type

Length

Mandatory

Remarks

Sample

requestId

String

32

Y

Request unique ID

abcdefg135202000000000263818

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)

COUPON

product

String

32

Y

Product type

(Fixed value)

GIFT_CARD

codeType

String

16

Y

Code type：

barcode - Barcode

qrcode - QR Code

promocode - Promotion Code

none - not display code(need to fill in content when create pass)

barcode

codeStandard

String

16

Y

Code standard:

CODE128 - Barcode default standard

EAN-13 - Barcode stardard

QRCODE - QR Code startadrd

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.

image.png

button

Object

/

Y

Button setup infomaration

JSON Object

localeInfo

Object

/

Y

Card information based on different locale

JSON Object

merchantLogo

String

512

Y

Logo Image URL

currentAmountCent

Long

0~100000000

N

Sell price (unit: cents)

1000 ( means 10.00HKD)

originalAmountCent

Long

0~100000000

N

Original price (unit: cents)

1000 ( means 10.00HKD)

currencyCode

String

16

N

Currency ,

HKD, CNY,USD,JPY, etc

stock

Integer

1~1000000

Y

Amount in Stock

100000

orderPageLink

String

512

Y

Product sales link. Configure the link to jump to coupon purchase

  • Link should start with alipayhk://

alipayhk://platformapi/startapp?appId=2160003634300010&page=pages%2Fvouchers%2Fdetail%2Fdetail%3Fsource%3Dcampaign%26couponId%3D184056

categories

LIst <String>

Maximum is 2

Y

Labeling for industry classification

["Medical","Cosmetics"]

Details see the section 2.1.5 Categories for enumeration values

bizMids

LIst<String>

Maximum is 30

N

Associated merchant ids

["2160199994945610","2160199994945611"]

exposure

String

/

Y

Exposure label. Allow giftcard to be displayed in AlipayHK designated in-app areas.

Enumerations:

exposed - exposure

hidden - hide from exposure

exposed

passExtInfo

JSON

/

O

Gift card template extend info

{

"availableStoreIds":["storeid1", "storeid2"],

"availableBrandIds":["brandid1","brandid2"]

}

2.1.3 Button Object

Field

Type

Length

Mandatory

Remarks

Sample

btnType

String

8

Y

Button Type

none - do not display

usage - use immediately

payment - rediret to wallet payment QR code page

payment

urlType

String

16

Y

URL Type:

CODE_PAY_BTN - Payment QR code page

SCAN_PAY_BTN - Scan to pay page

CUSTOM_BTN - Custom URL

CODE_PAY_URL

btnUrl

String

512

N

Custom URL

(When urlType=CUSTOM_BTN, this field is mandatory)

https://voucher.alipay.hk

browserOpen

boolean

/

N

If open from Browser

（ Only for A+ Merchant ）

Values：

false - default

true

false

2.1.4 LocaleInfo

Field

Type

Length (CHN/EN)

Mandatory

Remarks

Sample

name

String

25/50

Y

Gift card name

subName

String

400/400

N

Short descriptions of a gift card

Will be posted on AlipayHK in-app public areas.

image.png

description

String

4000/3000

Y

Gift card description

shops

String

1000/800

Y

The gift card can be redeemd in shops

brandName

String

32/64

Y

The gift card brand name

OpenRice

customTabs

List <CustomTab>

/

N

Custom Tab list

JSON Object

2.1.5 Categories

Chinese Description

English Description

Code Value

餐飲

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

2.1.6 CustomTab

Field

Type

Length

Mandatory

Remarks

Sample

label

String

20/40

Y

Custom 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

512

Y

URL to be opened

https://alipay.com

2.2 Response

Field

Type

Length

Remarks

Sample

resultInfo

Object

/

Result Code

templateCode

String

64

Template ID

status

String

16

Template Status

2.2.1 ResultInfo

Field

Type

Length

Remarks

Sample

resultCode

String

Result Code

SUCCESS

resultStatus

String

Result Status

F - Failed

S - Success

S

resultMsg

String

Result Description

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 Example

3.1 Request

copy
{
  "requestId": "121212812811211jhkjhkj9878jkjkj",  
  "type": "COUPON",
  "product": "GIFT_CARD",
  "codeType": "barcode",
  "codeStandard": "CODE128",
  "endDate": 1640970061000,
  "startDate": 1640970061000,
  "imageUrl": "https://alipay.com/glory66",
  "merchantLogo": "https://alipay.com/glory66",
  "currentAmountCent": 1000,
  "originalAmountCent": 1000,
  "currencyCode": "HKD",
  "stock": 10000,
  "orderPageLink": "alipayhk://platformapi/startapp?appId=2160003634300010&page=pages%2Fvouchers%2Fdetail%2Fdetail%3Fsource%3Dcampaign%26couponId%3D184056",
  "categories": ["Medical","Cosmetics"], 
  "button": {
    "browserOpen": false,
    "btnType": "payment",
    "btnUrl": "https://Alipay.com",
    "urlType": "CUSTOM_BTN"
  },
  "bizMids":[
    "2160124044445610",
    "2160124044445611"
  ],
  "exposure":"exposed",
  "passExtInfo":{
    "availableStoreIds":["1248934u", "12489ej23i"],
    "availableBrandIds":["234981ehebb","34u998h4v"]
},
  "localeInfo": {
    "zh_HK": {
      "customTabs": [
        {
          "label": "自定义tag1",
          "type": "url",
          "value": "https://alipay.com/2323"
        },
        {
          "label": "自定义tag2",
          "type": "url",
          "value": "https://alipay.com/gloey1"
        },
        {
          "label": "自定义tag3",
          "type": "url",
          "value": "https://alipay.com/glory2"
        },
        {
          "label": "自定义tag4",
          "type": "url",
          "value": "https://alipay.com/glory3"
        }
      ],
      "description": "省着点",
      "name": "随便一个模板名称",
      "shops": "你知道的店都能用",
      "brandName": "阿里中心"    
    },
    "en_US": {
      "customTabs": [
        {
          "label": "DIY tag 1",
          "type": "url",
          "value": "https://alipay.com/1"
        },
        {
          "label": "DIY tag 2",
          "type": "url",
          "value": "https://alipay.com/2"
        },
        {
          "label": "DIY tag 3",
          "type": "url",
          "value": "https://alipay.com/3"
        },
        {
          "label": "DIY tag 4",
          "type": "url",
          "value": "https://alipay.com/4"
        }
      ],
      "description": "Make it",
      "name": "Any template name",
      "shops": "You can use any store you know",
      "brandName": "AliCenter"
      
    }
  }
}

3.2. Response

copy
{
    "templateCode": "82022031100135000000000000626075",
    "status": "valid",
    "resultInfo":{
        "resultCode": "SUCCESS"
        "resultMessage":"success",
        "resultStatus": "S"
    }
}