目录

钱包卡券事件回调通知接口

功能介绍

用户领取或删除卡券时，通知开发者服务器。

场景描述

用户在华为钱包App里领取或删除卡券（已在华为钱包服务器中生成并绑定的卡券）时，华为钱包服务器调用此API通知开发者服务器。

使用约束

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

接口原型

承载协议

HTTPS POST

接口方向

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

接口URL

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

数据格式

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

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

V2版本更新：

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

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

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

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

5、“eventType”参数新增值“RECEIVE_CARD”、“TASK_RESULT_NOTIFY”。

V2版本参数如下：

请求参数

Request Header：

参数

是否必选

参数类型

描述

HMSSignType

是

String

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

HMSSign

是

String

签名值

Version

是

String

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

Request Body：

参数

是否必选

参数类型

描述

eventId

是

String(32)

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

passTypeIdentifier

是

String(64)

卡券对应的服务号。

modelId

是

String(32)

卡券模板的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。

instanceId

是

String(32)

个人化实例的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。

eventTime

是

String(32)

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

eventType

是

String(32)

事件类型：

“RECEIVE_CARD”：用户在华为钱包App中领取卡券。

“DELETE_CARD”：用户在华为钱包App中删除卡券。

“TASK_RESULT_NOTIFY”：定时任务通知。

sceneType

否

String(64)

场景类型：

“MODEL_ASYNC_UPDATE_SUCCESS”：更新模板后异步更新相应的卡券。

请求示例

POST /walletkit/callback/notify 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",
  "passTypeIdentifier": "hwpass.com.partner.examplepasstype",
  "modelId": "loyaltyModelTest",
  "instanceId": "40001",
  "eventTime": "2020-04-27T07:40:24.259Z",
  "eventType": "RECEIVE_CARD"
 }

V1版本参数如下：

请求参数

Request Header：

参数

是否必选

参数类型

描述

HMSSignType

是

String

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

HMSSign

是

String

签名值

Request Body：

参数

是否必选

参数类型

描述

eventId

是

String(32)

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

modelId

是

String(32)

卡券模板的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。

instanceId

是

String(32)

个人化实例的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。

eventTime

是

String(32)

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

eventType

是

String(32)

事件类型：

“RECEIVE_CARD”：用户在华为钱包App中领取卡券。

“DELETE_CARD”：用户在华为钱包App中删除卡券。

“EXPIRE_CLEAR”：模板或实例数据过期，被清理。

“TASK_RESULT_NOTIFY”：定时任务通知。

请求示例

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",
  "modelId": "loyaltyModelTest",
  "instanceId": "40001",
  "eventTime": "2020-04-27T07:40:24.259Z",
  "eventType": "RECEIVE_CARD"
 }

响应参数

参数

参数类型

描述

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