4. Query Card Template

2024-11-22 08:09

1 API Path

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

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

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	Required	Remarks	Sample
templateCode	String	64	M	Template	82022031000135000000000000624234
merchantId	String	64	M	Merchant ID	2160120041113167

2.2 Response

2.2.1 Body

Field	Type	Length	Remarks	Sample
templateCode	String	64	Template Code	82022031000135000000000000624234
startDate	Date	/	Template start date time in millisecond timestamp format	1640970061000
endDate	Date	/	Template end date time in millisecond timestamp format	1640970061000
status	String	32	Template Status: valid - default status frozen - template frozen expired - template expired closed - template offline	valid
codeType	String	16	Code type barcode - Barcode qrcode - QR code promocode - Promotion Code	barcode
codeStandrad	String	16	Code standard CODE128 - Barcode default standard EAN-13 - Barcode standard QRCODE - QR Code	CODE128
imageUrl	String	512	Image URL
button	Object	/	Button setup infomaration	JSON Object
localeInfo	Object	/	Card information based on different locale	JSON Object
merchantLogo	String	512	Logo Image URL
currentAmount	Object	0~100000000	Sell price (unit: cents)	1000 ( means 10.00HKD)
originalAmount	Object	0~100000000	Original price (unit: cents)	1000 ( means 10.00HKD)
discount	Integer	1~100	Discount rate	10
stock	Integer	1~1000000	Amount in Stock	100000
orderPageLink	String	512	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	Labeling for industry classification	["Medical","Cosmetics"] Details see the section 2.2.4 Categories for enumeration values
availableStock	Long	/	available stock num	10000
bizMids	LIst<String>	Maximum is 30	Associated merchant ids	["2160199994945610","2160199994945611"]
exposure	String	/	Exposure label. Allow giftcard to be displayed in AlipayHK designated in-app areas. Enumerations: exposed - exposure hidden - hide from exposure	exposed
passExtInfo	JSON	/	Gift card template extend info	{ "availableStoreIds":["storeid1", "storeid2"], "availableBrandIds":["brandid1","brandid2"] }

2.2.2 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	Open system browser (this field is not appliable in AlipayHK)	false

2.2.3 LocaleInfo

Field	Type	Length	Mandatory	Remarks	Sample
name	String	25	Y	Gift card name
description	String	4000	Y	Gift card description
shops	String	1000	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.2.4 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.2.5 currentAmount or originalAmount Object

Field

Type

Remarks

Sample

value

String

The value of the smallest monetary unit. (unit: cents)

10000

currency

String

Currency ,

HKD,CNY,USD,JPY, etc

HKD

2.2.6 CustomTab

Field	Type	Length	Mandatory	Remarks	Sample
label	String	20	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.7 ResultCode

ResultCode	resultStatus	resultMessage
SUCCESS	S	success
PARAM_ILLEGAL	F	request parameter illegal
PASS_TEMPLATE_NOT_EXIST	F	pass template not exsit

3. Request Example

3.1 Request

copy
{
   "merchantId": "2160120041113167",
   "templateCode": "82022031100135000000000000626075"
}

3.2. Response

copy
{
    "availableStock": 10000,
    "button": {
        "browserOpen": false,
        "btnType": "payment",
        "btnUrl": "https://Alipay.com",
        "urlType": "CUSTOM_BTN"
    },
    "categories": [
        "Groceries",
        "Medical"
    ],
    "bizMids":[
    "2160124044445610",
    "2160124044445611"
    ],
    "exposure": "exposed",
    "passExtInfo":{
        "availableStoreIds":["1248934u", "12489ej23i"],
      "availableBrandIds":["234981ehebb","34u998h4v"]
    },
    "codeStandard": "CODE128",
    "codeType": "promocode",
    "currentAmount": {
        "currency": "HKD",
        "value": "1000"
    },
    "discount": 16,
    "endDate": 1667120401000,
    "imageUrl": "https://alipay.com/glory66",
    "localeInfo": {
        "en_US": {
            "brandName": "AliCenter",
            "customTabs": [
                {
                    "label": "DIY tag 1",
                    "type": "url",
                    "value": "https://alipay.com/glory111"
                },
                {
                    "label": "DIY tag 2",
                    "type": "url",
                    "value": "https://alipay.com/glory222"
                },
                {
                    "label": "DIY tag 3",
                    "type": "url",
                    "value": "https://alipay.com/glory333"
                },
                {
                    "label": "DIY tag 4",
                    "type": "url",
                    "value": "https://alipay.com/glory444"
                }
            ],
            "description": "Make it",
            "name": "【Hung Fook Tong】Popularity in Taiwan Sunnyhill",
            "shops": "You can use any store you know"
        },
        "zh_HK": {
            "brandName": "阿里中心",
            "customTabs": [
                {
                    "label": "自定义tag1",
                    "type": "url",
                    "value": "https://alipay.com/glory111"
                },
                {
                    "label": "自定义tag2",
                    "type": "url",
                    "value": "https://alipay.com/gloey2222"
                },
                {
                    "label": "自定义tag3",
                    "type": "url",
                    "value": "https://alipay.com/glory333"
                },
                {
                    "label": "自定义tag4",
                    "type": "url",
                    "value": "https://alipay.com/glory44444"
                }
            ],
            "description": "省着点",
            "name": "【鴻福堂】台灣人氣微熱山丘鳳梨奶黃月餅(1盒...",
            "shops": "你知道的店都能用"
        }
    },
    "merchantLogo": "https://www.merchantLogo.com",
    "orderPageLink": "alipayhk://platformapi/startapp?appId=2160003634300010",
    "originalAmount": {
        "currency": "HKD",
        "value": "1200"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "startDate": 1664351748000,
    "status": "valid",
    "stock": 10000,
    "templateCode": "22022092700135606000000000154152"
}