• Introducing XDA Computing: Discussion zones for Hardware, Software, and more!    Check it out!
  • Fill out your device list and let everyone know which phones you have!    Edit Your Device Inventory

[HMS Core Tips & Tricks] Wallet Kit Integration Procedure and Precautions

Search This thread

John Wo

Official Huawei Rep
Apr 28, 2020
More information like this, you can visit HUAWEI Developer Forum

In this article, I would like to record the pits for integrating HUAWEI Wallet Kit I stepped on during the integration, so that you can integrate the Wallet Kit more quickly.

Link to the development guide:


Integration Procedure

The Wallet Kit integration process consists of the following five steps:

1. Open the wallet service on the AGC

2. Generating Public and Private Keys

3. Adding a Pass Type on the AGC

4. Running the Demo of the Server

5. Running the Demo of the Client

6. View card adding status

Step 1.2.3 can be performed under the guidance of the development guide.


You are advised to run the demo provided in the development guide in section 4.5 to avoid many detours.

Note that this function is invoked when the demo is invoked. (The demo is normal, but you need to pay attention to some points when using the demo.)

Download the demo from these

Server demo(huawei-wallet-server-windows-jwe-demo.zip):


Android demo:


Note: The sequence of steps in section 4.5 cannot be reversed. The reason is described in the following sections.


1. Pass structure

A card is made up of two parts.

Merchant information:

This is called model, which contains fixed information about the same type of vouchers, such as the card base, logo, merchant name, and card type.

Special information about a single pass:

This is called instance, such as membership card numbers, membership points, membership levels, and coupon status.


2. Sequence of generating templates and objects

In the Wallet Kit, you need to generate a model and then an instance. Only the server has the interface for generating a model. Therefore, the SDK on the device or an interface on the cloud can be invoked to generate a card instance only after the interface for generating a model is invoked on the server.

This is why the order of steps 4.5 cannot be reversed, as described in the integration steps section.

3. Integration server demo

The following describes the five points of the server:

(1) Dependency for downloading each package in the Maven repository

(2) Modifying the Configuration File in the Demo

(3) Run the demo and move the JSON file to the specified location.

(4) Generate JWE character strings.

(5) Binding pass by URL

(1) Dependency for downloading packages in the Maven repository

After the downloaded server demo is opened in the IDEA, some Maven repositories cannot be downloaded. As a result, some files of the project report errors.


You can wait for the IDEA to download it, or manually download it from the Maven official website: https://mvnrepository.com/

Search for the corresponding groupId on the Maven official website. The search list of each artifactId is displayed. Select the required point to download the version of each artifactId.




After the download is complete, you can save the downloaded Maven repository to the local Maven repository. To view the local Maven repository, choose File > SettingsBuild, Execution, Deployment > Build Tools > Mavens on the IDEA.



After the adding is complete, update the Maven repository.

(2) Modify the configuration file in the demo.

After the Maven repository is complete, you can modify the configuration in the demo.

Open the release.config.properties file in the test/resources directory.


appId and appId.secret are the appId and key of the corresponding app in the AGC. The third URL does not need to be changed. The value of walletServerBaseUrl needs to be changed. Check the region (China, Europe, Asia, Africa, and Russia) to which your developer account belongs. For details about the corresponding URL, see https://developer.huawei.com/consum...-V5/wallet-server-api-2-9-0000001050158382-V5, here, my developer account belongs to Europe. Therefore, change the URL to the URL of Europe. (If you forget the region to which your account belongs, you can try each URL when the demo reports an error.)



The screenshot after the modification is as follows:


(3) Run the demo and move the JSON file to the specified directory.

After the configuration is complete, copy the hmspass folder in the config directory, build the project, click Build-Build Progect. Then, copy the hmspass folder to the target/classes directory.


After that, you can run the demo. When you run the demo, you should mainly run the java files in the Test folder


Each type of passes corresponds to two Java files. The file whose name ends with ModelTest provides the examples of adding, modifying, and querying pass models. The file whose name ends with InstanceTest provides the examples of adding, modifying, and querying pass instances.

a. Generate a pass model

The following uses the member card (loyalty) as an example.

Open the HwLoyaltyModelTest file and create a model method named createLoyaltyModel().


The LoyaltyModel.json file is the file to be transferred to Huawei interfaces. Before running the method, you need to modify the file information. You can find the file in the target/classes/hmspass directory.


Modify the passTypeIdentifier and passStyleIdentifier fields. The passTypeIdentifier field is the service ID defined when we add card types on the AGC. The passStyleIdentifier field is the unique identifier of the model and is used when pass instances are created, field defined by the developer. The screenshot after the modification is as follows:


The following figure shows the console after createLoyaltyModel() is executed.

b. Generate a pass instance.

The following uses the member card (loyalty) as an example.

The procedure is similar to that for modifying a model. Open the HwLoyaltyInstanceTest file and view the LoyaltyInstance.json file in createLoyaltyInstance().


Change the values of passTypeIdentifier and passStyleIdentifier to the values generated in the previous step. The values of serialNumber and organizationPassId are unique identifiers of cards (in different application scenarios). Ensure that the values of the two fields are unique.

Then we run createLoyaltyInstance() to generate a pass instance.


(4) Generate a JWE character string

The generateThinJWEToBindUser() and generateJWEToAddPassAndBindUse() methods exist in the InstanceTest file of each pass.

generateThinJWEToBindUser(): Signs and encrypts the generated pass instance and generates a character string. -----The createLoyaltyInstance() method of (3).b does not need to be executed.

generateJWEToAddPassAndBindUse(): Signs and encrypts pass instances that are not generated, and generates corresponding character strings. ------The createLoyaltyInstance() method of (3).b does not need to be executed.

The two methods are similar. The following uses generateThinJWEToBindUser() as an example. The code is as follows:


appId indicates the app ID, and instanceIdListJson indicates the serialNumber set when the pass instance is generated. The code after modification is as follows:


Note: The LoyaltyInstance.json file in generateJWEToAddPassAndBindUse() is a pass instance that is not generated (the createLoyaltyInstance() method is not executed).

Then you need to change the value of jweSignPrivateKey to the private key of the public key configured on the AGC card.



The screenshot after the modification is as follows:


The following results are obtained:


A JWE string is generated after the serialNumber of a pass is encrypted and signed. Generally, the JWE string is called a thin JWE.

(5) Bind pass by URL

Huawei provides an interface for binding pass through the URL. The format is https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={jwt_content}.

{jwt_content} is the URL-encoded JWE String obtained in the previous step. The URL-encoded code is as follows:

URLEncoder.encode(jwtStrInstanceIds, StandardCharsets.UTF_8.toString())

{walletkit_website_url}: URL of the area where the developer is located. The mapping is as follows:


For example, the URL of the thin JWE in Europe is in the following format:


After you enter the URL in the browser, the Huawei ID login page is displayed. Log in to a Huawei ID that is in the same region as the developer account.


After the login is successful, the card binding result is displayed.




The possible cause of binding fail is that the pass has been bound by another user or the region of the Huawei ID is different from that of the developer account.

4. Integrate the client demo.

(1) Changing the Key

(2) Enter the pass information and add passes.

(3) Confirm and log in with your Huawei ID.

(4) Bind passes

(5) Open your wallet and check your passes.

(1) Changing the Key

After opening the HmsWalletClientDemo project using Android Studio, you need to modify the PRIVATE_KEY_EUROPE_DEBUG file in the Constant.java file in the com.huawei.hms.wallet package.


Change the value of this field to the content in the private.txt file that is generated when the public key and private key are generated in step 1.


(2) Enter the pass information and add passes.

a. Select European test environment

b. Click ClickSaveLoyaltyCard


For the full content, you can visit HUAWEI Developer Forum