Leave a request
Wallet for Android API
Wallet app is open to service providers to send push notifications for passes issued via their service. This page describes various aspects of how to implement support for Wallet app in your service platform.
Wallet app is open to service providers to send push notifications for passes issued via their service. This page describes various aspects of how to implement support for Wallet app in your service platform.
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 WalletUnionPass. 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.
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 WalletUnionPass. 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.
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; Device 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:
So in HTTP request you may see the following header:
User-Agent: WalletUnion/1.0 Passbook/1.0 (Linux; U; Android 6.0; LG-535D)
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
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.
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.
API Endpoint and Request Format
- 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
{
"passTypeIdentifier":"pass.your.passtype.id",
"pushTokens":["eyKU4bqE...PMml5PJX848I","cA47ZTE...WJlHmId0Ib6uv",... ]
}
API Response
The server will return the following responses depending on the request:
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 413 on exceeding number of tokens in a single request
- HTTP 429 on exceeding rate limits
{
"status":"OK",
"unknown_push_tokens":[ ],
"expired_push_tokens":[ ]
}
Any tokens not associated with the given passTypeIdentifier by the server or if Google FCM service 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.
Starting May 15, 2024, any push token from a device that remains inactive for more than 270 days (i.e. 9 months) will be considered by Google as expired. FCM will then mark the token as invalid and reject any submissions for such tokens. From this date, Google Firebase will implement a purge of inactive push tokens, starting with a massive catch-up and then on an ongoing basis.
Any tokens, returned in the "expired_push_tokens" array, should be considered as deleted forever. These tokens should be remove 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 Google FCM service was unavailable to for any reason to accept requests, the response will look like the one below:
Starting May 15, 2024, any push token from a device that remains inactive for more than 270 days (i.e. 9 months) will be considered by Google as expired. FCM will then mark the token as invalid and reject any submissions for such tokens. From this date, Google Firebase will implement a purge of inactive push tokens, starting with a massive catch-up and then on an ongoing basis.
Any tokens, returned in the "expired_push_tokens" array, should be considered as deleted forever. These tokens should be remove 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 Google FCM service was unavailable to for any reason to accept requests, 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 as failed. You can try sending them again later.
When there were too many tokens send in a single request, server returns HTTP 413:
When there were too many tokens send in a single request, server returns HTTP 413:
HTTP/1.1 413 Too many FCM tokens, max=xxx
Where xxx is currently set to 1000 as limited by Google FCM.
Staring June 20, 2024, number of device tokens in a single request to our service will be limited to 50. This is due to the migration from Legacy Google FCM to new Google FCM HTTP v1 which does not support sending push message to many devices in a single request.
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:
Staring June 20, 2024, number of device tokens in a single request to our service will be limited to 50. This is due to the migration from Legacy Google FCM to new Google FCM HTTP v1 which does not support sending push message to many devices in a single request.
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 app's page to install, and after installation the pass will be imported automatically.
It is also possible to launch Wallet from browser.
These methods using intents only work with Google Chrome browser.
An HTML and javascript snippet below demonstrate such technique.
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 app's page to install, and after installation the pass will be imported automatically.
It is also possible to launch Wallet from browser.
These methods using intents only work with Google Chrome browser.
An HTML and javascript snippet below demonstrate such technique.
<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>
function importInstallWallet(passurl) {
var uri = encodeURIComponent(passurl);
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet&referrer=" + uri;
window.location = "intent://import/" + uri + "#Intent;scheme=walletunion;package=com.walletunion.wallet;"
+ "S.browser_fallback_url=" + fallback +";end";
}
function launchWallet() {
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet;"
window.location = "intent://launch/#Intent;scheme=walletunion;package=com.walletunion.wallet;"
+ "S.browser_fallback_url=" + fallback +";end";
}
</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:
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.
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.
Download Wallet Union
