Overview

Push provisioning allows issuers to add a payment card to Google Wallet directly, providing a seamless experience for users. This guide will take you through the steps to push provision a card to Google Wallet.

How it works:

When users tap the Google Pay push provisioning button, they'll see a screen that asks them for confirmation before provisioning their card. Once they confirm, users will need to accept their issuer’s terms of service before their card is added to Google Pay. They will see a confirmation screen before they return to the issuer app.

Push Provisioning flow:

Prerequisites:

Google Pay :

Agreement with Google granting permission to use the Google Pay API for Push Provisioning.
Whitelisted app package name and SHA-256 certificate fingerprint by Google.

Planning the integration:

Sequence diagrams for Android push provisioning options

Issuer app: Push provisioning starts from the issuer's mobile banking app.
Issuer app: The user selects the specific card they would like to push provision.
Google Pay: Google Pay shows this confirmation screen to all users.
Google Pay: We show this screen the first time the user provisions a card in Google Pay or if our address service needs the user to correct their address.
Google Pay: This is the issuer's terms of service. We show this if prompted to do so by the TSP.
Google Pay: This screen is displayed while the issuer is generating and subsequently passing the OPC to the TSP.
Google Pay: The issuer is making an ID&V decision and creating the token. Yellow or red path is uncommon in push provisioning since the user has already proven their identity by logging into the issuer's app and accordingly has already provided a strong form of identity verification.
Google Pay: Google Pay shows this screen to confirm push provisioning completed successfully.
Google Pay: The card is now tokenized and available for tap and pay.
Issuer app: The user is directed back to the issuer app with a confirmation the card was added to Google Pay.

Backend development:

Backend development work will generally focus on generating the opaque payment card ("OPC"). You may also need to do some server side work to correctly list cards in your app.

Generating the OPC:

You will need to work with your TSP to generate the opaque payment card (OPC) for use during push provisioning.

This will likely involve a few steps:

1. Exchange keys with the TSP. These will be used to encrypt and decrypt the OPC.

2. Follow the TSP's documentation to build and encrypt the OPC.

3. Work with the TSP to validate that the OPC is valid and properly encrypted.

Note: Since the OPC is encrypted using keys you exchange with your TSP, we are limited in our ability to help you debug problems with it. Please correlation IDs that they can use to look up the request in their systems to better follow the instructions in our Troubleshooting for instructions on how to register for detailed error logs which include error details we receive from the TSP and assist you.

App development:

Your app will need to comply with our branding guidelines and test cases to ensure their implementation works properly before launching their integration.

1. Development environment setup: The Google Pay Push Provisioning API is bundled with Google Play Services. For the purposes of setting up your development environment, you can think of Google Play Services as two separate components:

The Google Play Services APK: Runs as a background service in the Android OS. This component is always installed on Android devices and is automatically updated with new versions irrespective of the user app download settings.
The Google Play Services Client Library SDK: The SDK is the entry point for the Push Provisioning API. You interact with the background service through the SDK and the service carries out the actions on your behalf.

See Set Up Your Environment for detailed steps on how to get started. Pay particular attention to the sections about the package name allowlist and incorporating our custom Google Play Services binaries into your app.

2. Testing in sandbox vs. production: During development, we strongly recommend testing using sandbox test cards rather than production test cards. Switching between sandbox and production does not require any changes to the code

3. Enable and disable sandbox mode: You can enable sandbox mode using the Android Debug Bridge (adb) command-line tool. To return to production mode, you only need to delete the file. After you add or delete the file, you'll need to reboot the device for the change to take effect.

Enable Sandbox mode command:

adb shell touch /sdcard/Download/android_pay_env_override_sandbox

adb reboot

Disable Sandbox mode command:

adb shell rm /sdcard/Download/android_pay_env_override_sandbox

adb reboot

4. Integrating the SDK: To access the Android Push Provisioning API, you must add a private SDK supplement to your app's dependencies. This supplement is separate from publicly available Google Play Services dependencies that your app might also rely upon.

To integrate the Push Provisioning libraries, you need to perform a few basic tasks to prepare your Android Studio project:

Unzip the SDK (Download the TapAndPaySDK like to the our server)
Edit your project Gradle file

a. Add rules to your root-level build.gradle file, to include the app/libs directory:

allprojects {

// ...

repositories {

// ...

google() // Google's public Maven repository

maven { url "file:/path/to/your/repo/m2repository/" } // Local path to the folder into which you unzipped the SDK

}

3. Edit your module Gradle file

a. In your module Gradle file (usually the app/build.gradle), add the implementation(...) line in your dependencies to import the SDK:

apply plugin: 'com.android.application'

android {

// ...

}

dependencies {

// ...

implementation 'com.google.android.gms:play-services-tapandpay:18.2.0'

// Getting a "Could not find" error? Make sure you have added the unzipped SDK

// location to your root build.gradle file as a local maven dependency

}

Note: The SDK is distributed as a .m2repo, so adding the SDK to your own private Maven repository will also work.

5. Push Provisioning API Access: Google grants access to the Push Provisioning API only to participating financial institutions. Issuer apps need to be given access to the API before they can make calls to it. When your app calls a method in our SDK, we check the fingerprint of the calling app to ensure the app was built using recognized signing keys.

Please use our Push Provisioning API request form to request access for your app.

6. Allowlisting internal builds of your app: For production apps available on the Play Store, we can get the keys from our backend and do not need you to provide your fingerprints when we allowlist your app. But, many issuers have builds of their apps for development or QA testing which have different package names or signing keys that we do not know about. To add these additional package names and fingerprints, submit the Push Provisioning API request form for any additional versions of your app that you need. A single package name can be associated with multiple fingerprints. And, issuers can add as many internal package names as they need for their development and testing purposes.

7. How to get your app's fingerprint: Use the following shell command with your project's APK file to display your SHA-256 certificate checksum using the apksigner tool. The default location of the debug APK file is: your_project_name/app/build/outputs/apk/debug.

# Command to display your SHA-256

$ apksigner verify --print-certs my-push-provisioning-app.apk | grep SHA-256

SHA-256 digest: 3638e ... 64eff

Note: In some cases you may need to use the keytool command instead of apksigner:

# Function to display your SHA-256

$ keytool -printcert -jarfile my-push-provisioning-app.apk | grep SHA256

SHA256: 36:38:63:59:6E:...:00:82:16:4E:FF

8. Backend requirements: To effectively use the Push Provisioning API, each issuer must:

Be able to determine token IDs for each of the customer cards.
Receive the new token ID no later than in 15 seconds (5 seconds is recommended) after a new token is created.

9. Determining Token IDs for the Active Wallet: Most calls to the methods exposed by the Push Provisioning API require you to pass the token ID on which you want to act.

There are two ways to determine the tokens in the active wallet, either

Google provides a mechanism to list tokens or token IDs in the active wallet using the listTokens API. Note that the API only returns token details for tokens in the wallet on the device with metadata matching your app package name.
Get the token IDs from the TSP for each card provisioned in the wallet.

Once you have the list of token IDs from the TSP, you should iterate through it, calling getTokenStatus on each ID to see which tokens are active and associated with the active wallet. This method returns a token status. TapAndPayStatusCodes.TAP_AND_PAY_TOKEN_NOT_FOUND indicates the token is not in the active wallet.

If you maintain a mapping of wallet IDs to token IDs, one potential optimization is to get a filtered set of token IDs for the active wallet, instead of the full set for all wallets. The method getActiveWalletId will return the active wallet’s ID as a string. Once you have the filtered list, you still need to iterate through the token IDs that were returned to make sure they are in the active wallet.

Please note, each network has its own terminology for token IDs:

10. SDK releases: The Push Provisioning API is not available in the publicly distributed version of Google Play Services. You must add the modules available to the public SDK to use this API.

11. Beta testing: During development and the pre-launch process, you will need to share an early version of your application with internal users. While there are many ways to do this by directly sharing APK binaries or using 3rd party tools, this guide documents how you can create a closed beta test through Play Store. See Closed beta testing using Google Groups or Google+ communities for additional information.