Developer


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.

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.

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; 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:
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.

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:

  • 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

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":[]
}

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...ddm5hMPkADY4t4K","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.

If Google FCM service was unavailable to for any reason, the response will look like the one below:


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

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 tokens, max=xxx

Where xxx is currently set to 1000 as limited by Google FCM.

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 and Importing Passes

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.

This method using intents only works 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="" onclick="loadInstallWallet(passURL);">

function loadInstallWallet(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";
}

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.

Wallet English Badge