AlipayHKAlipayHKDOCS

Base API

POST /api/open/alipay/v1/ipass/pass/manage/createPass

Use this interface to create a redeemable card / ticket, i.e. after purchase.

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.

userId string  

The AlipayHK user ID this pass is created for.

REQUIRED to provide either openId or userId.

openId string  

Authorization ID of AlipayHK user for merchant.

REQUIRED to provide either openId or userId.

templateCode string  REQUIRED

A template code ID provided by AlipayHK.

bizSerialId string  REQUIRED

Business serial number of this pass.

Must be unique for each pass.

More information:

  • Maximum length: 128 characters

bizSerialType string  REQUIRED

Type of the business serial number.

  • OUT_PLAT_FORM

startDate number  REQUIRED

Effective datetime of this pass in milliseconds.

endDate number  REQUIRED

Expiration datetime of this pass in milliseconds.

Please use the estimated end time of the event, or an appropriate time window for refunding.

bizCreate number  REQUIRED

Creation datetime of this pass 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.


codeInfo object  REQUIRED

An object controls the display code value.

Show child parameters

dataInfo object  

An object carries the data information of each business scenario.

Please refer to each business scenarios.

REQUIRED for ​TICKET​.

extInfo JSON  

An extended information object for different scenarios.

Select scenario

publishScene string  

Decide whether to deduct the budget according to the card issuance scenario.

  • ​​FREE_GIVE: Free giving.

Effective for ​​GIFT_CARD​ only.

Response parameters

resultInfo object  REQUIRED

A metadata object indicates the result of the request.

Show child parameters

passId string  

ID of the created pass.

More information:

  • Maximum length: 32 characters
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_ILLEGALFIllegal parameters. For example, non-numeric input, invalid date.
UNKNOWN_EXCEPTIONUAPI failed due to unknown reason.
USER_NOT_EXISTFThis user doesn't exist.
PASS_HAS_EXISTFPass has been created.
PASS_TEMPLATE_HAS_NOT_EXITFTemplate of this pass doesn't exist.
PASS_TYPE_NOT_MATCHFType of pass doesn't match.
PASS_PRODUCT_TYPE_NOT_MATCHFProduct type of this pass doesn't match.
PASS_TEMPLATE_JSON_CONTENT_IS_NULLFTemplate content of this pass is empty.
PASS_TEMPLATE_JSON_CONTENT_ILLEGALFTemplate content of this pass is invalid.