5. Create a Gift/Member Card

2024-04-15 07:54

1 API Path

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

Production domain: https://open.alipay.hk

Endpoint：https://open.alipay.hk/api/open/alipay/v1/ipass/pass/manage/createPass

Scenario：After user completed purchasing/receiving the card or coupon in mini-app, merchant backend should call this interface to synchronize the issued card or coupon to AlipayHK in-app wallet.

2 API Request

2.1 Request

2.1.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

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		{ "$codemsg$": "9123912839123712893", "$codevalue$": "9123912839123712893" }
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	ResultInfo	/	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

copy
{   
  "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

copy
{  
  "result": {   
    "resultCode": "SUCCESS",   
    "resultMessage": "success",   
    "resultStatus": "S"  
  },  
  "passId": "2020091119027102160530200000039" 
}