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 in Your App

Adding a Button for Claiming Passes in Your App

Last updated: 2020-05-20 06:49
Content overview

You can add a button to your app. When a user taps the button, a WebView page is displayed, and your server sends a JWE to the Huawei server through an intent to obtain and display the pass claiming result.

The procedure is as follows:

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

  • 2. Add a button to your app.

  • 3. Generate an instance and send it as a JWE 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.setOrganizationName("xxx");
  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 a button to your app. A tap on the button will start an activity via the ACTION_VIEW intent. You can add either of the following URIs to the button:

Collapse
Word wrap
Dark theme
Copy code
  1. hms://www.huawei.com/payapp/{jwt_content}

Or

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

Note: The former URI only applies to mobile phones with HMS Core (APK) installed. When the button is tapped, a page specified by HMS Core (APK) will be displayed, guiding the user to claim the card. The latter URI does not have such a restriction. It allows the user to claim the card by using a browser or the HUAWEI Wallet app that is installed on the user device.

3 Generating a JWT and Sending It to the Huawei Server

Generate an instance of a user's personalized information when a 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(relatedPassIdss); 
  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 accountName = new CommonFields(); 
  35. accountName.setKey("accountName"); 
  36. accountName.setValue("Member name"); 
  37. accountName.setLocalizedValue("accountName18N"); 
  38. commonFields.add(accountName); 
  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. level.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 accountNameChinese = new Localized(); 
  67. accountNameChinese.setKey("accountName18N"); 
  68. accountNameChinese.setLanguage("zh-CN"); 
  69. accountNameChinese.setValue("Member name in Chinese"); 
  70. localizedList.add(accountNameChinese); 
  71. // Member name in English. 
  72. Localized accountNameEnglish = new Localized(); 
  73. accountNameEnglish.setKey("accountName18N"); 
  74. accountNameEnglish.setLanguage("en-GB"); 
  75. accountNameEnglish.setValue("Member name in English"); 
  76. localizedList.add(accountNameEnglish); 
  77. fields.setImageList(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 Base64-encoded.

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

Note: Classes CommonUtil, RandomUtils, and JweUtil are referenced but not implemented in the following code. For their definitions, please refer to Server Sample Code.

Collapse
Word wrap
Dark theme
Copy code
  1. // The app ID registered in 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 application in AppGallery Connect.  
  14. String jweSignPrivateKey = "Replace with your private key."; 
  15. // Generate a JWE. 
  16. String jweStrByInstanceIds = JweUtil.generateJwe(sessionKey, jweSignPrivateKey,newInstanceJsonObject.toJSONString(), sessionKeyPublicKey);

Send the encoded JWE to the Huawei server through an intent.

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

Collapse
Word wrap
Dark theme
Copy code
  1. Intent intent = new Intent(Intent.ACTION_VIEW); 
  2. intent.setData(Uri.parse("hms://www.huawei.com/payapp/{" + jwe_content + "}")); 
  3. try { 
  4.     startActivityForResult(intent, requestCode) 
  5. } catch (ActivityNotFoundException e) { 
  6. ... 
  7. } 
  8. Or 
  9. Intent intent = new Intent(Intent.ACTION_VIEW); 
  10. intent.setData(Uri.parse("https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={" + jwe_content + "}")); 
  11. try { 
  12.     startActivityForResult(intent, requestCode) 
  13. } catch (ActivityNotFoundException e) { 
  14. ... 
  15. }


Adding a Deep Link for Claiming Passes in an SMS Message or Email
Integrating HMS Core Wallet SDK
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.