Google & Samsung Pay

ID&V flow for Google Pay

The following figure shows the Google Pay app-to-app ID&V flow, where Google Pay calls the issuer application ("Bank App").

Step 1: Choose app ID&V option

The end user is prompted to select the ID&V authentication method inside the Google Pay wallet. The end user selects "Sign in to the bank app".

Step 2: Log into issuer application

The end user uses their bank app credentials to log in.

Step 3: Issuer application UI

The bank app shows the last four PAN digits of the card added to Google Pay. The end user selects Next to activate the card in Google Pay.

Step 4: Success screen

A success screen shows the activation status in Google Pay. This screen includes a button that returns the end user to Google Pay.

Scheme TSP configuration

For complete instructions from Google, refer to Google Pay's TSP Settings.

Issuers must provide the following parameters to their TSPs. Google Pay receives these parameters from the TSPs during Tokenization and uses them to call your issuer application.

PARAMETER	EXAMPLE	DESCRIPTION
Package Name	com.example.mybank	The package name (applicationId) identifies the issuer mobile app that Google Pay should call when invoking the intent to start the app to app flow. If the app is not installed on the cardholder’s mobile device, the end user will be prompted to install it from the Google Play Store.
Action	com.example.mybank.action.ACTIVATE_CARD	When calling the issuer mobile app, Google Pay app creates an explicit intent. The action must be provided in its fully qualified form, including the package name. Also, the action must be specific for use in token activation.
Extra text		This parameter is used to pass extra data that will be included in the intent. It is typically a JSON structure, Base64-encoded. The value of this string is opaque to Google and will be provided as-is in the standard field EXTRA_TEXT.

App development flow

When an end user selects the app-to-app method to verify their identity, the issuer application must:

1. Receive the Intent from Google/Samsung Wallet.

2. Authenticate the cardholder.

3. Activate the token.

4. Return the end user to Google Wallet by calling activity.setResult(RESULT_OK, ...).

Receiving the intent

When an end user chooses to verify their identity using the issuer application, Google/Samsung Wallet calls the issuer application using the package name, action, and EXTRA_TEXT provided to Google/Samsung Pay through the TSP. To receive the intent from Google Pay, the issuer must update its application manifest file and create an activity to activate the token.

Updating the Android manifest file

Issuers must update the Android manifest file in their issuer applications to handle the action so that Google Wallet can call it during the app-to-app flow.

To update the manifest file to register the action and activity to handle app redirection:

<activity android:name=".CardActivationActivity">
    <!-- This activity handles App To App ACTIVATE_CARD action -->
    <intent-filter>
        <action android:name="com.example.mybank.action.ACTIVATE_CARD"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

Token activation activity

To complete activation, the issuer application must start an activity that performs token activation using the activation parameters passed in the Intent.

/*
 * Within issuer's mobile app AppToAppActivity (CardActivationActivity)
 * extra library: com.fasterxml.jackson.core:jackson-core & com.fasterxml.jackson.core:jackson-databind
 */

import android.util.Base64;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

/*
    * After receiving the intent, the application must use the Activity.getCallingPackage() API to
    * validate that the request is coming from Google Pay as follows:
    */
// Validate caller is Google Wallet (Google Play Services)
if ("com.google.android.gms".equals(getCallingPackage())) {
    // Proceed with token activation
} else {
    // Abort token activation: handle error
}

String data = getIntent().getStringExtra(Intent.EXTRA_TEXT);

// Parse base64 to retrieve the activation parameters as a JSON object in a String
byte[] decodedDataBytes = Base64.decode(data, Base64.DEFAULT);
String decodedData = new String(decodedDataBytes, StandardCharsets.UTF_8);

// Read the JSON string using jackson
ObjectMapper mapper = new ObjectMapper();
JsonNode node = mapper.readTree(decodedData);

String tokenId = null;
String scheme = CardScheme.VISA.getScheme();
String panLast4 = null;
String tokenRequestorId = "";

if (node.get("tokenReferenceID") != null) { // VISA Scheme
    // For VISA -> tokenReferenceID : tokenId
    tokenId = node.get("tokenReferenceID").asText(); //VISA
    panLast4 = node.get("panLast4").asText(); //VISA

    // tokenRequestorId -> For Google Pay or "40010043095" for Samsung Pay - relevant only in case SCHEME is VISA, for MASTERCARD put empty string
    tokenRequestorId = node.get("tokenRequestorID").asText(); //VISA

} else { // MASTERCARD
    // For MasterCard -> tokenUniqueReference : D1 -> tokenId
    tokenId = node.get("tokenUniqueReference").asText(); //MasterCard
    panLast4 = node.get("accountPanSuffix").asText(); //MasterCard
    scheme = CardScheme.MASTERCARD.getScheme();
}

String authorizationCode = "<JWT>"; // provide JWT value related to particular card, retrieved from issuer backend

// Note: Application must show panLast4 as Card Identification.

TPCManager.getInstance().getTSHProxy().updateTokenState(tokenId,
        tokenRequestorId,
        scheme,
        authorizationCode,
        TokenAction.ACTIVATE,
        new TPCSDKListener<Boolean>() {
            @Override
            public void onStart() {
                // on start
            }

            @Override
            public void onSuccess(TPCResult<Boolean> result) {
                Log.i(TAG, "Token State Updated, card activated");
                Boolean status = result.getResult();

                // TODO: refresh UI for new status
            }

            @Override
            public void onError(TPCSDKException exception) {
                Log.e("TAG", "updateTokenState request Error = " + exception.getMessage());
            }
        });

Card and Token identification

When Google Pay triggers the issuer application, it provides a Base64-encoded string called EXTRA_TEXT in Google's TSP Settings.

The issuer application must decode the Base64 string to retrieve the token details required for activation. The format depends on the scheme used.

The following example shows the JSON object encapsulated in the EXTRA_TEXT for Visa and Mastercard:

Caution

These JSON samples are provided as is. You are responsible for using the latest scheme specifications. Thales is not responsible for any changes the schemes may introduce to the following JSON objects.

An example of Visa scheme:

{
"panReferenceID ":"V-3815023863409817870482",
"tokenRequestorID":"42301999123",
"tokenReferenceID":"DNITHE381502386342002358",
"panLast4":"1234",
"deviceID":"DEiOiJBMjU2R_0NNS1-ciLCJiI",
"walletAccountID":"AiOiJBMjU-2_R0NNS1ciLCJiI6"
}

An example of Mastercard scheme:

{
"paymentAppProviderId": "123456789",
"paymentAppInstanceId": "123456789",
"tokenUniqueReference": "DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532",
"accountPanSuffix": "6789",
"accountExpiry": "1018"
}

Note

The tokenReferenceID and tokenUniqueReference correspond to the token ID in TSP. You can use these IDs to activate the token. panLast4 and accountPanSuffix are the last four digits of the PAN that was tokenized. You can use these values to retrieve the card art and display it to the end user during the authentication request.