1. Google Wallet SDK Overview

1.1. What is Google Wallet SDK?

The Google Wallet SDK is a closed framework dedicated to wallet token management. It enables integration with Google Pay API for Push Provisioning. SDK provides services which methods allow to perform common actions like:

  • start push tokenization flow,

  • set default token,

  • get active wallet id,

  • get token status.

Quickstart guide provides step by step instruction how to integrate with this SDK.

1.2. Prerequisites

Push Provisioning API access needs to be granted to issuer apps in order to make successful calls. If app is not added to allowlist, use Push Provisioning API request form to provide access for your app.

Please read the Google Pay Push Provisioning API’s documentation to see more details about the integration process. Access to the documentation is restricted and it is needed to be signed into Google Account that’s been authorized to view that content. More information here.

After providing a valid configuration and successfully completing the verification process, it is possible to use API methods.

1.3. Versioning and backward compatibility

SDK is based on semantic versioning. For example: 1.0.0 ( MAJOR.MINOR.PATCH )

  • Major version compatibility-breaking changes in SDK public APIs. It is mandatory to update application code, to use SDK, when this is incremented.

  • Minor version tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update application code, when this digit is incremented.

  • Patch version tracks internal changes in SDK. No updates in application code are necessary to update to version, which has this number incremented.

Changes not breaking compatibility:

  • Adding new optional interface to SDK setup.

  • Adding new method to any domain.

  • Adding new enum value to input or output.

  • Adding new field in input or output model.

2. Technical overview

This section describes basic information about Google Wallet SDK setup and available methods.

2.1. Basic information

2.1.1. Facade

Facade is the entry point to communicate with Google Wallet SDK.

2.1.2. Multiple facade types

Google Wallet SDK provides two public API’s with same functionalities, the API’s are:

  • GoogleWalletCoroutineService for projects which uses Kotlin programming language and Coroutines.

  • GoogleWalletStdService for projects which uses Kotlin or Java programming language and standard Callback.

The difference between the API’s is a way of providing data to SDK methods and getting the results from them. Input and output, as an data models, are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as question mark).

2.1.3. Method structure

Every method description has the same structure.

Execution type:
* Asynchronous - Operation could take more time and method is called on a thread different than main. The result of execution is provided in callback (described below).
* Synchronous - Result of operation is provided as a method return type.

Method type:
* Online - Operation requires Internet connection.
* Offline - Operation can be called without Internet connection.

Input
Input parameters with name, type and description.

Output
Result delivered by standard Callback with data or result is suspended until the Coroutine completes Multiple facade types.

2.2. Basic configuration

2.2.1. Min SDK Version

The minSdkVersion must be at least 23 (Android 6.0).

2.2.2. Artifactory

SDK is available on Verestro maven repository and can be configured in project using Gradle build system.

Username and password are provided by Verestro.

repositories{
        maven {
        credentials {
            username "<enter_username_here>"
            password "<enter_password_here>"
        }
        url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
    }
}

2.2.3. Artifacts dependency

Google Wallet SDK is available in two versions: debug and release.
The difference between these versions is debug allows to use application with debugger connected.
Debug version ends with appendix "-debug" in version name. Samples below:

For release version used on production environment in application uploaded to Google Play:

dependencies {
    implementation 'com.verestro.sdk:google-wallet:1.3.5'
}

For debugging purposes:

dependencies {
    implementation 'com.verestro.sdk:google-wallet-dev:1.3.5-debug'
}

2.2.4. Source code obfuscation and optimization

As SDK is written in Kotlin language we recommend to add following code to gradle configuration:

android {
    ...
    kotlinOptions {
        freeCompilerArgs = [
                '-Xno-param-assertions',
                '-Xno-call-assertions',
                '-Xno-receiver-assertions'
        ]
    }

    packagingOptions {
        exclude '/kotlin_metadata/**'
    }
    ...
}

And use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8 instead Proguard in gradle.properties file:

android.enableR8=true

2.3. Google Wallet SDK Setup

Available configuration methods:

  • GoogleWalletCoroutineApi.init(configuration: Configuration)

  • GoogleWalletStdApi.init(configuration: Configuration)

    Synchronous. Offline.
Method loads the SDK classes dependencies and initializes it's network services. Must be called before using any method of the SDK. Recommended place to call this method is just once after the application process starts, e.g. in Application's `onCreate` method.

2.3.1. Input

Configuration

Parameter Type Description

application

Application

Application context

url

String

API hostname URL for Token Management Platform

issuerName

String

Issuer name for Token Management Platform

certificateHashes

List<String>

API hostname pins SHA256 for Token Management Platform

tokenType

TokenType

Type token. Default value is SESSION_TOKEN

TokenType

Parameter Description

SESSION_TOKEN

Session token

ACCESS_TOKEN

Access token

2.3.2. Sample

GoogleWalletStdApi 
fun init(configuration: Configuration) {
    GoogleWalletStdApi.init(configuration)
}
GoogleWalletCoroutineApi 
fun init(configuration: Configuration) {
    GoogleWalletCoroutineApi.init(configuration)
}

2.4. Error handling

SDK returns GoogleWalletSdkException errors, which could be caught by application and shown on UI with detailed message. Table below describes general exception types.

GoogleWalletSdkException

Exception Description

UnknownErrorException

Unknown Error

TokenNotFoundException

The indicated issuer token ID does not match a token in the active wallet

InvalidTokenStateException

The specified token was found but was not in a legal state for the operation to succeed

AttestationErrorException

Device did not pass a compatibility check

ApiUnavailableException

TapAndPay API cannot be called by the current application. Check is app added to allowList

HttpApiException

HTTP API exception

TechnicalException

Internal issue

NoSessionException

User is unauthorized. Session expired

RequestCancelledException

Request was canceled

ValidationErrorException

Validation error. Contains list of ValidationError

NoCertificatePinningException

No certificate pinning

Specific types of exceptions are described for each method.

3. Google Wallet Service

3.1. pushTokenize

Asynchronous. Online.
This method is used to start push tokenization flow.

3.1.1. Input

PushTokenizeData

Parameter Type Description

cardId

Long

Card identifier

lastFourDigits

String

Last four digits for the payment card

displayName

String

Display name or nickname used to describe the payment card in the user interface

userAddress

UserAddressModel?

Optional. User’s address

UserAddressModel

Parameter Type Description

firstPartAddress

String?

Optional. First part address

secondPartAddress

String?

Optional. Second part address

countryCode

String?

Optional. Country code

locality

String?

Optional. Locality,e.g city, town, etc.

administrativeArea

String?

Optional. AdministrativeArea, eg. state, province, etc.

name

String?

Optional. Name of the person at this address

phoneNumber

String?

Optional. Phone number associated with the card.

postalCode

String?

Optional. Postal code or ZIP code.

3.1.2. Output

Success

Success callback with PushTokenizeResult model. PushTokenizeResult is an empty class.

Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

PushTokenizationCancelledException

Push Tokenization was cancelled

3.1.3. Sample

Standard Callback 
fun pushTokenize(pushTokenizeData: PushTokenizeData) {
    GoogleWalletStdApi
        .googleWalletStdService
        .pushTokenize(pushTokenizeData, object: ApiCallback<PushTokenizeResult> {
            override fun onSuccess(result: PushTokenizeResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
suspend fun pushTokenize(pushTokenizeData: PushTokenizeData): PushTokenizeResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .pushTokenize(pushTokenizeData)

3.2. tokenize

Asynchronous. Online.
This method restarts ID&V flow. Method is primarily used for activating tokens pending yellow path activation.

3.2.1. Input

TokenizeData

Parameter Type Description

cardId

Long

Card identifier

displayName

String

Display name or nickname used to describe the payment card in the user interface

3.2.2. Output

Success

Success callback with TokenizeResult model. TokenizeResult is an empty class.

Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

TokenizationCancelledException

Tokenization was cancelled

TokenNotFoundException

Token was not found for given card

3.2.3. Sample

Standard Callback 
fun tokenize(tokenizeData: TokenizeData) {
    GoogleWalletStdApi
        .googleWalletStdService
        .tokenize(tokenizeData, object: ApiCallback<TokenizeResult> {
            override fun onSuccess(result: TokenizeResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
 suspend fun tokenize(tokenizeData: TokenizeData): TokenizeResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .tokenize(tokenizeData)

3.3. setDefaultToken

Asynchronous. Online.
This method is used to set the card as their selected (default) card.

3.3.1. Input

SetDefaultTokenData

Parameter Type Description

cardId

Long

Card identifier

3.3.2. Output

Success

Success callback with SetDefaultTokenResult model. SetDefaultTokenResult is an empty class.

Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

SettingDefaultTokenCancelledException

Setting default token was cancelled

TokenNotFoundException

Token was not found for given card

3.3.3. Sample

Standard Callback 
fun setDefaultToken(setDefaultTokenData: SetDefaultTokenData) {
    GoogleWalletStdApi
        .googleWalletStdService
        .setDefaultToken(setDefaultTokenData, object: ApiCallback<SetDefaultTokenResult> {
            override fun onSuccess(result: SetDefaultTokenResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
suspend fun setDefaultToken(setDefaultTokenData: SetDefaultTokenData): SetDefaultTokenResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .setDefaultToken(setDefaultTokenData)

3.4. getActiveWalletId

Asynchronous. Online.
This method is used to get the id of the active wallet.

3.4.1. Input

No input parameters.

3.4.2. Output

Success

Success callback with GetActiveWalletIdResult model.

GetActiveWalletIdResult

Parameter Type Description

activeWalletId

String

Active wallet id
Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

NoActiveWalletException

There is no active wallet, wallet will be created when pushTokenize() is called

3.4.3. Sample

Standard Callback 
fun getActiveWalletId() {
    GoogleWalletStdApi
        .googleWalletStdService
        .getActiveWalletId( object: ApiCallback<GetActiveWalletIdResult> {
            override fun onSuccess(result: GetActiveWalletIdResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
suspend fun getActiveWalletId(): GetActiveWalletIdResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .getActiveWalletId()

3.5. getTokenStatus

Asynchronous. Online.
This method is used to get the status of a token with a given card id.

3.5.1. Input

GetTokenStatusData

Parameter Type Description

cardId

Long

Card identifier

3.5.2. Output

Success

Success callback with GetTokenStatusResult model.

GetTokenStatusResult

Parameter Type Description

tokenStatus

TokenStatus

Token status

TokenStatus

Parameter Description

NeedsIdentityVerification

The token is in the active wallet, but requires additional user authentication for use

Pending

The token is not currently available for payments, but will be after some time

Suspended

The token has been temporarily suspended

Active

The token is active and available for payments

FeliciaPendingProvisioning

Token has been issued by Token Service Provider, but Felica provisioning has not been completed

Untokenized

This state is visible in the SDK but is not possible for push provisioning

Unknown

Unknown status
Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

NoActiveWalletException

There is no active wallet, wallet will be created when pushTokenize() is called

TokenNotFoundException

Token was not found for given card

3.5.3. Sample

Standard Callback 
fun getTokenStatus(getTokenStatusData: GetTokenStatusData) {
    GoogleWalletStdApi
        .googleWalletStdService
        .getTokenStatus(getTokenStatusData, object: ApiCallback<GetTokenStatusResult> {
            override fun onSuccess(result: GetTokenStatusResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
suspend fun getTokenStatus(getTokenStatusData: GetTokenStatusData): GetTokenStatusResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .getTokenStatus(getTokenStatusData)

3.6. getTokensStatuses

Asynchronous. Online.
This method is used to get the status of a token for each given card id.

3.6.1. Input

GetTokensStatusesData

Parameter Type Description

cardsIds

Set<Long>

Set of cards' identifiers

3.6.2. Output

Success

Success callback with GetTokensStatusesResult model.

GetTokensStatusesResult

Parameter Type Description

tokensStatuses

Map<Long, TokenStatus?>

Token status for each provided card identifier. Null value indicates lack of token for a given card

TokenStatus

Parameter Description

NeedsIdentityVerification

The token is in the active wallet, but requires additional user authentication for use

Pending

The token is not currently available for payments, but will be after some time

Suspended

The token has been temporarily suspended

Active

The token is active and available for payments

FeliciaPendingProvisioning

Token has been issued by Token Service Provider, but Felica provisioning has not been completed

Untokenized

This state is visible in the SDK but is not possible for push provisioning

Unknown

Unknown status
Failure

Failure callback with throwable. Possible types of exceptions:

GoogleWalletSdkException

Exception Description

NoActiveWalletException

There is no active wallet, wallet will be created when pushTokenize() is called

3.6.3. Sample

Standard Callback 
fun getTokensStatuses(getTokensStatusesData: GetTokensStatusesData) {
    GoogleWalletStdApi
        .googleWalletStdService
        .getTokensStatuses(getTokensStatusesData, object: ApiCallback<GetTokensStatusesResult> {
            override fun onSuccess(result: GetTokensStatusesResult) {
                 /*TODO: do something with success event*/
            }
            override fun onFailure(error: Throwable) {
                /*TODO: something went wrong*/
            }
        })
}
Kotlin Coroutines 
suspend fun getTokensStatuses(getTokensStatusesData: GetTokensStatusesData): GetTokensStatusesResult =
    GoogleWalletCoroutineApi
        .googleWalletCoroutineService
        .getTokensStatuses(getTokensStatusesData)

3.7. setInAppVerificationCallback

Synchronous. Offline.
This method is used to register the callbak of in app verification process.

3.7.1. Input

InAppVerificationCallback

Parameter Type Description

inAppVerificationCallback

InAppVerificationCallback

Implementation of verification callback

3.7.2. Output

onAuthRequired

Authentication required with AuthRequest model.

AuthRequest

Parameter Type Description

tokenReferenceId

String

Token reference ID for which authentication is required.

approve

Method

This method should be called after successful authentication.

abort

Method

This method should be called to abort authentication.
onSuccess

Called when token activation finished successfully.

onFailure

Called when token activation was declined or some technical issue occurred.

Parameter Type Description

message

String

Detailed message, e.g. Token is not INACTIVE

3.7.3. Sample

Standard Callback 
    GoogleWalletCoroutineApi.googleWalletCoroutineService
        .setInAppVerificationCallback(object : InAppVerificationCallback {

            override fun onAuthRequired(authRequest: AuthRequest) {
                context.startActivity(createAuthIntent(authRequest.tokenReferenceId))
                eventBus.subscribe(AuthEvent::class.java) { authEvent ->
                    if (authEvent.success) authRequest.approve()
                    else authRequest.abort()
                }
            }

            override fun onSuccess() {
                Toast.makeText(context, "Verification completed!", Toast.LENGTH_SHORT).show()
            }

            override fun onFailure(message: String?) {
                Log.d(TAG, comment)
                Toast.makeText(context, "Verification failed. Please try again.", Toast.LENGTH_SHORT).show()
            }
        })

4. Quickstart guide

  1. Get access to Google Device Tokenization documentation. To achieve that read Prerequisites.

  2. Complete the Push Provisioning API verification process and make sure application is allowlisted.

  3. Add SDK dependency to app level build.gradle file. Check newest version in Artifacts dependency.

  4. Choose preferred type of facade from Multiple facade types and call init method according to Google Wallet SDK Setup.

  5. After SDK initialization, use a GoogleWalletStdService or GoogleWalletCoroutineService, depending of chosen facade, to access API methods.

  6. Provide card data that are be needed to invoke following methods:

    1. Call getTokenStatus method to retrieve token status for given cardId. The invocation of subsequent methods depends on the received status, so it should be called before pushTokenize or tokenize methods.
      Handle retrieved result in application:

      • Status NeedsIdentityVerification means that additional user authentication is needed. Update UI state. It is recommended to show the Google Pay push provisioning button. After click on it, tokenize method should be called.

      • The remaining statuses should be handled according to status meaning. Check [TokenStatus] table.

      • TokenNotFoundException, NoActiveWalletException mean that card has not been added to wallet. Update UI state. It is recommended to show the Google Pay push provisioning button. After click on it, pushTokenize method should be called.

      • Make sure to handle all remaining exceptions according to business and UX requirements.

    2. Call pushTokenize or tokenize method to complete tokenization process. Those methods need to be called in depends on current token status.

      • pushTokenize method requires cardId, lastFourDigits, displayName and optional userAddress and should be invoked to start push tokenization flow.

      • tokenize method requires cardId and displayName and should be invoked when card adding process to wallet is in yellow path which means that token is in the active wallet, but requires additional user authentication for use.

  7. After calling pushTokenize or tokenize method, Google Pay native screen should display automatically. User is asked to confirm card tokenization. After user confirmation, Google Pay native screen should close automatically. It’s recommended to get token status and update UI state at this step.

  8. For app-to-app verification call setInAppVerificationCallback and pass callback object. Perform authentication in onAuthRequired and call approve method on AuthRequest model.

5. Document changelog

5.1. 1.0.0

Created

5.2. 1.0.1

Renamed getCardTokenStatus method to getTokenStatus

5.3. 1.1.0

Added new method tokenize

5.4. 1.1.1

Updated documentation. Added :

  • opaquePaymentCard field to PushTokenizeData model

  • countryCode field to UserAddressModel model

5.5. 1.2.0

  • Added fields to Configuration model

  • Changed token field to cardId field in SetDefaultTokenData model

  • Removed opaquePaymentCard field from PushTokenizeData model

  • Changed tokenReferenceId field to cardId field in TokenizeData model

  • Changed tokenReferenceId field to cardId field in GetTokenStatusData model

5.6. 1.2.1

  • Updated documentation

5.7. 1.2.3

  • Updated documentation

5.8. 1.2.4

  • Updated documentation

5.9. 1.2.5

  • Added support for DC access token

  • Fixed dependency to TMP SDK in POM file

5.10. 1.2.6

  • Updates TMP SDK

5.11. 1.2.7

  • Updates TMP SDK to 1.1.0

5.12. 1.2.8

  • Fixes issues with getting token statuses

5.13. 1.2.9

  • Handles error from TMP SDK

5.14. 1.2.10

  • Updated koin to version 3.5.3

  • Updated java to 17

  • Updated compile and target android version

5.15. 1.2.11

  • Fixes issues after Koin update

5.16. 1.3.0

  • Adds app-to-app verification feature

5.17. 1.3.1

  • Adds option to override activity with custom intent actions

5.18. 1.3.2

  • Fixes in-app verification request

5.19. 1.3.3

  • Adds getTokensStatuses method for checking token status for multiple cards at once

  • Deprecates redundant exception - TokenReferenceIdNotAvailableForTheCardException

5.20. 1.3.4

  • Optimizes methods for retrieving token status

5.21. 1.3.5

  • Updates TMP SDK to 1.2.2