This API is used by the Huawei server to notify your server when a user uses the NFC capabilities of HUAWEI Wallet.
The NFC callback address is provided during service registration in AppGallery Connect.
Protocol |
HTTPS POST |
|---|---|
Direction |
Huawei server -> Developer server |
URL |
NFC callback address provided by the developer in AppGallery Connect. |
Data Format |
Request: Content-Type: application/json Response: Content-Type: application/json |
Updates in V2:
1. Added the Version parameter whose value is V2 in the request header.
2. Changed the value of HMSSignType in the request header to SHA256WithRSA/PSS.
3. Changed the value of HMSSign to the signature generated using the SHA256WithRSA/PSS algorithm. For details, please refer to Signature.
4. Added the passTypeIdentifier, sceneType, pushToken, and noticeToken parameters to the request body.
5. Added the value SWIPE_CARD for the eventType parameter.
The parameters in V2 are as follows:
Request Header
Parameter |
Mandatory/Optional |
Type |
Description |
|---|---|---|---|
HMSSignType |
Mandatory |
String |
Signing method. The value is always SHA256WithRSA/PSS. |
HMSSign |
Mandatory |
String |
Signature value. |
Version |
Mandatory |
String |
Callback API version. The value is always V2. |
Request Body
Parameter |
Mandatory/Optional |
Type |
Description |
|---|---|---|---|
eventId |
Mandatory |
String(32) |
Event ID. This parameter can be used to deduplicate callback notifications sent from the Huawei server. |
eventTime |
Mandatory |
String(32) |
Event time, which is a UTC time in format of yyyy-MM-dd'T'HH:mm:ss:SSS'Z'. |
eventType |
Mandatory |
String(32) |
Event type. RECEIVE_CARD: A user claims an NFC pass. DELETE_CARD: A user deletes an NFC pass. SWIPE_CARD: A user swipes an NFC pass. |
passNumber |
Mandatory |
String(32) |
Pass number. The value is the same as that of serialNumber. |
passTypeIdentifier |
Mandatory |
String(32) |
Service ID that you registered in AppGallery Connect. |
sceneType |
Optional |
String(32) |
Scene type. USER_OPERATION_DELETE_CARD: A user deletes a pass from HUAWEI Wallet, or signs out of the current HUAWEI ID in HUAWEI Wallet, which also triggers pass deletion. RESTORE_FACTORY_SETTINGS: A user restores the device to factory settings, which triggers pass deletion. REMOTE_DELETE_CARD: The Huawei server deletes a pass, for example, when a user reports pass loss. THIRD_PARTY_DELETE_CARD: You delete a pass. |
pushToken |
Optional |
String(64) |
Unique ID for associating a HUAWEI ID and a device. |
noticeToken |
Optional |
String(64) |
ID of an NFC event, which is used to call the Pushing Messages to Users Who Use the NFC Capability API. This ID is valid for 3 minutes. |
POST /walletkit/nfccallback HTTP/1.1
Content-Type: application/json;charset=utf-8
HMSSignType: SHA256WithRSA/PSS
HMSSign: ***
Version: V2
Accept: application/json;charset=utf-8
Host: partmer.host.com
{
"eventId": "0a1f133471c4102c8171f845919906f3",
"eventTime": "2020-04-27T07:40:24.259Z",
"eventType": "DELETE_CARD",
"passNumber": "40001",
"passTypeIdentifier": "hwpass.com.partner.examplepasstype"
}
The parameters in V1 are as follows:
Request Header
Parameter |
Mandatory/Optional |
Type |
Description |
|---|---|---|---|
HMSSignType |
Mandatory |
String |
Signing method. The value is always SHA256WithRSA. |
HMSSign |
Mandatory |
String |
Signature value. |
Request Body
Parameter |
Mandatory/Optional |
Type |
Description |
|---|---|---|---|
eventId |
Mandatory |
String(32) |
Event ID. This parameter can be used to deduplicate callback notifications sent from the Huawei server. |
eventTime |
Mandatory |
String(32) |
Event time, which is a UTC time in format of yyyy-MM-dd'T'HH:mm:ss:SSS'Z'. |
eventType |
Mandatory |
String(32) |
Event type. RECEIVE_CARD: A user enables NFC capabilities for a pass. DELETE_CARD: A user disables NFC capabilities for a pass. SWIPE_CARD: A user swipes an NFC pass. |
passNumber |
Mandatory |
String(32) |
Pass number. The value is the same as that of serialNumber. NOTE:
For passes generated through a pass package in the Chinese mainland, the pass number is specified by organizationPassId. |
passTypeIdentifier |
Mandatory |
String(32) |
Service ID that you registered in AppGallery Connect. |
POST /walletkit/callback HTTP/1.1
Content-Type: application/json;charset=utf-8
HMSSignType: SHA256WithRSA
HMSSign: ***
Accept: application/json;charset=utf-8
Host: partmer.host.com
{
"eventId": "0a1f133471c4102c8171f845919906f3",
"eventTime": "2020-04-27T07:40:24.259Z",
"eventType": "DELETE_CARD",
"passNumber": "40001",
"passTypeIdentifier": "hwpass.com.partner.examplepasstype"
}
Parameter |
Type |
Description |
|---|---|---|
returnCode |
String |
Result code. For details, please refer to Common Result Codes in the Common Definition section. |
returnDesc |
String |
Result description. |
HTTP/1.1 200 OK
Content-Type: application/json
{
"returnCode": "0",
"returnDesc": "success",
}
private BaseResponse callbackSp(CallbackRequest requestBody) {
String priKey = "xxx";
Map<String, String> header = new HashMap<>(8);
header.put("Content-Type", "application/json;charset=UTF-8");
header.put("Accept", "application/json;charset=UTF-8");
header.put("HMSSignType", "SHA256WithRSA");
String hmsSign = RSAUtils.signByRSA(ToStringUtil.signString(requestBody), priKey);
header.put("HMSSign", hmsSign);
HttpEntity<CallbackRequest> httpEntity = new HttpEntity(requestBody, header);
return restful.postForObject(whiteCardCallbackTask.getCallbackUrl(), httpEntity, BaseResponse.class);
}