Biometrics (React Native 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 PortalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each. - see Portal configuration.
• Integrate the Password Component into your app - see Required components.

The Password Component is required because:

1. Users must authenticate with their password before enrolling for biometrics. The password must be tokenizedTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. for secure communication.
2. 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 tokenizedTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. 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 SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). 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.

2. Turn on biometric authentication

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

3. Provide your Firebase service account key

Biometric Authentication uses two services powered by Firebase:

1. Push notification service, for reliable and secure communication.
2. 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.

Configure the Firebase JSON key

1. Create a service account.
   • Define service account details.
   • Grant the service account access to the project.
   • Grant user access to the service account (optional).
2. 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.
3. Service accounts and applicable keys are available through the Firebase Admin SDK screen.

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

1. Open the Google Cloud Console.
2. 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.
3. Open APIs & Services > Enabled APIs & services.
4. 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.

1. Open Google Play Console and select your app.
2. In the left menu, go to Release → App integrity.
3. Under Play Integrity API, click Link Cloud project.
4. Select the same GCP project where you enabled the Play Integrity API.
5. 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 3DS3DS 3-D Secure - an additional security layer for online credit and debit card transactions. It adds an authentication step where the cardholder verifies their identity with the card issuer during the purchase, reducing fraud and providing liability protection for merchants. transaction screens by selecting the font and colors that match your app's branding.

5. Turn on biometrics for user actions

Biometric Authentication can be used for several user actions:

1. 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).
2. Payment verification: transaction confirmation under PSD2 involves verifying the identity of the customer for a specific transaction.
3. 3DS3DS 3-D Secure - an additional security layer for online credit and debit card transactions. It adds an authentication step where the cardholder verifies their identity with the card issuer during the purchase, reducing fraud and providing liability protection for merchants.: multiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-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.

Get started

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

Our React Native SDK enables you to integrate our Biometric Authentication into your React Native app. To use the React Native SDK, ensure you have obtained the necessary credentials from the Embedder PortalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each.. 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 ";

Push notification setup

Android setup

1. Notification Channel

   • The SDK automatically creates a notification channel with ID "Weavr-auth-channel"
   • Channel is configured with high importance for authentication notifications
   • Vibration and lights are enabled by default

2. Permissions

   import { PermissionsAndroid } from "react-native";
   
   async function requestUserPermission() {
     // Request notification permission for Android 13+
     if (Platform.OS === "android") {
       await PermissionsAndroid.request(
         PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
       );
     }
   }

iOS setup

1. Background Modes

   • Add the following to your app.config.ts:

   ios: {
     infoPlist: {
       UIBackgroundModes: ['fetch', 'remote-notification'],
     },
     entitlements: {
       'aps-environment': 'production',
     },
   }

Implementation flows

The following sections walk through the two main flows you'll integrate: a one-time device enrollment, then the ongoing biometric login and challenge operations.

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:

import {
  initializeUXComponents,
  initializePSA,
} from "@weavr-io/secure-components-react-native";

initializeUXComponents(env, WEAVR_UI_KEY)
  .then((res) => console.log(res))
  .catch((e) => console.log(e));

//if you are using biometric solution
initializePSA(env)
  .then((res) => console.log(res))
  .catch((e) => console.log(e));

Preparing for enrollment

The enrollment flow requires you to set the user token and update the Firebase Cloud Messaging (FCM) token before you enroll the user's device, and every time it changes.

Set the user token. For example:

import { setUserToken } from "@weavr-io/secure-components-react-native";

setUserToken(token).then((res: any) => {
  console.log(res);
});

Then, check it has been associated correctly:

import { isAssociated } from "@weavr-io/secure-components-react-native";

isAssociated().then((res) => {
  if (res) {
    // do your stuff
  } else {
    console.log("You must login first to continue!");
  }
});

The FCM token is required because push notifications are used for the biometric login and Strong Customer Authentication (SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).) flows.

Update FCM token (iOS only)

This operation is only required for iOS. On Android, calling updateFCMToken before the SDK has obtained a token returns an "operation not supported" error - skip it on Android and let the SDK manage FCM token registration automatically.

To provide the FCM token, you must execute a snippet similar to the one below:

import { updateFCMToken } from "@weavr-io/secure-components-react-native";

const token = await messaging().getToken();

updateFCMToken(token)
  .then((res) => console.log("token updated"))
  .catch((e) => console.log(e));

Device enrollment

To start enrollment:

import { startEnrollment } from "@weavr-io/secure-components-react-native";

let result = await startEnrollment();

switch (result.case) {
  case "completed":
    console.log("Enrollment completed");
    break;

  case "initialisationError":
    console.log("SDK not initialised:" + result.error);
    break;

  case "cryptographyError":
    console.log("Cryptography error:" + result.error);
    break;

  case "noBiometricsAvailable":
    switch (result.biometricAvailability) {
      case "noneEnrolled":
        console.log("Device supports biometrics but none are enrolled");
        break;

      case "hwUnavailable":
        console.log("Biometrics hardware is temporarily unavailable");
        break;

      case "noHardware":
        console.log("Device has no biometrics hardware");
        break;
    }
    break;

  case "challengeFailed":
    console.log("Challenge failed:" + result.cause);
    break;

  case "failedBiometricsChallenge":
    console.log("User failed biometrics challenge");
    break;

  case "unauthorized":
    console.log("Unauthorized. Please log in again.");
    break;

  case "userDoesNotConsent":
    console.log("User did not consent to enrollment");
    break;

  case "failedToLoadBrand":
    console.log("Failed to load biometrics configuration");
    break;

  case "noPhoneNumberAvailable":
    console.log("No phone number available");
    break;
}

tip

You have the ability to brand this page by adjusting colors, font, and text size. You can do this in the embedder portalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each. under Settings > Authentication Config > Biometric.

Biometric operations

Biometric login overview

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:

Biometric login

To implement biometric login:

import { startBiometricLogin } from "@weavr-io/secure-components-react-native";

startBiometricLogin()
  .then((res) => {
    const { error, result } = res;
    if (error) {
      Toast.show("Error: " + error.message, 1);
    } else {
      // get token from result.token
    }
  })
  .catch((e) => {
    console.log(e);
  });

Check device status for enrollment

import { checkDeviceIsEnrolled } from "@weavr-io/secure-components-react-native";

checkDeviceIsEnrolled()
  .then((res) => {
    //do your stuff here
  })
  .catch((e) => console.log("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:

1. Challenge reception

   • Challenges are received through push notifications
   • The SDK automatically processes incoming challenges

2. Challenge verification

   • The SDK verifies challenges using biometric authentication
   • Fallback to password (iOS) or passcode (Android) is automatically triggered after 3 failed attempts. Apple does not permit passcodes as an authentication method on iOS, so iOS apps must use password

3. Challenge UI

   • The SDK provides built-in UI for challenge handling
   • UI follows the branding guidelines

4. Triggering a Challenge

Challenges can be triggered by user actions from within your app, namely transaction confirmation for OWTsOWT Outgoing Wire Transfer - a transaction that moves funds from a Weavr managed account to a bank account held at a third-party financial institution. OWTs require the managed account to have an assigned IBAN and the user to complete Strong Customer Authentication., SendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary., or adding a payment beneficiaryBeneficiary A trusted recipient for payments that includes both information about the business or individual as well as their bank account or instrument details. When using trusted beneficiaries, customers may be allowed to skip Strong Customer Authentication (SCA) when executing Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required.; or they can be triggered by a user action outside your app, specifically using a card for an e-commerce transaction that requires 3DS3DS 3-D Secure - an additional security layer for online credit and debit card transactions. It adds an authentication step where the cardholder verifies their identity with the card issuer during the purchase, reducing fraud and providing liability protection for merchants. approval.

Example: app-triggered challenge

Transaction Confirmation challenges for OWTsOWT Outgoing Wire Transfer - a transaction that moves funds from a Weavr managed account to a bank account held at a third-party financial institution. OWTs require the managed account to have an assigned IBAN and the user to complete Strong Customer Authentication. and SendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary. are triggered via the Confirmation Challenges endpoint. A challenge to verify a batch of beneficiaries can be triggered via the Beneficiaries endpoint.

Example: 3DS3DS 3-D Secure - an additional security layer for online credit and debit card transactions. It adds an authentication step where the cardholder verifies their identity with the card issuer during the purchase, reducing fraud and providing liability protection for merchants. challenge

For the approval of an e-commerce transactions via 3DS3DS 3-D Secure - an additional security layer for online credit and debit card transactions. It adds an authentication step where the cardholder verifies their identity with the card issuer during the purchase, reducing fraud and providing liability protection for merchants., 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:

1. After failed biometric attempts

   • Automatically triggered after 3 failed biometric attempts
   • No manual intervention required
   • SDK handles the entire fallback flow

2. 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

3. 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:

1. Uninstalling (and re-installing) the app.

2. By triggering a call from your backend to the Weavr API Unlink endpoint.