1. Create Merchant’s Membership Card

2024-10-23 07:57

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

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

Provide this interface for AlipayHK to create membership in your system.

Request

Header

Please check API Structure for basics.

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

Body

Name	Description	Type	Sample
createCardChannel conditional	required for Cross-Border scenario. Valid value include HK_CREATE_CARD CN_CREATE_CARD	String	"HK_CREATE_CARD"
createCardRecordId required	An unique ID referencing the membership card creation record in AlipayHK.	String max:
extendInfo required	Extended information for AlipayHK to identify the record. **Use this value in the /createPass interface.	String	{ "createCardRecordId": "111", "uid": "222", "mid": "333" }
mobileNo conditional	required if user logins AlipayHK with mobile number, otherwise empty. Either mobileNo or userEmail must be provided.	String	"852-12345678"
passId conditional	required for Cross-Border scenario. An unique ID referencing the membership card creation record in AlipayCN. **Return this value in the response.	String max: 64
pointsSubjectId required	An unique ID referencing your system which owns the membership card.	String max:
userEmail conditional	required if user logins AlipayHK with email address, otherwise empty. Either mobileNo or userEmail must be provided.	String	"sample@alipayhk.com"
userId required	An unique user ID referencing each AlipayHK user, starts with 2160.	String	"2160XXXXXXXXXXXX"
userSupplementaryInfo required	The customized information required to create membership card, please refer to the template you submitted to AlipayHK.	SupplementaryInfo	See reference.

SupplementaryInfo (For AlipayHK)

Name	Description	Type	Sample
birthDate	Birthday of the user in "YYYY-MM-dd" format.	String	"2005-10-01"
city	City of the user.	String
customerEmail	Register email of the user.	String
firstName	First name of the user.	String
gender	Gender of the user	String	"M"
lastName	Last name of the user.	String
residentAddress	Address of the user.	String
referralCode	Referral code of this registration.	String
referrerId	Referrer ID of this registration.	String
title	Title of the user.	String	"Mr"

SupplementaryInfo (For Cross-Border / AlipayCN)

Name	Description	Type	Sample
birthDate	Birthday date of the user.	String	"10-01"
city	City of the user.	String
customerEmail	Contact email of the user.	String
gender	Gender of the user.	String	"男"
mobileNo required	The mobile number of the user.	String	"13800000000"
name	Full name of the user.	String	"Chris Cai"

Example

copy
{
    "mobileNo": "852-11111111",
    "userEmail": "alipayhk@sample.com",
    "userId": "2160000000",
    "pointsSubjectId": "121312313123",
    "createCardRecordId": "1231312312313",
    "passId": "000001",
    "createCardChannel": "HK_CREATE_CARD",
    "userSupplementaryInfo": "{\"birthDate\":\"1993-01-01\",\"city\":\"香港\",\"customerEmail\":\"abc@qq.com\",\"firstName\":\"火\",\"gender\":\"男\",\"lastName\":\"花\",\"referralCode\":\"推荐码ABC\",\"referrerId\":\"推荐人10086\",\"residentAddress\":\"详细地址\",\"title\":\"先生\"}",
    "extendInfo": "{\"createCardRecordId\":\"2024011219056122400090000000000160190000586318\"}"
}

copy
{
  "mobileNo": "852-11111111",
  "userEmail": "alipayhk@sample.com",
  "userId": "2160000000",
  "pointsSubjectId": "121312313123",
  "createCardRecordId": "1231312312313",
  "passId":"000001",
  "createCardChannel":"HK_CREATE_CARD",
  "userSupplementaryInfo": "null",
  "extendInfo": "{\"createCardRecordId\":\"2024011219056122400090000000000160190000586318\"}"
}

Response

Header

Please check API Structure for basics.

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

Body

Please check API Structure for basics.

Name	Description	Type	Sample
result required	A metadata object indicates the result of the request.	Result	See example below.

Result

Name	Description	Type	Sample
resultCode required	The status code of this result, used for troubleshooting.	String	"SUCCESS"
resultStatus required	The status of this request.	String	"S"
resultMessage	A description message of the result.	String	"success"

Name

Description

Type

Sample

memberCardInfo

conditional

required for Cross-Border scenario.

Information of the membership card.

MemberCardInfo

See reference.

openCardExtInfo

Extra Information for creating member card, required for cross-border scenario.

String (OpenCardExtInfo)

{\"is_new_member\":\"true\"}

MemberCardInfo

Name	Description	Type	Sample
externalCardNo required	ID of the membership card.	String max: 64	"EXT0001"
level	Level of the membership card.	String max: 64	"VIP1"
openDate required	Creation date of the membership card in "YYYY-MM-dd HH:mm:ss" format.	String	"2014-02-20 21:20:46"
passId required	An unique ID referencing the membership card creation record in AlipayCN. **Use the value in the request.	String	"000001"
point	Number of membership points in the card.	String max: 64	"88"
templateId required	Merchant card template ID in AlipayCN.	String	"20170308000000000058101000300045"
userId required	An unique user ID referencing each AlipayHK user, starts with 2160.	String	"216013131313"
validDate required	Expiry date of the membership card in "YYYY-MM-dd HH:mm:ss" format..	String	"2014-02-20 21:20:46"

OpenCardExtInfo

Name	Description	Type	Sample
is_new_member	"true" or "false" value, indicates if the user is a new member in your system.	String	"true"

Result Code

resultCode	resultStatus	resultMessage	Description	Error Message Display on AlipayHK APP
SUCCESS	S	success	API call successfully	NA
PARAM_ILLEGAL	F	Illegal parameters. For example, non-numeric input, invalid date.	Parameter illegal. Please make sure the API parameters meed the requirements on this document	English: Unable to activate merchant membership card. Please try again later. Contact the merchant for more information. Chinese: 無法開通商戶會員卡，請稍後再試。如有更多問題請聯絡商戶查詢。
INVALID_LOGIN_LABEL	F	Do not support registration using this login label.	Can't create thee membership card using the fields send to the Merchant side.	English: Unable to activate merchant membership using AlipayHK login via email. Please change your AlipayHK login method to phone number and try activating merchant membership again. Chinese: 未能成功以 AlipayHK 登入電郵開通商戶會員，請將 AlipayHK 登入方式更換為手機號碼，然後重新開通商戶會員。
DUPULICATED_LOGIN_LABEL	F	This login label has been registered by another user.	The mobile no. or Email address has been bound to another Merchantship acount already	English: This account has already been registered for the merchant's loyalty program. Please contact the merchant for assistance. Chinese: 此賬號已註冊過商戶的會員計劃，請聯絡商戶處理
FROZEN_USER	F	The user account is frozen.	The account has been locked by Merchant. User needs to contact Merchant side to unlock the account	English: This account has been suspended by the merchant. Please contact the merchant for assistance. Chinese: 此賬號已被商戶凍結，請聯絡商戶處理
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	Request timeout or failed due to unknown reason	English: Unable to quickly activate membership using AlipayHK account. Please contact the merchant directly. Chinese: 無法以AlipayHK賬號快速開通會員，請直接聯絡商戶。
NEED_SUPPLY_USER_INFORMATION	F	Need to provide more information	Need to provide more information	NA

Example

Success

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "memberCardInfo": {
    "userId": "216013131",
    "passId": "000001",
    "externalCardNo": "EXT0001",
    "templateId": "20170308000000000058101000300045",
    "openDate": "2000-01-01 21:20:46",
    "validDate": "2100-02-20 21:20:46",
    "level": "VIP1",
    "point": "88"
  },
  "openCardExtInfo": "{\"is_new_member\":\"true\"}"
}

Failed

copy
{
  "result": {
    "resultCode": "PARAM_ILLEGAL",
    "resultMessage": "错误信息",
    "resultStatus": "F"
  }
}

Timeout

copy
{
    "result": {
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "API failed due to unknown reason.",
        "resultStatus": "U"
    }
}