AlipayHKAlipayHKDOCS

6. Update a Gift/Member Card

1 API Path

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

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

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

Scenario：Merchants can update the issued cards and coupons through this interface. Two main functions of this interface: update content and status of cards and coupons.

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

The merchant id, which identifies the settlement target that Alipay would settle to.

String

32

M

2312314123123123

userId

AlipayHK User ID

String

32

C

At least send one ID. userId or openId

2188200000000000

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

O

passId

Card ID, the unique identifier generated by Alipay

String

32

M

status

Card status update：

USED - The ticket is used

CLOSED - Remove the ticket

UPDATE - To update the ticket content

REFUND - The ticket is refunded

String

32

M

CLOSED and REFUND both display this card is bean deleted

image

USED

updateDetailType

When the card status type is UPDATE, the available types are:

UPDATE_TEMPLATE - update template;

UPDATE_DATA_INFO - update template placeholder data;

UPDATE_VALIDITY - Update card validity period;

String

32

C

UPDATE_DATA_INFO

passVerifyCode

write-off code

String

128

O

write-off code string value [When the status is changed to USED, it is recommended to send it]

passVerifyType

write-off method

String

32

O

write-off method, currently supports: wave (sound wave method), qrcode (QR Code method), barcode (barcode method), input (text method, that is, manual input method). pass and verify_type cannot be empty at the same time

endDate

Card expiration time

String

128

O

Card expiration time

2021-01-11T00:00:00+08:00

dataInfo

Dynamic data that needs to be updated, json data type, with language identifier

String

O

Update data type, Chinese and English, passed in json

If it is a scenario of upgrading the membership card level, not only the level data should be passed, but also all the placeholder data should be passed according to the membership card template

2.2 Response Parameter

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

Result

/

M

2.2.3 Result

Name

Description

Type

Length

Required

Remarks

Sample

resultCode

Result code

String

64

M

SUCCESS

resultStatus

Result status

String

2

M

F- Fail

S- Success

S

resultMessage

Result message

String

256

O

success

2.2.4 Result Code

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_UPDATE_FAIL

F

update pass info failed

200OK

6

PASS_HAS_NOT_EXIST

F

pass has not exist

200OK

7

PASS_USED_OCCUPIED

F

pass used occupied

200OK

8

PASS_HAS_NOT_USED

F

pass has not used

200OK

9

BIZ_NOT_SUPPORT

F

Business does not support

200OK

10

PASS_STATUS_ILLEGAL

F

pass status is illegal

200OK

3 Request Sample

3.1 Request

copy
{     
  "merchantId":"6228480402564890018",
  "userId":"2160400000000135",
  "templateId":"5228480402564890018",     
  "passId":"2995228480402564890018",     
  "status":"USED",
  "verifyCode":"52284804025648900182995228480402564890018",
  "verifyType":"qrcode" 
}

3.2 Response

copy
{
  "resultInfo":{
    "resultCode": "SUCCESS",
    "resultMessage":"success",         
    "resultStatus": "S"     
  } 
}

3.3 Examples

Request Body - Card Status AVAILABLE

copy
{
  "merchantId":"6228480402564890018",
  "userId":"2160400000000135",
  "templateId":"5228480402564890018",
  "passId":"2995228480402564890018",
  "status":"AVAILABLE",
  "verifyCode":"52284804025648900182995228480402564890018",
  "verifyType":"52284804025648900182995228480402564890018" 
}

Request Body - Card Status USED

copy
{     
  "merchantId":"6228480402564890018",     
  "userId":"2160400000000135",     
  "templateId":"5228480402564890018",     
  "passId":"2995228480402564890018",     
  "status":"USED",     
  "verifyCode":"52284804025648900182995228480402564890018",
  "verifyType":"52284804025648900182995228480402564890018" 
}

Request Body - Member Card Status UPDATE (Update card level)

copy
{     
  "merchantId":"6228480402564890018",     
 "userId":"2160400000000135",     
 "passId":"2995228480402564890018",     
  "status":"UPDATE",     
  "updateDetailType":"UPDATE_DATA_INFO",      
  "dataInfo": {      
    "zh_HK": {      
      "$level$": "金卡"    
    },   
    "en_US": {      
      "$level$": "gold card"   
    }  
  } 
}

Request Body - Member Card UPDATE (Update card score)

copy
{     
  "merchantId":"6228480402564890018",     
  "userId":"2160400000000135",     
  "passId":"2995228480402564890018",     
  "status":"UPDATE",     
  "updateDetailType":"UPDATE_DATA_INFO",      
  "dataInfo": {      
    "zh_HK": {      
      "$score$": "12000"     
    },   
    "en_US": {      
      "$score$": "12000"   
    }  
  } 
}

Request Body - Member Card UPDATE (Update card template)

copy
{     
  "merchantId":"6228480402564890018",     
  "userId":"2160400000000135",     
  "templateCode":"5228480402564890018",     
  "passId":"2995228480402564890018",     
  "status":"UPDATE",     
  "updateDetailType":"UPDATE_TEMPLATE",      
  "dataInfo": {      
    "zh_HK": {      
      "$score$": "12000",         
      "$level$":"金卡"         
    },   
    "en_US": {      
      "$score$": "12000",          
      "$level$":"gold card" 
    }  
  } 
}