AlipayHKAlipayHKDOCS

4. Query Template

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

Use this interface to query 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

merchantId string  REQUIRED

Merchant ID provided by AlipayHK.

templateCode string  REQUIRED

An unique ID referencing the template issued by AlipayHK.

More information:

  • Maximum length: 32 characters

Response parameters

result Result  REQUIRED

A metadata object indicates the result of the request.

Show child parameters

templateCode string  

An unique ID referencing the template issued by AlipayHK.

More information:

  • Maximum length: 32 characters

startDate number  

Active datetime of the template in milliseconds.

endDate number  

Expiry datetime of the template in milliseconds.

status string  

Status of the template.

  • valid
  • closed: Permanently unavailable.
  • paused: Temporarily unavailable.

codeType string  

Type of display code.

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

codeStandard string  

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  

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

button Button  

An extended object information for button setup.

Show child parameters

localeInfo LocaleInfo  

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

currentAmount object  

An object represents the value and currency of current selling amount.

Show child parameters

originalAmount object  

An object represents the value and currency of current selling amount.

Show child parameters

discount string  

Discount percentage of this redeemable card / ticket, calculated through original and current amount.

More information:

  • Value range: 1-100

stock number  

Quantity in stock.

REQUIRED when type == ​COUPON​.

More information:

  • Value range: 1 - 1000000

availableStock number  

Number of redeemable card / ticket available in stock.

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

categories Array<string>  

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

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

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

Select scenario
API Explorer

Request

Request Body

Response

Response Body


Result/Error codes

CodeValueMessage
SUCCESSSSuccess
PARAM_ILLEGALFInvalid request parameters.
PASS_TEMPLATE_NOT_EXISTFTemplate does not exist.