Wallet Passes for Android API

This document describes how to add support for the Wallet Passes for Android app.

Registering a Device to Receive Push Notifications for a Pass

Wallet Passes for Android follows Apple’s Wallet Web Service API for registering a device for receiving push notifications as stated in the following document Apple Wallet Web Service Reference

Wallet Passes for Android uses a different Authorization header to ensure that the app is not erroneously detected as Apple Wallet App.
The Authorization header is the word AndroidPass (instead of ApplePass), followed by a space, followed by the pass’s authorization token as specified in the pass.

If your system already implements the Apple Wallet Web Service API you only need to take in account the special Authorization header for flagging the device as Android device.
The pushToken in the payload is similar to APN pushToken and you need to store it for later use with the push notification service.

User Agent

You can always detect the app by inspecting the user agent. Request from Wallet Passes for Android always contain the following user agent part: WalletPasses/<version> (Linux; U; Android ...)

Sending Push Notifications to the App

Getting started

The API is open for everybody. While it is not required to use an API key, we recommend to register yourself to get your personal API key (see rate limitation). You only need to have a Google Account to register for your personal API key.

Authentication

For authentication send your API Key in the HTTP Authorization header.

Authorization: <API Key>

The push notification request

Sending push notifications consists in sending a POST request with a specific payload to the following App endpoint with the content type "application/json".

POST https://walletpasses.appspot.com/api/v1/push

Payload [POST body content]:

{
    "passTypeIdentifier": "pass.io.walletpasses.android.sample",
    "pushTokens":[
      "59144e4701b04a3abd2bdc5fcb87ce2cbace8fcfc00a476ea7f19c18925d0af4" ,
      "8e372fdadea847febe0aacb44d3003496a5f24d5855e451eadfb9167e81c77c8"
    ]
}

Name	Type	Required	Description
passTypeIdentifier	String	Yes	The passTypeIdentifier eg: “pass.io.walletpasses.android.sample”
pushTokens	Array of Strings	Yes	Example: [“59144e4701b04a3abd2bdc5fcb87ce2cbace8fcfc00a476ea7f19c18925d0af4”, “8e372fdadea847febe0aacb44d3003496a5f24d5855e451eadfb9167e81c77c8”]

In case of success the server will respond with 200 OK. If you send a wrong request (e.g. missing passTypeIdentifier or pushTokens), the server will respond with 400 Bad Request

Rate Limitation

To protect our constrained resources, the public API is rate limited to 5 push notifications per second (maximum of 300 notifications per minute). All non-authenticated API calls count towards the public rate limit.
If you want to send more notifications, please create your personal API Key.

If you hit the rate limit with your request, the backend will reply with 429 Too Many Requests.
In such a response the server will send the header Retry-After, which contains the seconds to wait until the request can be retried.

Example:

HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Limit: 300
X-Rate-Limit-Remaining: 0
Retry-After: 8

If your request exceeds the overall quota (more than 300 push tokens for non-authenticated calls), the backend will reply with 413 Request Entity Too Large.
Consider splitting your request into smaller ones and retry.

If you need a higher quota that is available by default, contact [email protected].

Add to Wallet Passes Badges

We provide Add to Wallet Passes Badges you can use to indicate your support for the app.
The badges are available in different variants, resolution and languages.

The badges are available at the following URL: https://www.walletpasses.io/badges/badge_web_<variant>_<language><resolution>.png.

Example: The english retina resolution image is available at https://www.walletpasses.io/badges/[email protected].

Resolutions

We offer regular resolution (empty suffix), as well as @2x, @3x and @4x resolution images.

Languages

We currently only have english badges, if you need a translated badge, please contact [email protected].

Variants

Use the generic variant (white version) whenever possible. Use the black version of the badge only when you have it side by side to the Add to Wallet badge from Apple.

Installing App and automatically install a pass after installation

Automatic Method (recommended)

For your convenience we have built a small service that add your pass directly if the app is installed. If the import fails, a page with an instruction to download the app is displayed. The link to the Google Play store contains your pass URL so that the pass will be imported after installation. Use the following URL:

https://walletpass.io?u={url}

The following query parameters can be used:

Name	Type	Value	Description
u	String	eg: https://walletpasses.io/sample.pkpass	URL to the pkpass file to be installed. Ensure that you URL encode this URL
p	Optional String	eg: partnerid	Your Partner ID

Example: https://walletpass.io?u=https%3A%2F%2Fwalletpasses.io%2Fsample.pkpass

Manual Method

When serving a a Passbook (.pkpass) file to a client and if your client requires installation of the Wallet Passes for Android App you can redirect the user to the Google Play Store page and specify a pass to be downloaded and installed automatically after installation by passing the referrer parameter in the Google Play Store URL

GET https://play.google.com/store/apps/details?id=io.walletpasses.android&referrer={referrer}

Name	Type	Value	Description
referrer	String	eg: https://walletpasses.io/sample.pkpass	URL to the pkpass file to be installed when the user first opens Wallet Passes for Android App

The final URL would look like this: https://play.google.com/store/apps/details?id=io.walletpasses.android&referrer=https%3A%2F%2Fwalletpasses.io%2Fsample.pkpass

NOTE: To avoid breaking URL’s please encode the referrer URL using URL encoding.

Alliance Members & Partners

Alliance Members and partners are able to show their support by adding their logo inside the app when it is installed from their website.
In order for this to work, a different referrer value needs to be used.
Instead of https://walletpasses.io/sample.pkpass as referrer string, use utm_source=partner&utm_medium=referral&utm_campaign=<Partner ID>&pass=https://walletpasses.io/sample.pkpass.

The final URL would look like this: https://play.google.com/store/apps/details?id=io.walletpasses.android&referrer=utm_source%3Dpartner%26utm_medium%3Dreferral%26utm_campaign%3Dpartner-id%26pass%3Dhttps%253A%252F%252Fwalletpasses.io%252Fsample.pkpass

NOTE: To avoid breaking URL’s please first encode the pass URL and then whole referrer string using URL encoding.

Import and show pass

You can use the walletpasses:// scheme to import and show a passes. Different commands are provided as the URL host, and depending on the command, different parameters are provided as URL path segments.

NOTE: Ensure that you use these kind of URLs when you are sure that the app is installed or you have a proper fallback in place.
For more information on how to use intent links with android, see Android Intents with Chrome.

Import Pass

In order to import a pkpass file, you can use the import command. It requires a single parameter, the URL to the pkpass file.
This URL needs to be URL encoded.

Example: walletpasses://import/https%3A%2F%2Fwalletpasses.io%2Fsample.pkpass

Show Pass

If a pass was installed in the app, you can open with the show command. It requires two parameters, the pass type identifier and the serial number of the pass, encoded as two URL path segments.

Example: walletpasses://open/io.walletpasses.android.sample/123456789