App-to-app verification

Issuers can offer app-to-app verification as an option for completing a yellow path ID&V challenge when provisioning a token. App-to-app verification is configured through your TSP and does not require any configuration by the Google Pay team. This page explains how your app interacts with the Google Wallet app based on the provisioning instructions we receive from your TSP.

When users choose to activate app-to-app verification, Google Wallet will invoke the issuer app by calling the Android Activity specified by the issuer through their TSP configuration. Once the user has verified their identity, the issuer app passes control back to Google Wallet to finish the provisioning flow.

If the app is not installed on the user's device, Google Wallet will open the Play Store page for your app. After installing the issuer app, the user needs to restart the flow.

To support app-to-app verification, you will need to:

The flow below shows an abstract user experience for the app-to-app verification process:

a2a-sample-flow

TSP settings

Issuers must provide the parameters below to their TSP. Google Pay receives these parameters from the TSP during the tokenization process and uses them to call your app.

Parameter Example Description
Package Name com.example.myapp The package name (applicationId) identifies the issuer mobile app that Google Pay should call during when invoking the Intent to start the app to app flow. If the app is not installed on the cardholder’s mobile device, the user will be prompted to install it from the Google Play Store.
Action com.example.bank.action.ACTIVATE_TOKEN When calling your app, we create an explicit Intent. The action must be provided in it's 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.

Learn more about sending intents in Android and allowing intents in Android.

App development

When a user selects the app-to-app method to verify their identity, the issuer app must:

  1. Receive the Intent from Google Wallet.
  2. Authenticate the cardholder.
  3. Activate the token.
  4. Return the user to Google Wallet by calling activity.setResult(RESULT_OK, ...)

Receiving the intent

When a user chooses to verify their identity using the issuer's app, Google Wallet calls your app using the package name, action, and EXTRA_TEXT provided to us through the TSP. To receive the Intent from our call, you will need to update your app manifest and create an activity to activate the token.

App manifest

Issuers must update the Android manifest of their mobile app to handle the Action so Google Wallet can call it during the app-to-app flow.

Once your app's manifest has been updated, Google Wallet will be able to call your app to start the token activation activity in your app.

<activity android:name="AppToAppActivity">
  <!-- This activity handles App To App ACTIVATE_TOKEN action -->
  <intent-filter>
    <action android:name="com.example.bank.action.ACTIVATE_TOKEN"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

Learn more about Android intents in the Android developer documentation and Android developer reference.

Token activation activity

To complete activation, your app must start an activity to complete token activation using the activation parameters passed in the Intent. The following code sample demonstrates how you can access the data from the EXTRA_TEXT in the Intent.

/*
 * Within issuer's mobile app AppToAppActivity
 */

// Validate caller is Google Wallet
// see Security Considerations section below

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

// Parse base64 to retrieve the activation parameters as a JSON object in a String
String decodedData = new String(base64.decodeBase64(data));

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

// Extract the activation parameters
String tokenRef = node.get("param0").asText());
String tokenParam = node.get("param1").asText());
// etc.

// Authenticate the user
...

Activating the token

There are two ways to activate tokens:

Activation using TSP APIs

When the card issuing bank mobile app uses the TSP API to activate the token, the card issuing bank app receives the Intent, authenticates the cardholder, and activates the token by calling the TSP’s API. At the end of this flow, you simply indicate to Google Wallet whether or not the activation was successful when returning the user to Google Wallet. Review your TSP technical documentation for details on how you can activate tokens using their APIs.

When activating through the TSP API, your app does not return a code to Google Pay and the token activation happens “out of band” from the Google Pay perspective.

a2a-activation-using-tsp-api

Below is a code sample for how to return the user to Google Wallet after the activation process is complete using the TSP API technique.

Intent resultIntent = new Intent();

resultIntent.putExtra("BANKING_APP_ACTIVATION_RESPONSE", "approved");
// or "declined", or "failure"

activity.setResult(RESULT_OK, resultIntent);

Activation code

When the card issuing bank mobile app obtains an activation code from the TSP and returns it to Google Wallet, the issuer app returns an activation code to Google Wallet using an intent result. Consult with your TSP on how to generate an activation code, sometimes called an authentication code or Tokenization Authentication Value (TAV).

a2a-activation-using-activation-code

Below is a code sample for how to return the user to Google Wallet with an activation code.

Intent resultIntent = new Intent();

resultIntent.putExtra("BANKING_APP_ACTIVATION_RESPONSE", "approved");
// or "declined", or "failure"

// if "approved", also pass the code
resultIntent.putExtra("BANKING_APP_ACTIVATION_CODE", activationCode);

activity.setResult(RESULT_OK, resultIntent);

Mobile app security

The card issuing bank mobile app must have the ability to adhere to the Android security model, especially concerning the use of intents. Upon receiving the intent, use Activity.getCallingPackage to validate that the calling activity is actually Google Wallet as indicated below.


// 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
    ...
}

Make sure that your mobile app does the following:

  • Authenticates the cardholder's identity.
  • Obtains cardholder consent to every digitization request.
  • Verifies that the digitization relates to the correct cardholder account.

Review your TSP’s technical documentation on token activation and the Android developer site for sending, allowing, and receiving Intents.