AlipayHKAlipayHKDOCS

1. Create Merchant’s Membership Card

POST /{Merchant’s tag}/points/membercard/create

Sample：https://hk-api.merchant.com/merchant/api/alipayhk/points/membercard/create

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, 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

mobileNo string  

Mobile number user used to login AlipayHK.

REQUIRED to provide either ​mobileNo​ or ​userEmail​.

userEmail string  

Email address user used to login AlipayHK. 

REQUIRED to provide either mobileNo or userEmail.

userId string  REQUIRED

An unique user ID referencing each AlipayHK user, starts with 2160.

pointsSubjectId string  REQUIRED

An unique ID referencing your system which owns the membership card.

createCardRecordId string  REQUIRED

An unique ID referencing the membership card creation record in AlipayHK.

createCardChannel string  

  • HK_CREATE_CARD: create card through AlipayHK
  • CN_CREATE_CARD​: create card through AlipayCN

REQUIRED for Cross-Border scenario.

passId string  

An unique ID referencing the membership card creation record in AlipayCN.

REQUIRED for Cross-Border scenario, return this value in the response.

userSupplementaryInfo SupplementaryInfo  REQUIRED

The customized information required to create membership card, please refer to the template you submitted to AlipayHK.

We will first call this API with "null", and you should return error NEED_SUPPLY_USER_INFORMATION if user information is not found, we will then prompt user to input user information and request again with the information.

Select scenario

extendInfo string  REQUIRED

Extended information for AlipayHK to identify the record.

Use this value in the /createPass interface.

Response parameters

result Result  REQUIRED

A metadata object indicates the result of the request.

Show child parameters

memberCardInfo MemberCardInfo  

Information of the membership card.

REQUIRED for Cross-Border scenario.

Show child parameters

openCardExtInfo JSONString  

Additional information of the membership card.

Escape the JSON to JSONString.

Show child parameters
API Explorer

Request

Case
With user information
Request Body

Response

Response Body

Result/Error codes

CodeValueMessage
SUCCESSSSuccess
PARAM_ILLEGALFPlease check the parameters of request.
INVALID_LOGIN_LABELFDo not support registration using this login label.
DUPULICATED_LOGIN_LABELFThis login label has been registered by another user.
FROZEN_USERFThe account has been frozen by Merchant. User needs to contact Merchant side to unlock the account
UNKNOWN_EXCEPTIONUAPI failed due to unknown reason, please check with support.
NEED_SUPPLY_USER_INFORMATIONFMore information is needed.

Error Message Display on AlipayHK app

CodeValueMessage
PARAM_ILLEGALEnglishUnable to activate merchant membership card. Please try again later. Contact the merchant for more information.
INVALID_LOGIN_LABELEnglishUnable to activate merchant membership using AlipayHK login via email. Please change your AlipayHK login method to phone number and try activating merchant membership again.
DUPULICATED_LOGIN_LABELEnglishThis account has already been registered for the merchant's loyalty program. Please contact the merchant for assistance.
FROZEN_USEREnglishThis account has been suspended by the merchant. Please contact the merchant for assistance.
UNKNOWN_EXCEPTIONEnglishUnable to quickly activate membership using AlipayHK account. Please contact the merchant directly.
PARAM_ILLEGALChinese無法開通商戶會員卡，請稍後再試。如有更多問題請聯絡商戶查詢。
INVALID_LOGIN_LABELChinese未能成功以 AlipayHK 登入電郵開通商戶會員，請將 AlipayHK 登入方式更換為手機號碼，然後重新開通商戶會員。
DUPULICATED_LOGIN_LABELChinese此賬號已註冊過商戶的會員計劃，請聯絡商戶處理
FROZEN_USERChinese此賬號已被商戶凍結，請聯絡商戶處理
UNKNOWN_EXCEPTIONChinese無法以AlipayHK賬號快速開通會員，請直接聯絡商戶。