5. Create a Gift/Member Card
1 API Path
/api/open/alipay/v1/ipass/pass/manage/createPass
Sample：https://open.alipay.hk/api/open/alipay/v1/ipass/pass/manage/createPass
Scenario：After the user completes the purchase/receipt of the card and coupon in the mini-app, he or she can call this interface to synchronize the issued card and coupon to the AlipayHK APP. After that, user can view the cards in the AlipayHK wallet.
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
Name | Description | Type | Length | Required | Remarks | Sample |
merchantId | Merchant ID | String | 32 | M | 2160220037044427 | |
userId | AlipayHK User ID | String | 32 | C | At least send one ID. userId or openId | 2160120037098191 |
openId | The id that authorized by the AlipayHK user and sent to merchant | String | 32 | C | At least send one ID. userId or openId | fj398457jd8iue98d8w7w93j |
templateCode | Card template number | String | 32 | M | 2020091119027102160530200000039 | |
bizSerialId | Card business serial number | String | 128 | M |
|
|
bizSerialType | Card business serial number type | String | 32 | M | enumerate： OUT_PLAT_FORM | OUT_PLAT_FORM |
startDate | Card effective time | Date | / | M | Template start date time in millisecond timestamp format | 1640970061000 |
endDate | Card expiration time | Date | / | M | Template end date time in millisecond timestamp format | 1640970061000 |
bizCreate | The time when the card was created | Date | / | M | The time when the card was created, in millisecond timestamp format | 1640970061000 |
type | Card type | PassType enumerate： COUPON CARD | 32 | O |
| Coupon Type : COUPON Card Type : CARD |
product | Product Type | PassProductType enumerate： GIFT_CARD MEMBER_CARD | 32 | O |
| Gift Card Product Type: GIFT_CARD Member Card Card Type: : CARD Member Card Product Type: MEMBER_CARD |
codeInfo | Card code value information, in JSON format | string | 512 | M |
| { |
dataInfo | Card details
| The variable assigned in the corresponding template | 8192 | O |
Specific fields are assigned according to template variables | { |
extInfo | String | O | json string | "{\"paymentOrderId\": \"22022050900135606000000000018282\",\"tradeAmountCent\":1000,\"currencyCode\":\"HKD\",\"cardType\":\"SALES_CARD\"}" paymentOrderId - AlipayHK payment order number tradeAmountCent - Transaction Amount (unit points) currencyCode - currency cardType : SALES_CARD - 售卖券(Voucher) DIRECT_CARD - 直领券 (Coupon) MEMBER_CARD - 会员卡 (Member Card) | ||
publishScene | String | O | Enumeration Decide whether to deduct the budget according to the card issuance scenario | FREE_GIVE - gift scenario |
2.2 Response
2.2.1 Header
Name | Description | Type | Length | Required | Remarks | Sample |
clientId | Client ID | String |
| M | 211020000000000000044 | |
signature | Message signature information | String |
| M | algorithm=sha256withrsa,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 | ||
tracerId | Each request will be assigned with a unique id, identify an unique system request, it is not used to identity an unique business request. | String | M | 645864f51556420636666454470556 |
2.2.2 Body
Name | Description | Type | Length | Required | Remarks | Sample |
result | Result info | / | M |
|
| |
passId | System-generated unique identifier | string | 32 | M |
|
|
2.2.3 ResultInfo
Name | Description | Type | Length | Required | Remarks | Sample |
resultCode | Result code | String | 64 | M | SUCCESS | |
resultStatus | Result status | String | 2 | M | S | |
resultMessage | Result message | String | 256 | O | success |
2.2.4 Result Code List
Index | Result Code | Result Status | Description | HTTP Status Code |
1 | PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | 200OK |
2 | SUCCESS | S | success. | 200OK |
3 | UNKNOWN_EXCEPTION | U | API failed due to unknown reason. | 200OK |
4 | USER_NOT_EXIST | F | The user nor exist. | 200OK |
5 | PASS_HAS_EXIST | F | pass has exist |
|
6 | PASS_TEMPLATE_HAS_NOT_EXIT | F | pass template has not exist | 200OK |
7 | PASS_TYPE_NOT_MATCH | F | pass type not match | 200OK |
8 | PASS_PRODUCT_TYPE_NOT_MATCH | F | pass product type not match | 200OK |
9 | PASS_TEMPLATE_JSON_CONTENT_IS_NULL | F | pass template content is null | 200OK |
10 | PASS_TEMPLATE_JSON_CONTENT_ILLEGAL | F | pass template content illegal | 200OK |
3. Request Sample
3.1 Request
{
"merchantId": "2160120036095023",
"userId": "2160220037090534",
"templateCode": "temlate111001",
"bizSerialId": "1111128828",
"bizSerialType": "OUT_PLAT_FORM",
"startDate": 1640970061000,
"endDate": 1640970061000,
"type": "COUPON",
"dataInfo": {
"en_US": {
"$shopname$": "demo shop"
},
"zh_HK": {
"$shopname$": "測試門店"
}
},
"product": "GIFT_CARD",
"codeInfo": {
"$codemsg$": "9123912839123712893",
"$codevalue$": "9123912839123712893"
},
"bizCreate": 1640970061000,
"extInfo": "{\"paymentOrderId\": \"22022050900135606000000000018282\",\"tradeAmountCent\":1000,\"currencyCode\":\"HKD\",\"cardType\":\"SALES_CARD\"}"
}3.2 Response
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
},
"passId": "2020091119027102160530200000039"
}