Create passes on Android using the Google Wallet API

1. Introduction

Overview

The Google Wallet API allows you to engage with users through various types of passes: loyalty cards, offers, gift cards, event tickets, transit tickets, boarding passes, and more. Each pass type, or pass class, comes with use-case specific fields and features to enhance the user experience.

However, these might not fit every use case. To create a more customized experience, you can use the generic pass type. Here are some example use cases for the generic pass type:

  • Parking passes
  • Library membership cards
  • Stored value vouchers
  • Gym membership cards
  • Reservations

You can use generic passes for any use case that can be presented with:

  • Up to three rows of information
  • (Optional) Barcode graphic
  • (Optional) Details section

An Android-powered device demonstrating the Add to Google Wallet provisioning flow

For more information on the Google Wallet API, or adding an Add to Google Wallet button to an Android application, please see the Google Wallet developer documentation.

Pass classes and objects

The Google Wallet API exposes methods to create the following:

Type

Description

Pass class

A template for an individual pass object. It contains information common to all pass objects that belong to this class.

Pass object

An instance of a pass class that is unique to a user ID.

About this codelab

In this codelab, you will complete the following tasks.

  1. Create a new issuer account in demo mode
  2. Create a service account for issuing passes
  3. Create a new Generic pass class
  4. Create a new pass object
  5. Create an Add to Google Wallet button to save a pass
  6. Display the button in your Android app
  7. Handle the pass save result

Prerequisites

Objectives

After completing this codelab, you will be able to do the following:

  • Add the Google Wallet SDK to your Android app
  • Check if the Google Wallet API is available on an Android-powered device
  • Create an Add to Google Wallet button

Support

If you are stuck at any point in the codelab, the google-pay/wallet-android-codelab GitHub repository contains a complete solution for reference.

2. Setup

In this step, you will create an Issuer account in demo mode. This will allow you to create pass classes and objects that can be added to user wallets. Next, you will create a Google Cloud project and service account. These will be used to programmatically create pass classes and objects in the same manner as a backend server. Last, you will authorize the Google Cloud service account to manage passes in your Google Wallet issuer account.

Sign up for a Google Wallet API issuer account

An Issuer account is necessary to create and distribute passes for Google Wallet. You can sign up using the Google Pay & Wallet Console. Initially, you will have access to create passes in demo mode. This means that only specific test users will be able to add passes you create. Test users can be managed in the Google Pay & Wallet Console.

For more information on demo mode, see the Generic pass prerequisites.

  1. Open the Google Pay & Wallet Console
  2. Follow the on-screen instructions to create an Issuer account
  3. Select Google Wallet API
  4. Confirm you understand the terms of service and privacy policy
  5. Copy the Issuer ID value to a text editor or other location
  6. Under the Manage tab, select Set up test accounts
  7. Add any email addresses you will use in this codelab

Enable the Google Wallet API

  1. Sign into the Google Cloud console
  2. If you don't already have a Google Cloud project, create one now (see Creating and managing projects for more information)
  3. Enable the Google Wallet API (also referred to as Google Pay for Passes API) for your project

Create a service account and key

A service account and a service account key are necessary to call the Google Wallet API. The service account is the identity that calls the Google Wallet API. The service account key contains a private key that identifies your application as the service account. This key is sensitive, so keep it confidential.

Create a service account

  1. In the Google Cloud console, open Service Accounts
  2. Enter a name, ID, and description for your service account
  3. Select CREATE AND CONTINUE
  4. Select DONE

Create a service account key

  1. Select your service account
  2. Select the KEYS menu
  3. Select ADD KEY, then Create new key
  4. Select the JSON key type
  5. Select CREATE

You will be prompted to save the key file to your local workstation. Make sure to remember its location.

Set the GOOGLE_APPLICATION_CREDENTIALS environment variable

The GOOGLE_APPLICATION_CREDENTIALS environment variable is used by Google SDKs to authenticate as a service account and access different APIs for a Google Cloud project.

  1. Follow the instructions in the Google Cloud Service account keys documentation to set the GOOGLE_APPLICATION_CREDENTIALS environment variable
  2. Verify the environment variable is set in a new terminal (MacOS/Linux) or command-line (Windows) session (you may need to start a new session if you have one open already)
    echo $GOOGLE_APPLICATION_CREDENTIALS

Authorize the service account

Lastly, you will need to authorize the service account to manage Google Wallet passes.

  1. Open the Google Pay & Wallet Console
  2. Select Users
  3. Select Invite a user
  4. Enter the email address of the service account (e.g. test-svc@myproject.iam.gserviceaccount.com)
  5. Select either Developer or Admin from the Access level drop-down menu
  6. Select Invite

3. Create a Generic pass class

In this step, you will create the base class for your pass. Any time a new pass is created for a user, it will inherit the properties defined in the pass class.

The pass class you will create during this codelab uses the flexibility of Generic passes to create an object that works as both an identity badge and challenge points tracker. When a pass object is created from this class, it will look like the following graphic.

Pass classes can be created directly in the Google Pay & Wallet Console or by using the Google Wallet API. In this codelab, you will create the Generic pass class using the API. This follows the process a private, backend server would use to create pass classes.

  1. Clone the google-pay/wallet-android-codelab GitHub repository to your local workstation
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. Open the cloned repository in your terminal or command-line prompt
  3. Navigate to the backend directory (these scripts imitate backend server actions)
    cd backend
  4. Install the Node.js dependencies
    npm install .
  5. In the backend directory, open generic_class.js
  6. Replace the value of