Google Wallet ID Setup And Testing Guide

A shareable developer document for integrating, configuring, and testing Google Wallet Digital ID support in the Incode Android SDK, available from SDK 5.48.0.

Last updated: 2026-May-11

Available from SDK: 5.48.0

Minimum SDK: API 28

Contents

• Overview
• Requirements
• SDK setup
• Runtime flow
• Sequence diagram
• Device setup
• Test ID pass
• How to test
• Troubleshooting
• Release notes
• References

Overview

The wallets feature lets an end user verify identity by presenting a Google Wallet Digital ID from the Android credential selector instead of scanning a physical ID document.

Wallet Request Ownership

Incode's backend provides the Google Wallet request. That request controls which ID type and which credential fields are requested from Google Wallet.

Requirements

Minimum Platform And Dependency Requirements

Optional Dependency Requirement

If Google Wallet ID verification is used but the optional com.incode.sdk:wallets dependency is not added, the SDK throws a MissingWalletsDependencyException. Add the wallets dependency or disable Device Wallet verification for that IdScan configuration.

SDK Setup

1. Add The Optional Artifact

Use the SDK BOM if the integration already relies on it. Otherwise, pin each artifact version explicitly.

android {
    defaultConfig {
        minSdk 28
    }
}

dependencies {
    implementation platform("com.incode.sdk:bom:5.48.0")
    implementation "com.incode.sdk:welcome"
    implementation "com.incode.sdk:core-light"
    implementation "com.incode.sdk:wallets"
}

2. Select The Google Wallet Environment

The default value is GoogleWalletEnvironment.PRODUCTION. Set GoogleWalletEnvironment.SANDBOX only while testing with Google Wallet sandbox and test ID passes.

IncodeWelcome.Builder(application, apiUrl, apiKey)
    .setGoogleWalletEnvironment(GoogleWalletEnvironment.SANDBOX)
    .build()

IncodeWelcome.Builder(application, apiUrl, apiKey)
    .setGoogleWalletEnvironment(GoogleWalletEnvironment.SANDBOX)
    .build();

For production, remember to remove the .setGoogleWalletEnvironment(GoogleWalletEnvironment.SANDBOX) line. The SDK will use GoogleWalletEnvironment.PRODUCTION automatically.

3. Enable Google Wallet For IdScan

In the Incode Dashboard, open the specific Flow or Workflow where Google Wallet ID should be available. In the IdScan module configuration, turn on Enable Device Wallet verification and make sure Show Document chooser screen is checked.

Environment Must Match The Wallet Device

Use SANDBOX only when your device is switched to the Google Wallet sandbox environment. Production integrations can rely on the default PRODUCTION environment.

Runtime Flow

What Happens When The User Selects Google Wallet

1. SDK confirms Wallet support is available.

   The app must include the optional wallets dependency and use a supported Android version.

2. Incode backend provides the wallet request.

   The request defines which ID and fields should be requested from the user's Google Wallet.

3. SDK shows Google Wallet in document selection.

   The option appears when the IdScan module is configured for Device Wallet verification and the document chooser screen is enabled.

4. Google Wallet opens for user consent.

   The user selects a matching Wallet ID pass and approves sharing the requested fields.

5. SDK continues the onboarding flow.

   When verification succeeds, the SDK advances to the next module. If the user cancels or no credential is selected, the SDK returns to document selection.

Sequence Diagram

The wallet request is fetched before the user starts the Wallet interaction. Later, the user taps Google Wallet, the SDK passes that request to Google Wallet through Android Credential Manager, and the returned credential is sent to Incode backend for verification.

sequenceDiagram
    autonumber
    participant App as Client app
    participant SDK as Incode SDK
    participant BE as Incode backend
    participant Wallet as Google Wallet / Credential Manager

    App->>SDK: Start Flow or Workflow
    Note over App,SDK: SDK initialization and onboarding start
    SDK->>BE: Fetch configuration and wallet request
    Note over SDK,BE: Incode decides requested ID and fields
    BE-->>SDK: Return IdScan config plus wallet request
    Note over SDK: Request is kept until user action
    SDK-->>App: Render document chooser
    Note over App,SDK: Google Wallet button is visible when enabled
    App->>SDK: User taps Google Wallet
    SDK->>Wallet: Pass wallet request to Credential Manager
    Note over SDK,Wallet: Previously received request is used here
    Wallet->>Wallet: User authenticates and consents
    Note over Wallet: Google Wallet shares approved data
    Wallet-->>SDK: Return credential response
    Note over SDK: Response arrives inside the client app process
    SDK->>BE: Send credential for verification
    Note over SDK,BE: Incode backend validates the shared data
    BE-->>SDK: Return verification result
    SDK-->>App: Continue onboarding

Device Setup

Sandbox testing requires two Android devices. Device A simulates an ePassport. Device B stores the ID pass in Google Wallet and runs the SDK test app.

Device A - Passport Simulator

• Android 9 or higher.
• Install the Utopia ePassport Simulator app from Google documentation.
• Create a new passport entry.
• Note: During testing, Pixel 6 worked reliably for this role, while Samsung S25 Ultra was tested and found not to work as expected.

Device B - Wallet And SDK Test Device

• Android 9 or higher, not rooted.
• Google Wallet app installed or updated.
• Google Play Services beta enrolled and updated.
• Screen lock set up.
• Bluetooth and Nearby Devices enabled.
• Use an eligible or allowlisted Gmail account.

Enroll Device B In Google Play Services Beta

1. Open Google Play Services beta enrollment on Device B.
2. Tap Become a tester.
3. Update Google Play Services after enrollment is available.

Request Sandbox Access If The Sandbox Toggle Is Hidden

1. Use the Google Pay Sandbox Access Request form.
2. Submit the Gmail account used on Device B.
3. Wait up to 24 hours, reboot occasionally, then check for TapAndPay Environment again.

Enable Sandbox Mode On Device B

1. Open Settings - Google - All services.
2. Open TapAndPay Environment.
3. Switch from PRODUCTION to SANDBOX.
4. Restart the device.
5. Open Google Wallet and confirm the bottom of Wallet settings shows sandbox mode.

If TapAndPay settings are not visible, Google documents this direct Android settings entry point:

adb shell am start -n com.google.android.gms/com.google.android.gms.tapandpay.settings.TapAndPaySettingsActivity

Do Not Use A Personal Production Wallet For Sandbox Switching

Switching Wallet environments can affect existing Wallet data on the device. Use dedicated test devices and dedicated test accounts whenever possible.

Test ID Pass

Create A Test ID Pass In Google Wallet

1. Install the ePassport simulator on Device A.

   Install the Utopia ePassport Simulator app and create a new passport entry. Keep the entry available for MRZ and NFC steps.

2. Start adding the ID pass on Device B.

   Open Google Wallet, tap Add to Wallet, select ID, then select ID pass.

3. Complete MRZ entry.

   Use the passport details from Device A. If the scan is blocked by the simulator UI, enter the MRZ details manually.

4. Complete NFC handoff.

   Place Device A against the back of Device B during the NFC scan, with the simulator passport entry open.

5. Verify the pass exists.

   Open the ID pass in Google Wallet and confirm the pass details match the simulator entry.

How To Test

Happy Path

1. Install a build that includes com.incode.sdk:wallets on an Android 9 or higher device.
2. Initialize the SDK with GoogleWalletEnvironment.SANDBOX.
3. Use a Flow or Workflow where the IdScan module has Enable Device Wallet verification turned on and Show Document chooser screen checked.
4. Make sure Device B is in Google Wallet sandbox mode and has a test ID pass.
5. Start the onboarding session and navigate to the IdScan document selection screen.
6. Verify that the Google Wallet option is visible.
7. Tap Google Wallet.
8. Verify the Android credential selector opens and shows the matching Wallet ID pass.
9. Select the pass and approve the Wallet consent prompt.
10. Verify the SDK shows processing, completes verification, and advances to the next module or completes IdScan successfully.

Negative And Edge Cases

1. Cancel the credential selector. Expected result: the SDK returns to document selection and does not crash.
2. Use Device B with no matching Wallet ID pass. Expected result: Google Wallet may show no matching IDs. Confirm that the requested ID and fields match the test credential.
3. Use a Flow or Workflow where Enable Device Wallet verification is off. Expected result: Google Wallet is not shown.
4. Run a direct full-SDK IdScan with Google Wallet enabled but without the wallets dependency. Expected result: MissingWalletsDependencyException.
5. Force a failed verification response. Expected result: the SDK shows the Wallet ID upload error screen and the user can tap Try Again.
6. Test on API level 27 or lower with the wallets artifact included. Expected result: the app should not be considered a supported integration because the module requires API level 28+.

When Wallet Shows No Matching IDs

This usually means the request provided by Incode backend does not match any credential currently stored in Google Wallet, or the device is pointed at the wrong Google Wallet environment. Recheck the test ID pass, sandbox state, requested ID type, and requested attributes.

Troubleshooting

References

• Incode Developer Hub
• Google Wallet sandbox mode
• Create a test ID pass in Google Wallet
• Supported credential attributes in Google Wallet
• OpenID4VP 1.0 specification