HUAWEI Wallet Kit Server Demo

Table of Contents

• Introduction
• Supported Environments
• Apply for Wallet Kit Service
• Set Configuration Values
• Pass Models and Pass Instances
• Compile the Demo as a Maven Project
• Example Methods
  1. Example Methods for Pass Models
  2. Example Methods for Pass Instances
  3. Generate JWE
  4. Signature Validation
• Question or issues
• License

Introduction

HUAWEI Wallet Kit Server Demo is sample code showing how to use the HUAWEI-Wallet-Server interfaces. The HUAWEI-Wallet-Server interfaces contain REST APIs for six types of passes (Loyalty Card, Offer, Gift Card, Boarding Pass, Transit Pass, and Event Ticket). You can use these REST APIs to implement operations such as adding, querying, or updating passes.

Before you use this Demo, you should have a HUAWEI developer account, and have already created an app to implement the HUAWEI wallet service. This "app" doesn’t have to be a program that will be actually installed on cell phones. It means an application of using the HUAWEI wallet service. So please create an app on the HUAWEI AppGallery Connect (AGC) website even if you are not going to develop mobile apps. If you haven't, please refer to Register a HUAWEI ID and Create an App.

Supported Environments

Maven and Oracle Java 1.8.0.211 or higher are required to run the Demo project.

Apply for Wallet Kit Service

Follow Enabling Services to apply for wallet service.

Please notice that you will set a "Service ID" in your application. The "Service ID" here is "passTypeIdentifier" you will use in the Demo code. You will set the "passTypeIdentifier" later.

You will generate a pair of RSA keys during this process. Store them properly, and you will use the private key to sign JWEs (see Generate JWE). The wallet server will use the public key you upload to verify signatures.

After you finished applying for a service ID, you can begin to test the corresponding pass. Apply for other service IDs if you want to test other passes.

Set Configuration Values

Before running the Demo project, you need to set the following configuration values in the "src\test\resources\release.config.properties" file: "gw.appid", "gw.appid.secret", "gw.tokenUrl", "walletServerBaseUrl", "servicePrivateKey", and "walletWebsiteBaseUrl"

Set "gw.appid" and "gw.appid.secret":

To implement the Wallet Kit to an app, "gw.appid" and "gw.appid.secret" are this app's "App ID" and "App secret". Go to the AGC website, login to your account, click "My apps" and then click the app you want to operate. Then you can find its App ID and App secret.

Set "gw.tokenUrl"

Set gw.tokenUrl = https://oauth-login.cloud.huawei.com/oauth2/v3/token. This is the address to obtain a REST API authentication token.

Set "walletServerBaseUrl":

"walletServerBaseUrl" is a common section of the REST APIs’ http requests. Its format is: walletServerBaseUrl = https://{walletkit_server_url}/hmspass. Set {walletkit_server_url} with one of the values in the following table according to your account’s location.

location	walletkit_server_url
Chinese Mainland	wallet-passentrust-drcn.cloud.huawei.com.cn
Asia	wallet-passentrust-dra.cloud.huawei.asia
Europe	wallet-passentrust-dre.cloud.huawei.eu
Latin America	wallet-passentrust-dra.cloud.huawei.lat
Russia	wallet-passentrust-drru.cloud.huawei.ru

Set "servicePrivateKety"

You generated a pair of RSA private key and public key while you applying for Wallet Kit service. Set the private key here and you will use it to sign JWEs.

Set "walletWebsiteBaseUrl"

"walletWebsiteBaseUrl" is the address of HUAWEI-Wallet-H5 server. Its format is: walletWebsiteBaseUrl=https://{walletkit_website_url}/walletkit/consumer/pass/save. Set {walletkit_website_url} with one of the values in the following table according to your account’s location.

location	walletkit_website_url
Chinese Mainland	walletpass-drcn.cloud.huawei.com
Asia	walletpass-dra.cloud.huawei.com
Europe	walletpass-dre.cloud.huawei.com
Latin America	walletpass-dra.cloud.huawei.com
Russia	walletpass-drru.cloud.huawei.com

Pass Models and Pass Instances

A pass model is a style of pass instances. Instances belonging to the same model share some common parameters. For example, a boarding pass model contains information about departure time and arrival time, while a boarding pass instance contains a passenger’s name, his seat, his boarding sequence, etc. Each pass instance belongs to a specific model. Hence, you should first create a model before creating instances and performing other operations.

All pass models and instances have the same data format, which is HwWalletObject. Refer to HwWalletObject Definition for more details.

Input parameters of models and instances are passed by JSON files in the Demo project. You can generate your own data by modifying the JSON files in the "src\test\resources\data" folder.

Remember to set the correct "passTypeIdentifier" in these input JSON files, which should be identical to your "Service ID" on the AGC website.

Compile the Demo as a Maven Project

After you set all the configurations values, compile the Demo as a Maven project. It may take a few minutes to deploy all dependencies. How long it takes depends on your settings files and your network environment.

Example Methods

Example Methods for Pass Models

1. Register a Pass Model

The HUAWEI wallet server provides REST APIs to create pass models. See Creating a Model. You can add a loyalty model to the server’s database by calling the "createLoyaltyModel" method, and create other types of models likewise. You should create a pass model first before calling any other methods.

2. Query a Pass Model

The HUAWEI wallet server provides REST APIs to query a pass model by its model ID. See Query a Model. You can query a loyalty model by calling the "getLoyaltyModel" method, and query other types of models likewise.

3. Query a List of Pass Models

If your app created multiple models of a pass type (e.g. a gold loyalty card model and a diamond loyalty card model), you can use these APIs to query a list of these models. See Query Models. You can query a list of loyalty models by calling the "getLoyaltyModelList" method, and query other types of models likewise.

4. Overwrite a Pass Model

The HUAWEI wallet server provides REST APIs to overwrite an entire pass model by its model ID. See Overwrite a Model. You can overwrite a loyalty model by calling the "fullUpdateLoyaltyModel" method, and overwrite other types of models likewise.

5. Update a Pass Model

The HUAWEI wallet server provides REST APIs to update part of a pass model by its model ID. See Update a Model. You can overwrite a loyalty model by calling the "partialUpdateLoyaltyModel" method, and update other types of models likewise.

6. Add Messages to a Pass Model

"messageList" is one of the attributes in a pass model, which is a list of messages. You can add messages to a loyalty model by calling the "addMessageToLoyaltyModel" method, and add to other types of models likewise. The "messageList" in a pass model has at most 10 messages. You cannot add more than 10 messages at a time. If the list’s size is already 10 and you keep adding messages, the oldest messages will be removed. See Add Messages to a Model.

Example Methods for Pass Instances

1. Add a Pass Instance

The HUAWEI wallet server provides REST APIs to add pass instances. See Add an Instance. You can add a loyalty instance to the server’s database by calling the "createLoyaltyInstance" method, and create other types of instances likewise. You should create a pass model first before creating instances belonging to it.

2. Query a Pass Instance

The HUAWEI wallet server provides REST APIs to query a pass instance by its instance ID. See Query an Instance. You can query a loyalty instance by calling the "getLoyaltyInstance" method, and query other types of instances likewise.

3. Overwrite a Pass Instance

The HUAWEI wallet server provides REST APIs to overwrite an entire pass instance by its instance ID. See Overwrite an Instance. You can overwrite a loyalty instance by calling the "fullUpdateLoyaltyInstance" method, and overwrite other types of instances likewise.

4. Update a Pass Instance

The HUAWEI wallet server provides REST APIs to update part of a pass instance by its instance ID. See Update an Instance. You can overwrite a loyalty instance by calling the "partialUpdateLoyaltyInstance" method, and update other types of instances likewise.

5. Add Messages to a Pass Instance

"messageList" can also be an attribute of a pass instance. You can add messages to a loyalty instance by calling the "addMessageToLoyaltyInstance" method, and add to other types of instances likewise. The "messageList" in a pass instance has at most 10 messages. You cannot add more than 10 messages at a time. If the list’s size is already10 and you keep adding messages, the oldest messages will be removed. See Add Messages to an Instance.

6. Link/unlink Offer Instances to/from a Loyalty Instance

This API is only provided for loyalty instances. See Link/Unlink an Offer. You can link/unlink offer instances to/from a loyalty instance by calling the "updateLinkedOffersToLoyaltyInstance" method. You should make sure the offers you want to add already exist before you use this API. Otherwise, the client cannot show an offer that is not in the server’s database. These offer instances can belong to other apps or other developers.

Generate JWE

Developers need to generate JSON Web Encryption (JWE) strings and send them to the HUAWEI-Wallet-H5 server) to bind a pass to a HUAWEI Wallet user.
There are two ways to generate JWEs. The first way: you can generate a JWE string with complete information of a pass instance and send it to the HUAWEI-Wallet-H5 server. In this way, you don’t need to call add-pass-instance methods. The second way: you can add a pass instance to the wallet server first, and then generate a thin JWE (with only instance ID information) and send it to the HUAWEI-Wallet-H5 server to bind the pass instance to a user.
The demo has example methods for generating JWEs and thin JWEs. Please refer to the demo and implement the code in your own system. Please also refer to Integrate Add to HUAWEI Wallet Button (section "Generating a JWE and Sending It to the Huawei Server" and section "Generating a Thin JWE and Sending It to the Huawei Server") for more details.

Signature Validation

If you provide a Callback URL or an NFC Callback URL during applying for Wallet Kit service, you will receive callback notification requests from the HUAWEI wallet server. You should verify the signature in the request header with HUAWEI's fixed signature public key. The test case "verifySignature" gives an example of verifying a signature. Refer to Callback APIs for more details.

Question or issues

If you want to evaluate more about HMS Core, r/HMSCore on Reddit is for you to keep up with the latest news about HMS Core, and to exchange insights with other developers.

If you have questions about how to use HMS samples, try the following options:

• Stack Overflow is the best place for any programming questions. Be sure to tag your question with huawei-mobile-services.
• Huawei Developer Forum HMS Core Module is great for general questions, or seeking recommendations and opinions.

If you run into a bug in our samples, please submit an issue to the Repository. Even better you can submit a Pull Request with a fix.

License

HUAWEI Wallet Kit Server Demo is licensed under the Apache License, version 2.0.