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:
- Configure TSP settings to enable the app-to-app flow.
- Update your app to support the app-to-app flow.
The flow below shows an abstract user experience for the app-to-app verification process:
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:
- Receive the Intent from Google Wallet.
- Authenticate the cardholder.
- Activate the token.
- 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:
- By calling the TSP API to activate the token directly.
- By obtaining an activation code from the TSP and passing
it to Google Wallet in the
Activity
result.
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.
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).
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
.