Biometrics (Android SDK)

Use it for: returning-user login on a previously enrolled device, so the user authenticates with their device biometrics instead of re-entering their password each session. The first sign-in still uses the Password component - biometrics replaces it on subsequent logins, with password as the fallback.

Prerequisites

Before implementing authentication via biometrics, you must:

Configure your program in the Embedder Portal - see Portal configuration.
Integrate the Password Component into your app - see Required components.

The Password Component is required because:

Users must authenticate with their password before enrolling for biometrics. The password must be tokenized for secure communication.
The user must have a password or passcode set, because if biometric authentication fails (e.g. fingerprint not recognized), either password or passcode can be used as a fallback identification method.

Required components

Password component

Required for initial authentication
Used as the fallback authentication method (supports both password and passcode)
Must be tokenized for security

Follow the Password component guide to implement this in your app.

Portal configuration

Before integrating biometrics in your app, configure your program in the Embedder Portal. These steps apply to iOS, Android, and React Native integrations.

1. Configure the fallback factor

Biometric Authentication uses a knowledge factor (something you know) as the fallback when biometric authentication can't complete - for example, a fingerprint isn't recognized. From an SCA perspective, this satisfies the "knowledge" factor.

We recommend password as the fallback factor for new integrations. Passcode is also supported, but only if your app does not implement push provisioning.

In the Settings tab, select Authentication Configs > Weavr Authentication > Authentication Constraints and choose Password (recommended) or Passcode.

info

If you use passcode, we can configure the passcode length for you, between 4 and 8 digits. The initial value is 4.

Program authentication constraints

2. Turn on biometric authentication

In the same Authentication Configs tab, select Biometric > Enable Biometric.

Biometric turned off

3. Provide your Firebase service account key

Biometric Authentication uses two services powered by Firebase:

Push notification service, for reliable and secure communication.
Play Integrity API (Android only), a Google requirement that provides app security and defense against abuse.

To enable the push service, provide your Firebase Service Account Key.

Biometric turned on

Configure the Firebase JSON key

Create a service account.
- Define service account details.
- Grant the service account access to the project.
- Grant user access to the service account (optional).
Access the service account by filtering on the Service Account Name you defined.
- Select Manage keys.
- Choose Add Key > JSON.
- The downloaded file is the Firebase JSON file needed to complete the configuration.
Service accounts and applicable keys are available through the Firebase Admin SDK screen.

Turn on the Play Integrity API in Google Cloud (Android only)

Open the Google Cloud Console.
Select your project.
- Use the project selector at the top to choose your GCP project for the Play Integrity API.
- If you don't have a project, create one with New Project.
Open APIs & Services > Enabled APIs & services.
Turn on the Play Integrity API.
- Select + ENABLE APIS AND SERVICES.
- Search for "Play Integrity API" and select it.
- Select ENABLE.

info

Billing: ensure billing is turned on for your project, as the Play Integrity API may incur usage costs.
Quotas: familiarize yourself with API usage quotas and limits in the Google Cloud Console.
API key: you may need an API key for back-end access to the Play Integrity API. Create and manage API keys in the Google Cloud Console.

Refer to the official Play Integrity API documentation for up-to-date information and best practices.

Link your app in Google Play Console (Android only)

After enabling the Play Integrity API in GCP, you must also link your app in Google Play Console. Without this step, biometric enrollment fails on production builds with an ENROLLMENT_FAILED: Invalid Origin error.

Open Google Play Console and select your app.
In the left menu, go to Release → App integrity.
Under Play Integrity API, click Link Cloud project.
Select the same GCP project where you enabled the Play Integrity API.
Click Link.

warning

Both steps are required-enabling via GCP Console alone is not sufficient. The Google Play Console link is what allows your app's builds to pass integrity checks at runtime.

Attestation: iOS vs Android

The SDK uses different attestation mechanisms on each platform:

Platform	Mechanism	Setup required
iOS	Firebase App Check	Register app in Firebase Console, configure App Check
Android	Play Integrity API (direct)	Enable in GCP Console + link in Google Play Console

These are independent systems. Configuring Firebase App Check for iOS does not cover Android. The Android SDK calls the Play Integrity API directly - it does not use Firebase App Check.

For cross-platform teams: if iOS biometrics work but Android fails with ENROLLMENT_FAILED: Invalid Origin, the most likely cause is that the Play Integrity setup for Android has not been completed.

4. Customize the UI

Choose a brand theme for payments and 3DS transaction screens by selecting the font and colors that match your app's branding.

KYC UI customization

Biometric Authentication can be used for several user actions:

Step-up: a single biometric verification on an enrolled device serves as two independent factors-something you are (biometry) and something you have (enrolled device).
Payment verification: transaction confirmation under PSD2 involves verifying the identity of the customer for a specific transaction.
3DS: multi-factor authentication for online credit and debit card transactions.

In the Settings tab, select Identities > Corporate > Authentication and set Biometric as the authentication method for the user actions you want it to apply to.

Step-up Portal payments and 3DS verification

Get started

Make sure you have read the overall Android Get started section for guidance on setting up, installing, and initializing the SDK.

Our Android SDK enables you to integrate the Biometric Authentication component into your Android app. To use the Android SDK, ensure you have obtained the necessary credentials from the Embedder Portal. Add the values in a configuration file or wherever is convenient to store securely in your app.

UI_KEY = "Your UI key goes here"
API_KEY = "Your API key goes here"
OWT_PROFILE_ID = "Your profile id goes here"
SEND_PROFILE_ID = "Your send profile id goes here"

Required permissions

Add these permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

ProGuard configuration

When integrating our SDK into your Android app, you need to add specific ProGuard rules to ensure proper functionality. Add the following rules to your app's proguard-rules.pro file:

# Keep Weavr SDK classes and their members
-keep class io.weavr.** { *; }
-keep class io.weavr.components.data.dto** { *; }
-keep class io.weavr.components.sumsub.data** { *; }
-keep class io.weavr.components.SecureEditText { *; }
-keep class io.weavr.components.weavrbiometric.WeavrPsaManager { *; }

# Keep required interfaces and resources
-keep class * implements android.graphics.drawable.Drawable { *; }
-keep class * implements android.content.res.Resources { *; }

# Keep Gson related classes and annotations
-keepattributes Signature
-keepattributes *Annotation*
-keep class * extends com.google.gson.TypeAdapter
-keep class * implements com.google.gson.TypeAdapterFactory
-keep class * implements com.google.gson.JsonSerializer
-keep class * implements com.google.gson.JsonDeserializer

# Keep serialized fields
-keepclassmembers,allowobfuscation class * {
  @com.google.gson.annotations.SerializedName <fields>;
}

# Keep Play Integrity related classes
-keep class com.google.android.play.core.integrity.** { *; }
-keep interface com.google.android.play.core.integrity.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

# Keep Approov related classes
-keep class io.approov.** { *; }
-keep class com.criticalblue.** { *; }
-keep class com.criticalblue.approovsdk.** {
    <init>(...);
    *;
}

# Keep crash reporting information
-keepattributes SourceFile,LineNumberTable
-keep public class * extends java.lang.Exception

Why these rules are needed

Weavr SDK classes: the rules prevent ProGuard from obfuscating or removing essential SDK classes and their members.
Gson support: the SDK uses Gson for JSON serialization/deserialization. These rules ensure proper handling of annotated fields and type adapters.
Play Integrity: required for device integrity checks and security features.
Crash reporting: maintains readable stack traces for debugging.

warning

Failure to include these ProGuard rules may result in runtime crashes or unexpected behavior in the SDK's functionality.

First time only: enroll a device

Overview

The following sequence diagram shows the high-level flow of the biometric enrollment process:

Initialize the SDK

To initialize both the main SDK and the Biometric Authentication component:

Note: PSA initialization is required only if your app uses PSA features such as biometric login, step-up authentication (SCA), or enrollment.

// Initialize the main SDK
UXComponents.initialise(this, ENV.SANDBOX, UI_KEY)

// Initialize the biometric manager with error handling
try {
    UXComponents.psa.initialise(
        this,
        PsaENV.SANDBOX,
    )
} catch (e: Exception) {
    // Handle initialization error
    Log.e("WeavrSDK", "Failed to initialize biometric component", e)
}

Push notification setup

Before checking biometric availability, you must set up Firebase Cloud Messaging (FCM) for push notifications:

Configure Firebase Cloud Messaging

Add the following to your AndroidManifest.xml:

<service android:name=".YourFirebaseMessagingService" android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Create Firebase messaging service

Create a service that extends WeavrFCMService:

class YourFirebaseMessagingService : WeavrFCMService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)
        // Handle any additional notification logic here
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        // Update the FCM token in the SDK
        UXComponents.psa.updateDeviceToken(
            token,
            object : WeavrResult<UpdateDeviceTokenResponse, ErrorResponse> {
                override fun onSuccess(result: UpdateDeviceTokenResponse?) {
                    // Handle successful FCM token update
                }
                override fun onFailure(error: ErrorResponse) {
                    // Handle FCM token update failure
                }
            }
        )
    }
}

Register broadcast receiver

private val foregroundMsgReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent != null) {
            UXComponents.psa.handleIntent(
                intent,
                activity = context as Activity,
                PreferenceRepo(context).getAppPNS().toString(),
                weavrPsaSessionListener = object : WeavrPsaSessionListener {
                    override fun onFailed(error: ErrorResponse) {
                        // Handle challenge failure
                    }

                    override fun onSuccess(message: String, challengeType: PSAChallengeType, challengeId: String) {
                        // Handle successful challenge
                    }
                }
            )
        }
    }
}

// Register the receiver
val filter = IntentFilter()
filter.addAction(WeavrFCMService.WEAVR_INTENT_ACTION)
registerReceiver(foregroundMsgReceiver, filter)

Update device FCM token

When you receive a new FCM token, to update it in the SDK:

UXComponents.psa.updateDeviceToken(
    fcmToken,
    object : WeavrResult<UpdateDeviceTokenResponse, ErrorResponse> {
        override fun onSuccess(result: UpdateDeviceTokenResponse?) {
            // Handle successful FCM token update
        }
        override fun onFailure(error: ErrorResponse) {
            when (error.message) {
                "Push Notification Error" -> // Handle push notification error
                    "Service Unavailable"
                -> // Handle service unavailability
                else -> // Handle other errors
            }
        }
    }
)

Device enrollment

Using startEnrollment (recommended)

UXComponents.psa.startEnrollment(
    activity = this,
    certificates = R.array.com_google_android_gms_fonts_certs,
    completion = { result ->
        when (result) {
            is WeavrEnrollmentResult.Completed ->
                // Enrollment finished successfully
            is WeavrEnrollmentResult.InitialisationError ->
                // Flow could not be initialised: result.error
            is WeavrEnrollmentResult.CryptographyError ->
                // Cryptography operation failed: result.error
            is WeavrEnrollmentResult.FailedBiometricsChallenge ->
                // User failed the biometric prompt
            is WeavrEnrollmentResult.Unauthorized ->
                // User token is invalid or expired
            is WeavrEnrollmentResult.UserDoesNotConsent ->
                // User cancelled or dismissed the flow
            is WeavrEnrollmentResult.FailedToLoadBrand ->
                // Brand configuration could not be loaded
            is WeavrEnrollmentResult.NoPhoneNumberAvailable ->
                // No phone number available for SMS OTP
            is WeavrEnrollmentResult.NoBiometricsAvailable ->
                // No usable biometrics enrolled: result.availability
            is WeavrEnrollmentResult.ChallengeFailed ->
                // Challenge failed: result.cause
        }
    }
)

Result reference

Result	Description
`Completed`	Enrollment finished successfully.
`InitialisationError`	The enrollment flow could not be initialised.
`CryptographyError`	A cryptography operation failed.
`FailedBiometricsChallenge`	The user failed the biometric prompt.
`Unauthorized`	The user token stored in the SDK is invalid or expired.
`UserDoesNotConsent`	The user cancelled or dismissed the flow.
`FailedToLoadBrand`	Brand configuration could not be loaded.
`NoPhoneNumberAvailable`	No phone number is available for the SMS OTP step.
`NoBiometricsAvailable`	The device has no usable biometrics enrolled.
`ChallengeFailed`	The challenge failed; inspect `result.cause` for details.

Using startPSAEnrollment (deprecated)

Deprecated

startPSAEnrollment is deprecated as of v3.9.0 and will be removed in a future release. Use startEnrollment instead. See the v3.9.0 migration guide for step-by-step instructions.

// Check all permissions needed for biometric authentication
UXComponents.psa.checkAllPermissionsRequiredByPSA(this)

// Start enrolment with error handling
UXComponents.psa.startPSAEnrollment(
    activity = this,
    firebaseToken = firebaseToken,
    authToken = authToken,
    certificates = R.array.certificates,
    enrollmentListener = object : WeavrPSAListener {
        override fun onFailed(error: ErrorResponse) {
            when (error.message) {
                "Push Notification Error" -> // Handle push notification setup failure
                    "Enrolment Error"
                -> // Handle enrolment failure
                    "Internal Server Error"
                -> // Handle server error
                    "Pin Error"
                -> // Handle PIN verification failure
                else -> // Handle other errors
            }
        }
        override fun onSuccess(message: String) {
            // Handle successful enrolment
        }
    }
)

tip

You have the ability to brand this page by adjusting colors, font, and text size. You can configure this in the embedder portal under Settings > Authentication Config > Biometric

Troubleshooting an internal configuration error

“Internal configuration error” snackbar is shown when the Android SDK starts device authorization but a required local value is missing. Specifically, the consent screen verifies both the UI key and a Play Integrity token are present before proceeding. The Integrity token is fetched right after PSA initialization via a config call that returns a cloud project number, then the Play Integrity API is called.

This usually fails if:

The SDK isn’t fully initialized before starting enrollment (missing UI key or Integrity token).
The Integrity token hasn’t been fetched yet (timing).
The device/Google Play Services/Integrity setup can’t issue a token for the project number.

Ensure that:

You call both SDK init and PSA init on app startup (before showing the consent screen) and with the same environment as your backend:
- You initialize the SDK with your UI key.
- You initialize PSA.
Google Play services is present (not a non‑GMS emulator)
Google-services.json is present in the Android app and matches the same Firebase/Cloud project you use for Play Integrity.
If you are using any proxy tool, disable it and check again.

ENROLLMENT_FAILED: Invalid Origin on Android production

This error means the enrollment request returned HTTP 403 from the backend. It is distinct from the "Internal configuration error" preceding it - that error is a local missing-token issue; this one is a server rejection.

The most common cause when Sandbox works but production fails is that Play Integrity is not fully configured for your production app. Complete both setup steps:

Enable the Play Integrity API in GCP Console → APIs & Services.
Link your app in Google Play Console → Release → App integrity.

Also confirm:

The uiKey passed to UXComponents.initialize() belongs to the Production programme (not Sandbox).
You are testing via Google Play Internal Testing, not a sideloaded APK. Production Play Integrity checks require a Play Store-distributed build.
Even when installed via the Play Store, a debug-signed APK may not pass Play Integrity on production. Use a release-signed build for production testing.

Biometric operations

tip

For first-time user-access, for a user to be fully logged in, a biometric login is required following the enrollment. Returning users should only complete a biometric login, not an enrollment every time.

The Biometrics Authentication component is designed for a single user on one device. If a different user tries to enroll, it shows as the device is already enrolled. See un-enrollment section for more details.

The following sequence diagram shows the high-level flow of a biometric login:

To implement biometric login:

UXComponents.psa.startBiometricPsaLogin(
   activity = activity,
   biometricLoginListener = object : WeavrLoginListener {
      override fun onFailed(error: ErrorResponse) {
         when (error.message) {
            "Authorization Error" -> {
               // Handle biometric authorization failure
            }
        }
        override fun onSuccess(loginResponse: WeavrSecureLoginData?) {
            // Handle successful login
            // Store the token for future use
            val token = loginResponse?.token
        }
    },
    onForgotPassword = {
        // Handle forgot password scenario
    }
)

Check enrollment status

Verify device enrollment status:

UXComponents.psa.isPSAEnrolled(
    context,
    object : WeavrPSAStatusListener {
        override fun onFailed(error: ErrorResponse) {
            when (error.message) {
                "Initialization Error" -> // Handle initialization error
                    "Server Error"
                -> // Handle server error
                else -> // Handle other errors
            }
        }
        override fun onSuccess(isEnrolled: Boolean) {
            if (isEnrolled) {
                // Device is enrolled
            } else {
                // Device is not enrolled
            }
        }
    }
)

Challenge handling

For general context about challenges, see the Step-Up Authentication and Transaction Confirmation sections of the product documentation.

The SDK automatically handles all challenge-related operations:

Challenge reception
- Challenges are received through push notifications
- The SDK automatically processes incoming challenges
Challenge verification
- The SDK verifies challenges using biometric authentication
- Password or passcode fallback is automatically triggered after 3 failed attempts
Challenge UI
- The SDK provides built-in UI for challenge handling
- UI follows the branding guidelines
Triggering a Challenge

Challenges can be triggered by user actions from within your app, namely transaction confirmation for OWTs, Sends, or adding a payment beneficiary; or they can be triggered by a user action outside your app, specifically using a card for an e-commerce transaction that requires 3DS approval.

Example: app-triggered challenge

Transaction Confirmation challenges for OWTs and Sends are triggered via the Confirmation Challenges endpoint. A challenge to verify a batch of beneficiaries can be triggered via the Beneficiaries endpoint.

Example: 3DS challenge

For the approval of an e-commerce transactions via 3DS, the challenge is triggered by an action outside of your app: a purchase by the user at an online checkout, and follows the sequence below:

Automatic fallback to password or passcode

The SDK automatically handles fallback to password or passcode authentication when biometric authentication fails:

After failed biometric attempts
- Automatically triggered after 3 failed biometric attempts
- No manual intervention required
- SDK handles the entire fallback flow
Fallback flow
- SDK automatically shows password or passcode entry screen
- Users can choose between password or passcode authentication
- Handles verification for both authentication methods
- Manages retry attempts for both options
- Provides appropriate error messages
Error handling
- Handles invalid password or passcode attempts
- Manages verification failures for both methods
- Provides clear user feedback

Un-enrollment

A device can only be enrolled to one user for Biometrics Authentication at any one time. Therefore another user cannot use the same device for Biometric Authentication in your app unless the previous user has been unenrolled. This is of particular note when testing your app with the Biometrics Authentication component, where testers may share devices.

The current user can be unenrolled by either:

Uninstalling (and re-installing) the app.
By triggering a call from your backend to the Weavr API Unlink endpoint.

Prerequisites​

Required components​

Portal configuration​

1. Configure the fallback factor​

2. Turn on biometric authentication​

3. Provide your Firebase service account key​

Configure the Firebase JSON key​

Turn on the Play Integrity API in Google Cloud (Android only)​

Link your app in Google Play Console (Android only)​

Attestation: iOS vs Android​

4. Customize the UI​

5. Turn on biometrics for user actions​

Get started​

Required permissions​

ProGuard configuration​

Why these rules are needed​

First time only: enroll a device​

Overview​

Initialize the SDK​

Push notification setup​

Configure Firebase Cloud Messaging​

Create Firebase messaging service​

Register broadcast receiver​

Update device FCM token​

Device enrollment​

Using startEnrollment (recommended)​

Using startPSAEnrollment (deprecated)​

Biometric operations​

Biometric login overview​

Biometric login​

Check enrollment status​

Challenge handling​

Automatic fallback to password or passcode​

Un-enrollment​