Google Wallet ID

This feature verifies a user's identity using their Google Wallet Digital ID instead of scanning a physical document. This page covers setup, the runtime flow, sandbox device configuration, and how to test the happy path and edge cases.

Google Wallet ID is available for:

• SDK version 5.48.0 or later
• SDK API level 28 or later

How It Works

Google Wallet appears as a verification option in the ID Scan module's document chooser when the integration is configured for Device Wallet verification. The user selects a Google Wallet Digital ID and approves sharing the requested fields. The SDK then sends the returned credential to Incode's back end for verification.

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

Prerequisites

• Include the com.incode.sdk:wallets dependency only for integrations that need Google Wallet ID support. Customers not using this feature should omit it.

  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 ID Scan configuration.

• Enable Device Wallet verification in the ID Scan module configuration for the specific Flow or Workflow where Google Wallet ID should be offered.

• Prepare a sandbox-ready Google account and device for testing. Production verification may require package name and signing certificate authorization with Google Wallet.

Set Up Google Wallet ID

Complete the following steps in order.

Add the Optional Artifact

Use the SDK BOM if the integration already relies on it. Otherwise, pin each artifact version explicitly. See Installation for full dependency setup and BOM Version Mapping for BOM-to-module version mapping.

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"
}

Select the Google Wallet Environment

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();

Remove the entire .setGoogleWalletEnvironment(GoogleWalletEnvironment.SANDBOX) line for production. The default value is GoogleWalletEnvironment.PRODUCTION.

Enable Google Wallet for the ID Scan Module

In Dashboard, open the specific Flow or Workflow where Google Wallet ID should be available. In the ID Scan module configuration, turn on Enable Device Wallet Verification and make sure Show Document Chooser Screen is selected.

You can also enable it programmatically when building the module: IdScan.Builder().setGoogleWalletIdEnabled(true). Use IdScan.BuilderNonUi in non-UI mode. Both the Dashboard setting and this builder option control whether Google Wallet ID is offered.

Your environment must match the Wallet device. Use SANDBOX only when your device is switched to the Google Wallet sandbox environment. Production integrations use the default PRODUCTION environment.

Runtime Flow

When the user selects Google Wallet, the following steps occur:

1. The SDK confirms Wallet support is available. The app must include the optional wallets dependency and use a supported Android version.
2. The Incode back end provides the wallet request. The request defines which ID and fields should to request from the user's Google Wallet.
3. The SDK shows Google Wallet in document selection. The option appears when the ID Scan 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. The SDK continues the onboarding flow. When verification succeeds, the SDK advances to the next module. If the user cancels or selects no credential, the SDK returns to document selection.

Sequence Diagram

The wallet request is fetched before the user starts the Wallet interaction. The user then taps Google Wallet, the SDK passes that request to Google Wallet through Android Credential Manager, and the returned credential is sent to the Incode back end 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

Test Google Wallet ID

Complete the following steps in order.

Set Up Testing Devices

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

Set Up Device 1: Passport Simulator

1. Confirm the device is running Android 9 or later.
2. Install the Utopia ePassport Simulator app from Google documentation.
3. Create a new passport entry and keep it available for MRZ and NFC steps.

Set Up Device 2: Wallet and SDK Test Device

1. Confirm the device is running Android 9 or later, not rooted.
2. Install the Google Wallet app. If it's already installed, update it if needed.
3. Enroll in Google Play Services beta:
   1. Open Google Play Services beta enrollment.
   2. Select Become a tester.
   3. Update Google Play Services after enrollment is available.
4. Set up screen lock.
5. Enable Bluetooth and Nearby Devices.
6. Use an eligible or allowlisted Gmail account.

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 2.
3. Wait up to 24 hours, reboot occasionally, then check for TapAndPay Environment again.

Enable Sandbox Mode on Device 2

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 sandbox mode is shown at the bottom of Wallet settings.

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

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

Test ID Pass

1. Install the ePassport simulator on Device 1. 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 2. Open Google Wallet and select Add to Wallet > ID > ID pass.
3. Complete MRZ entry. Use the passport details from Device 1. If the scan is blocked by the simulator UI, enter the MRZ details manually.
4. Complete NFC handoff. Place Device 1 against the back of Device 2 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.

Test Happy Path

1. Install a build that includes com.incode.sdk:wallets on an Android 9 or later device.
2. Initialize the SDK with GoogleWalletEnvironment.SANDBOX.
3. Use a Flow or Workflow where the ID Scan module has Enable Device Wallet Verification turned on and Show Document Chooser Screen selected.
4. Make sure Device 2 is in Google Wallet sandbox mode and has a test ID pass.
5. Start the onboarding session and navigate to the ID Scan document selection screen.
6. Verify that the Google Wallet option is visible.
7. Select 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 ID Scan successfully.

Test Negative and Edge Cases

If Wallet shows no matching IDs, the request from the Incode back end does not match any credential 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

External References

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

See API Reference for the full KDoc/Javadoc API surface, or contact Incode support if you run into integration issues.