目录

NFC相关事件回调通知接口

功能介绍

用户进行NFC卡券相关操作时,通知开发者服务器。

场景描述

用户进行华为钱包NFC能力相关操作时,华为钱包服务器调用此API通知开发者服务器。

使用约束

开发者在AGC网站上申请服务时,提供了NFC回调地址。

接口原型

承载协议

HTTPS POST

接口方向

华为钱包服务器->开发者服务器

接口URL

开发者在华为AGC网站上提供的NFC回调地址。

数据格式

请求消息:Content-Type: application/json

响应消息:Content-Type: application/json

V2版本更新:

1、请求头新增“Version”字段,值为“V2”。

2、请求头中的“HMSSignType”的值改为“SHA256WithRSA/PSS”。

3、请求头中的“HMSSign”的签名值改为使用“SHA256WithRSA/PSS”算法。详见签名。

4、请求体中新增“passTypeIdentifier”、“sceneType”、“pushToken”、“noticeToken”参数。

5、“eventType”参数新增值“SWIPE_CARD”。

V2版本参数如下:

请求参数

Request Header:

参数

是否必选

参数类型

描述

HMSSignType

是

String

签名方式。值为固定值:"SHA256WithRSA/PSS"。

HMSSign

是

String

签名值

Version

是

String

回调接口版本号。为固定值“V2”。

Request Body:

参数

是否必选

参数类型

描述

eventId

是

String(32)

事件ID。若钱包服务器多次重试发送回调通知,开发者服务器可以用此参数去重。

eventTime

是

String(32)

事件发生时间(UTC时间):"yyyy-MM-dd'T'HH:mm:ss:SSS'Z'"

eventType

是

String(32)

事件类型:

“RECEIVE_CARD”:用户领取NFC卡券。

“DELETE_CARD”:删除NFC卡券。

“SWIPE_CARD”:用户使用NFC卡券刷卡。

passNumber

是

String(32)

卡券号,即“serialNumber”。

说明:

中国大陆卡券包方式生成的卡券,此参数为“organizationPassId”。

passTypeIdentifier

是

String(32)

开发者在AGC网站注册的服务号。

sceneType

否

String(32)

场景类型:

“USER_OPERATION_DELETE_CARD”:用户在华为钱包App里删卡,或用户在华为钱包App退出华为账号触发删卡。

“RESTORE_FACTORY_SETTINGS”:用户恢复手机出厂设置触发删卡。

“REMOTE_DELETE_CARD”:华为服务器删卡,如用户挂失场景。

“THIRD_PARTY_DELETE_CARD ”:开发者删卡。

pushToken

否

String(64)

账号及设备关联的唯一标识。

noticeToken

否

String(64)

NFC事件对应的标识,用于调用用户使用NFC能力后推送消息接口。此标识有效时间为3分钟。

请求示例

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"
 }

V1版本参数如下:

请求参数

Request Header:

参数

是否必选

参数类型

描述

HMSSignType

是

String

签名方式。值为固定值:"SHA256WithRSA"。

HMSSign

是

String

签名值

Request Body:

参数

是否必选

参数类型

描述

eventId

是

String(32)

事件ID。若钱包服务器多次重试发送回调通知,开发者服务器可以用此参数去重。

eventTime

是

String(32)

事件发生时间(UTC时间):"yyyy-MM-dd'T'HH:mm:ss:SSS'Z'"

eventType

是

String(32)

事件类型:

“RECEIVE_CARD”:用户开通相关卡券的NFC能力。

“DELETE_CARD”:用户删除相关卡券的NFC能力。

“SWIPE_CARD”:用户使用相关卡券的NFC能力刷卡。

passNumber

是

String(32)

卡券号,即serialNumber。

说明:

中国区卡券包方式生成的卡券,此参数为"organizationPassId"。

passTypeIdentifier

是

String(32)

开发者在AGC网站注册的服务号。

请求示例

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"
 }

响应参数

参数

参数类型

描述

returnCode

String

响应码,详见回调接口公共定义中的公共响应码。

returnDesc

String

错误描述

响应示例

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);
}