We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HUAWEI HMS Core

HMS Core 4.0
输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K

Documents from this version have been archived, and will not continue to be maintained. Please use the latest version.

HMS Core GuidesWallet KitApp DevelopmentDevelopment ScenarioGenerating and Pushing a JWE to the Huawei ServerAdding a Button for Claiming Passes on a Web Page

Adding a Button for Claiming Passes on a Web Page

Last updated: 2020-11-04 01:14
Content overview

You can push a template from your server to the Huawei server and add the Add to HUAWEI Wallet button to your web page.

After a user taps the button, a JWT containing the user's personalized information is sent to the Huawei server. The Huawei server associates the corresponding template, generates a pass, and associates the pass with the user's HUAWEI ID. Then the user can view the pass in HUAWEI Wallet.

The procedure is as follows:

  • Define a template and push it to the Huawei server through the REST API.

  • Add the Add to HUAWEI Wallet button to your web page.

  • Generate an instance and send it as a JWT to the Huawei server when a user taps the button.

1 Define a Template

Define a template of common merchant information about all passes. The following uses loyalty cards of a merchant as an example.

Collapse
Word wrap
Dark theme
Copy code
  1. HwWalletObject hwWalletObject = new HwWalletObject(); 
  2. hwWalletObject.setPassVersion("10.0"); 
  4. hwWalletObject.setOrganizationPassId("1231");
  6. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // Template ID, which is unique. 
  7. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // Service ID specified during service registration. 
  8. hwWalletObject.setWebServiceURL("https://www.xxx.com"); // Callback URL used when a user claims a loyalty card. 
  9. Fields fields = new Fields(); 
  10. fields.setCountryCode("CN"); 
  11. // Geofence information. 
  12. List<Location> locationList = new ArrayList<>(); 
  13. Location location = new Location(); 
  14. location.setLongitude("11x.0679603815"); 
  15. location.setLatitude("2x.6592051284"); 
  16. locationList.add(location); 
  17. fields.setLocationList(locationList); 
  18. List<CommonFields> commonFields = new ArrayList<>(); 
  19. CommonFields cardImage = new CommonFields(); 
  20. cardImage.setKey("backgroundImage"); 
  21. cardImage.setValue("https://www.xxx.com/.../cardImage.png"); // URI of the background image of a loyalty card issued by the merchant. 
  22. commonFields.add(cardImage); 
  23. CommonFields logo = new CommonFields(); 
  24. logo.setKey("logo"); 
  25. logo.setValue("https://www.xxx.com/.../logo.png"); // URI of the merchant's logo. 
  26. commonFields.add(logo); 
  27. // Merchant name. The following provides sample code for defining merchant names in multiple languages. You can specify a random string here, for example, merchantNameI18N, for obtaining the merchant name in the corresponding language from the value of Localized. 
  28. CommonFields merchantName = new CommonFields(); 
  29. merchantName.setKey("merchantName"); 
  30. merchantName.setValue("Some merchant name"); 
  31. merchantName.setLocalizedValue("merchantNameI18N"); 
  32. commonFields.add(merchantName); 
  33. // Loyalty card name. 
  34. CommonFields name = new CommonFields(); 
  35. name.setKey("name"); 
  36. name.setValue("Loyalty Card"); 
  37. commonFields.add(name); 
  38. fields.setCommonFields(commonFields); 
  39. List<AppendFields> appendFields = new ArrayList<>(); 
  40. AppendFields nearbyLocations = new AppendFields(); 
  41. nearbyLocations.setKey("nearbyLocations"); 
  42. nearbyLocations.setValue("https://www.xxx.com/.../nearbyLocation.html"); // URI of the page listing nearby stores of the merchant. 
  43. nearbyLocations.setLabel("Nearby Locations"); 
  44. appendFields.add(nearbyLocations); 
  45. AppendFields website = new AppendFields(); 
  46. website.setKey("website"); 
  47. website.setValue("https://www.xxx.com/.../merchantMainPage.html"); // URI of the merchant's main page. 
  48. website.setLabel("Website"); 
  49. appendFields.add(website); 
  50. AppendFields hotline = new AppendFields(); 
  51. hotline.setKey("hotline"); 
  52. hotline.setValue("400820XXXX"); // Merchant's hotline. 
  53. hotline.setLabel("Hotline"); 
  54. appendFields.add(hotline); 
  55. fields.setAppendFields(appendFields); 
  56. List<ValueObject> imageList = new ArrayList<>(); 
  57. ValueObject imagePic = new ValueObject(); 
  58. imagePic.setValue("https://www.xxx.com/.../banner.png"); // Promotion image. 
  59. imageList.add(imagePic); 
  60. fields.setImageList(imageList); 
  61. List<Localized> localizedList = new ArrayList<>(); 
  62. // Merchant name in Chinese, which can be obtained based on the previously specified string merchantNameI18N. 
  63. Localized merchantNameChinese = new Localized(); 
  64. merchantNameChinese.setKey("merchantNameI18N"); 
  65. merchantNameChinese.setLanguage("zh-CN"); 
  66. merchantNameChinese.setValue("Merchant name in Chinese"); 
  67. localizedList.add(merchantNameChinese); 
  68. // Merchant name in English, which can be obtained based on the previously specified string merchantNameI18N. 
  69. Localized merchantNameEnglish = new Localized(); 
  70. merchantNameEnglish.setKey("merchantNameI18N"); 
  71. merchantNameEnglish.setLanguage("en-GB"); 
  72. merchantNameEnglish.setValue("Merchant name in English"); 
  73. localizedList.add(merchantNameEnglish); 
  74. fields.setLocalized(localizedList); 
  75. hwWalletObject.setFields(fields);

Push the template to the Huawei server through the following REST API using POST:

Collapse
Word wrap
Dark theme
Copy code
  1. POST 
  2. https://{walletkit_server_url}/hmspass/v1/loyalty/model

Note: You need to replace {walletkit_server_url} in the preceding URL based on the region to which the server belongs. For privacy considerations, data of a region is kept within the region. It is recommended that you push the JWE to all of the following regions. For details, please refer to Wallet Server Address.

China

passentrust-drcn.wallet.hicloud.com

Russia

passentrust-drru.wallet.hicloud.com

Asia, Africa, and Latin America

passentrust-dra.wallet.hicloud.com

Europe

passentrust-dre.wallet.hicloud.com

The code for pushing hwWalletObject to the Huawei server is as follows:

Collapse
Word wrap
Dark theme
Copy code
  1. boolean validateClass = HwWalletObjectUtil.validateHwWalletObjectClass(hwWalletObject); 
  2. if (validateClass) { 
  3.   // post hwWalletObject to Huawei server 
  4.   WalletBuildService walletBuildService = new WalletBuildServiceImpl(); 
  5.   HwWalletObject loyaltyClass = walletBuildService.postHwWalletClassToWalletServer("loyalty/model", hwWalletObject); 
  6. }

2 Adding the Add to HUAWEI Wallet Button

Add the following script to your web page code to display the Add to HUAWEI Wallet button:

Collapse
Word wrap
Dark theme
Copy code
  1. <script src="savetohuaweipay.min.js"></script>

Download the script: savetohuaweipay.zip

Add the following content to your web page code, which is used to transfer a JWT as a parameter when a user taps the button:

Collapse
Word wrap
Dark theme
Copy code
  1. <hw-savetohuaweipay jwt="{jwt_content}" theme="light"></hw-savetohuaweipay>

The Add to HUAWEI Wallet button is displayed on the web page.

3 Generating a JWT and Sending It to the Huawei Server

Generate an instance of a user's personalized information when the user taps the Add to HUAWEI Wallet button.

Collapse
Word wrap
Dark theme
Copy code
  1. HwWalletObject hwWalletObject = new HwWalletObject(); 
  2. hwWalletObject.setSerialNumber("854687156"); // Instance ID unique to the associated template. 
  4. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // Template ID, which is unique.
  6. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // Service ID specified during service registration.
  8. hwWalletObject.setOrganizationPassId("1231")
  12. Fields fields = new Fields(); 
  13. // Loyalty card status, which cannot be specified for an expired loyalty card. 
  14. Status status = new Status(); 
  15. status.setState("active"); 
  16. status.setEffectTime("2019-11-11T00:00:00.000Z"); 
  17. status.setExpireTime("2029-11-10T23:59:59.999Z"); 
  18. fields.setStatus(status); 
  19. // Template IDs and instance IDs of coupons associated with the loyalty card. 
  20. List<LinkedPassId> relatedPassIds = new ArrayList<>(); 
  21. LinkedPassId linkedCoupon = new LinkedPassId(); 
  22. linkedCoupon.setTypeId("Coupon template id"); 
  23. linkedCoupon.setId("Coupon instance id"); 
  24. relatedPassIds.add(linkedCoupon); 
  25. fields.setRelatedPassIds(relatedPassIds); 
  26. // Barcode or QR code. 
  27. BarCode barCode = new BarCode(); 
  28. barCode.setText("Refresh every ten minutes"); 
  29. barCode.setType("codabar"); // codabar or qrCode 
  30. barCode.setValue("829383819844342342"); 
  31. fields.setBarCode(barCode); 
  32. List<CommonFields> commonFields = new ArrayList<>(); 
  33. // Member name. The following provides sample code for defining member names in multiple languages. 
  34. CommonFields memberName = new CommonFields(); 
  35. memberName.setKey("memberName"); 
  36. memberName.setValue("Member name"); 
  37. memberName.setLocalizedValue("memberName18N"); 
  38. commonFields.add(memberName); 
  39. // Loyalty card number. 
  40. CommonFields cardNumber = new CommonFields(); 
  41. cardNumber.setKey("cardNumber"); 
  42. cardNumber.setValue("4527809736"); 
  43. commonFields.add(cardNumber); 
  44. fields.setCommonFields(commonFields); 
  45. List<AppendFields> appendFields = new ArrayList<>(); 
  46. // Loyalty points. 
  47. AppendFields points = new AppendFields(); 
  48. points.setKey("points"); 
  49. points.setLabel("Points"); 
  50. points.setValue("1299"); 
  51. appendFields.add(points); 
  52. AppendFields balance = new AppendFields(); 
  53. balance.setKey("balance"); 
  54. balance.setValue("$19"); 
  55. balance.setLabel("Balance"); 
  56. appendFields.add(balance); 
  57. // Loyalty level. 
  58. AppendFields level = new AppendFields(); 
  59. rewardsLevel.setKey("level"); 
  60. level.setValue("Gloden"); 
  61. level.setLabel("Level"); 
  62. appendFields.add(level); 
  63. fields.setAppendFields(appendFields); 
  64. List<Localized> localizedList = new ArrayList<>(); 
  65. // Member name in Chinese. 
  66. Localized memberNameChinese = new Localized(); 
  67. memberNameChinese.setKey("memberName18N"); 
  68. memberNameChinese.setLanguage("zh-CN"); 
  69. memberNameChinese.setValue("Member name in Chinese"); 
  70. localizedList.add(memberNameChinese); 
  71. // Member name in English. 
  72. Localized memberNameEnglish = new Localized(); 
  73. memberNameEnglish.setKey("memberName18N"); 
  74. memberNameEnglish.setLanguage("en-GB"); 
  75. memberNameEnglish.setValue("Member name in English"); 
  76. localizedList.add(memberNameEnglish); 
  77. fields.setLocalized(localizedList); 
  78. hwWalletObject.setFields(fields);

Convert the generated instance to a JWE, which consists of five parts:

  • Part 1: header

  • Part 2: RSA-encrypted session key, which is generated using the RSA public key provided by Huawei server

  • Part 3: initialization vector (IV), a string of 12 bytes

  • Part 4: HwWalletObject, which is encrypted and compressed using the AES-GCM method based on the session key (serving as the symmetric key) and the IV (serving as the encryption vector)

  • Part 5: signature, which is generated by signing the previous four parts using your JWE private key, which is obtained from HUAWEI Developers through an application process

Each part is encoded using Base64.

Note: It is recommended that you change the session key and IV each time.

Collapse
Word wrap
Dark theme
Copy code
  1. // The app ID registered with AppGallery Connect. 
  2. String appId = "Replace with your app ID"; 
  3. // Create a loyalty card instance and link it to a user. 
  4. String newInstanceJson = CommonUtil.readWalletObject("LoyaltyInstance.json"); 
  5. JSONObject newInstanceJsonObject = JSONObject.parseObject(newInstanceJson); 
  6. newInstanceJsonObject.put("iss", appId); 
  7. // Generate a session key to encrypt payload data. A session key is a string of random hex numbers. 
  8. String sessionKey = RandomUtils.generateSecureRandomFactor(16); 
  9. System.out.println("sessionKey: " + sessionKey); 
  10. // The public key provided by Huawei, which is used to encrypt the session key. 
  11. String sessionKeyPublicKey = 
  12.           "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAgBJB4usbO33Xg5vhJqfHJsMZj44f7rxpjRuPhGy37bUBjSLXN+dS6HpxnZwSVJCtmiydjl3Inq3Mzu4SCGxfb9RIjqRRfHA7ab5p3JnJVQfTEHMHy8XcABl6EPYIJMh26kztPOKU2Mkn6yhRaCurhVUD3n9bD8omiNrR4rg442AJlNamA7vgKs65AoqBuU4NBkGHg0VWWpEHCUx/xyX6hIwqc1aD7P2f62ZHsKpNZBOek/riWhaVx3dTAa9ZS+Av3IGLOZiplhYIow9f8dlWyqs8nff9FZoJO03QhXLvOORT+lPAkW6gFzaoeMaGb40HakkZn3uvlAEKrKrtR0rZEok+N1hnboaAu8oaKK0rF1W6iNrXcFrO0rcrCsFTVF8qCa/1dFmIXwUd2M6cUzT9W0YkNyb6ZBbwEhjwBL4DNW4JfeF2Dzj0eZYlSuYV7e7e1e+XEO8lwPLAiy4bEFAWCaeuDVIhbIoBaU6xHNVQoyzct98gaOYxE4mVDqAUVmhfAgMBAAE="; 
  13. // The private key you obtained during service registration with AppGallery Connect.  
  14. String jweSignPrivateKey = "Replace with your private key."; 
  15. // Generate a JWE. 
  16. String jweStrByInstanceIds = JweUtil.generateJwe(sessionKey, jweSignPrivateKey,newInstanceJsonObject.toJSONString(), sessionKeyPublicKey);

Note: The JWE must be encoded using URLEncoder.encode(jweStrByInstanceIds, StandardCharsets.UTF_8.toString()).

The link carrying the JWE can contain a maximum of 2000 characters. The following is a sample HTTPS link:

Collapse
Word wrap
Dark theme
Copy code
  1. https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={jwt_content}

Note: The {walletkit_website_url} variable in the preceding request should be selected based on the region where the wallet website is located:

China

walletpass-drcn.cloud.huawei.com

Russia

walletpass-drru.cloud.huawei.com

Asia, Africa, and Latin America

walletpass-dra.cloud.huawei.com

Europe

walletpass-dre.cloud.huawei.com


Overview
Adding a Deep Link for Claiming Passes in an SMS Message or Email
This page may contain third-party content. For details, click here.
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.