Developer

Скачать приложение

для разработчиков

прайс

СВЯЗАТЬСЯ

блог

updated 04 Nov 2024

Wallet for Android API

Wallet app is open to Apple pass service providers to send push notifications for passes issued via their respective services. This page describes various aspects of how to implement support for Wallet app in your service platform both for Android phones with Google Services and Huawei phones without Google services.

Registering a Device to Receive Push Notifications

Wallet app fully implements Apple's protocol to register a pass with service provider so push messages can be sent to the pass. All protocol commands, data types and options are supported as described in APPLE WALLET WEB SERVICE REFERENCE

To assist you as a Service Provider in identifying a pass installed in the Wallet app and allowing push messages to be routed accordingly, the Wallet app replaces the original string ApplePass with corresponding string.

Authorization: WalletUnionPass aabbccddeeff11223344

Authorization: WalletUnionHMSPass aabbccddeeff11223344

This is the only change from the original Apple specification. So if your service already support Apple's protocol, you can easily implement support for the Wallet app.

Application Detection

In order to detect the Wallet app in your pages serving passes, a unique user agent is supplied every time when the app accesses web pages or scans a QR code to import a pass via URL link.

WalletUnion/1.0 Passbook/1.0 (Linux; U; Android <version>; <manufacturer> <model>)

WalletUnionHMS/1.0 Passbook/1.0 (Linux; U; Android <version>; <manufacturer> <model>)

Passbook/1.0 is added for compatibility with wider range of pass providers who do not yet detect requests from WalletUnion application natively.

So in HTTP request you may see the following header:

User-Agent: WalletUnion/1.0 Passbook/1.0 (Linux; U; Android 14; samsung SM-A556E)

User-Agent: WalletUnionHMS/1.0 Passbook/1.0 (Linux; U; Android 12; HUAWEI MAO-LX9)

There is also an additional HTTP header present to assist in serving a pass download page in appropriate language:

Accept-Language: zz;q=0.9

where zz is set to the current language of the device, running the application, for example en, ru, de etc.

Sending Push Notifications to the Wallet

API Endpoint and Request Format

In order to send request to services, use the following rules:

POST request to https://push.walletunion.com/send
HTTP header must contain Authorization: <API Key>
HTTP header must contain Content-type: application/json
Body of the request has required payload

Any Service Provider can send push messages to his passes installed in the Wallet app. In order to do that you as a Pass Provider need to use an API Key. To get an API Key please fill in the form. It is free for testing purposes. For commercial use appropriate license is required.

{ 
"passTypeIdentifier":"pass.your.passtype.id", 
"pushTokens":["eyKU4bqE...PMml5PJX848I","cA47ZTE...WJlHmId0Ib6uv",... ] ,
"hms":false // optional parameter
}

{ 
"passTypeIdentifier":"pass.your.passtype.id", 
"pushTokens":["eyKU4bqE...PMml5PJX848I","cA47ZTE...WJlHmId0Ib6uv",... ] ,
"hms":true // required parameter
}

API Response

The server will return the following responses depending on the request:

HTTP 200 and delivery results as json in response body on success
HTTP 400 on any malformed input data
HTTP 401 on authorization failure
HTTP 403 license is required to send push to the requested passtypeid. License can be obtained in personal cabinet
HTTP 413 on exceeding number of tokens in a single request
HTTP 429 on exceeding rate limits

In case of successful request (HTTP 200), the server will return json structure with an empty array of failed push tokens.

{
"status":"OK",
"unknown_push_tokens":[ ],
"expired_push_tokens":[ ]
}

Any tokens not associated with the given passTypeIdentifier by the Service, or if Google FCM or Huawei HMS services didn't accept some tokens for delivery for any reason, then the response will look like the one below:

{
"status":"ERROR",
"unknown_push_tokens":["ra9LE...ddm5hMP","bdH2OH...76jJuQ9YWn0T7k",...],
"expired_push_tokens":["f1G3hR..xeM5o","e41bJ2...gApIc","bdH2OH...76jJuQ9YWn0T7k"]
}

Presence of failed tokens in response means that either some of your passes are not installed on the device in question or user switched off the automatic update for a particular pass on the device. You should not attempt to send push to this device again util the pass registers both on the device and with your platform.

Any tokens, returned in the "expired_push_tokens" array, should be considered as deleted forever. These tokens should be removed from your database of active device tokens and you should not attempt to send pushes to them.
All tokens from "expired_push_tokens" array also present in "unknown_push_tokens" array for compatibility reasons.

If for any reason Google FCM or Huawei HMS services were unavailable to accept request to send push, the response will look like the one below:

{
"status":"FCM_FAILED",
"unknown_push_tokens":["ra9LE...ddm5hMP","bdH2OH...76jJuQ9YWn0T7k",...],
"expired_push_tokens":[ ]
}

In this situation all device tokens supplied in the request will be returned. You can try sending them again later.

When there were too many tokens send in a single request, server returns HTTP 413:

HTTP/1.1 413 Too many FCM pushTokens, max=50

HTTP/1.1 413 Too many HMS pushTokens, max=1000

The service doesn't currently limit number of pushes sent. But in some situations it may impose limits on the push requests rate. In this situation the response may look like this:

HTTP/1.1 429 Too many requests 
X-Rate-Limit-Limit: 3000 
X-Rate-Limit-Remaining: 100 
Retry-After: 30

Installing Wallet, Importing Passes, Launching Wallet

The Wallet app supports automatic installation if it is not yet installed on a device. At the same time it is possible to automatically import a pass upon installation completion. If the app is already installed, it can import a pass with a single click. If the app is not yet installed, tapping a button will redirect browser to Google Play or Huawei AppGallery app's page to install, and after installation the pass will be imported automatically.

An HTML and javascript snippet below demonstrate such technique.

This method will only work in Google Chrome browser!

<You can install your card by tapping the button "Add to Wallet"> 
<input type="submit" value="Add to Wallet" onclick="importInstallWallet(passURL);">

<You can launch Wallet app by tapping the button "Open Wallet"> 
<input type="submit" value="Open Wallet" onclick="launchWallet();">

<script>
/* !! Works only with Google Chrome browser !! */

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
* After installing and opening the app, pass will import automatically
*/
function importInstallWallet(passurl) { 
var uri = encodeURIComponent(passurl); 
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet&referrer=" + uri; 
var fullLink = "intent://import/" + uri + "#Intent;scheme=walletunion;package=com.walletunion.wallet;" 
+ "S.browser_fallback_url=" + fallback +";end"; 
window.location = fullLink;
}

/* 
* If Wallet is already installed, will automatically open Wallet
* If Wallet is not installed, will redirect user to the app's page
*/
function launchWallet() { 
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet;" 
var fullLink = "intent://launch/#Intent;scheme=walletunion;package=com.walletunion.wallet;" 
+ "S.browser_fallback_url=" + fallback +";end";
windows.location = fullLink;
}
</script>

This method will only work in Huawei built-in browser!

<You can install your card by tapping the button "Add to Wallet"> 
<input type="submit" value="Add to Wallet" onclick="importInstallWallet(passURL);">

<You can launch Wallet app by tapping the button "Open Wallet"> 
<input type="submit" value="Open Wallet" onclick="launchWallet();">

<script>
/* !! Works only with Huawei built-in browser !! */

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
* After installing and opening the app, pass will import automatically
*/
function importInstallWallet(passurl) { 
var uri = encodeURIComponent(passurl); 
var fallback = encodeURIComponent('https://appgallery.cloud.huawei.com/appDetail?pkgName=com.walletunion.wallet&referrer=' + passurl);
var fullLink = 'intent://import/' + uri + '#Intent;scheme=walletunion;package=com.walletunion.wallet;'
         + 'S.browser_fallback_url=' + fallback + ';end';
window.location = fullLink;
}

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
*/
function launchWallet() { 
var fallback = encodeURIComponent('https://appgallery.cloud.huawei.com/appDetail?pkgName=com.walletunion.wallet'); 
var fullLink = 'intent://launch/#Intent;scheme=walletunion;package=com.walletunion.wallet;'
+ 'S.browser_fallback_url=' + fallback +';end';
window.location = fullLink; 
}
</script>

Linking Android App to a Pass

The WalletUnion app has support for linking a pass to an Android app of your choice. If the app is not already installed on the device then the specified title text will be displayed on the back of the pass along with the app's icon from Google Play Store. By tapping on the icon an appropriate app installation page will be launched in Play Market. If the app is already installed on the device, tapping on the app's icon will launch the app.
To link a pass to an Android app please add the following top level json structure to the pass.json file of your pkpass package:

"associatedApps":[
{ 
"title":"My special app", "idGooglePlay":"com.mydomain.myapp"
}
]

Add to Wallet Badges

To indicate to your clients that your service supports Wallet app you can use web badges. They are available as SVG images and come in many languages. Please let us know if you require any particular language for your clients.

Скачать приложение
удобным для вас способом