Skip to main content

Biometrics (iOS 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.

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:

  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.

Biometric turned on

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.

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:

PlatformMechanismSetup required
iOSFirebase App CheckRegister app in Firebase Console, configure App Check
AndroidPlay 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.

KYC UI customization

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.

Step-up Portal payments and 3DS verification

Get started​

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

The iOS SDK enables you to integrate Biometric Authentication into your iOS app. To use the iOS 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 UIKey here”
API_KEY= “Your API Key here”
OWT_PROFILE_ID= ”Your OWT id here”
SEND_PROFILE_ID= “Your send profile id here”

Required capabilities​

Your app target must have the push provisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. notifications capability enabled for the correct functioning of biometrics.

Implementation flows​

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:

//initialize UX components
UXComponents.initialize(environment: .SANDBOX, uiKey: "MY-UI-KEY") { result in
    switch result {
    case .success(let status):
        print("SDK initialised!")
        print("Fixed passcode length: \(status.fixedPasscodeLength)")
        if status.userNeedsRelogin {
            // Logout the user and require a new login.
        }

    case .failure(let error):
        print("Something went wrong initialising the SDK: \(error)")
    }
}

//initialize Biometric Authentication
UXComponents.psa.initialize(psaEnv: .SANDBOX)

Push notification setup​

You need to extend your push notification setup in two steps. First, you'll need to provide to our Components SDK, the device registration token:

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let fcmToken else {
        return
    }
    UXComponents.psa.updateDeviceToken(fcmToken)
}

Second, you'll need to forward to the SDK, the payload received in the push notification, so the SDK can trigger the relevant flows:

UXComponents.psa.startBiometricsChallenge(userInfo: notificationPayload) { (result) in
    print("The challenge ID: \(result.id)")
    print("The challenge type: \(result.type)")

    // Handling of the resolution state
    switch result.state {
    case .completed:
        print("Successfully completed")
    case .declined:
        print("User declined")
    case .noSessionAvailable:
        print("There is no session present")
    case .invalidPassword:
        print("The user entered an invalid password")
    case .failedToDisplay(message: let message):
        print("Failed to display the challenge: \(message)")
    case .cryptoError(message: let message):
        print("There was an error in the cryptography module: \(message)")
    case .serverError(flow: let flow, error: let error):
        print("There was a server error during the SCA flow \(flow): \(error)")
    }
}

Device enrollment​

To start enrollment you must call the UXComponents.psa.startEnrollment function, passing a UIViewController to launch from:

UXComponents.psa.startEnrollment(viewController: viewController) { res in
    switch res {
    case .completed:
        print("The enrollment was completed successfully")
    case .initialisationError(error: let error):
        print("There was an error while initialising the enrollment flow: \(error)")
    case .cryptographyError(error: let error):
        print("There was an error in the cryptography operations of the enrollment flow: \(error)")
    case .failedBiometricsChallenge:
        print("The user failed the biometrics challenge")
    case .unauthorized:
        print("The token present in the SDK is not valid")
    case .userDoesNotConsent:
        print("The user cancelled the flow")
    case .failedToLoadBrand:
        print("Failed to load the brand configuration.")
    case .noPhoneNumberAvailable:
        print("No phone number available to perform the SMS OTP flow.")
    case .noBiometricsAvailable(hardwareSupportsBiometrics: let hardwareSupportsBiometrics):
        print("No biometrics available. Hardware supports biometrics: \(hardwareSupportsBiometrics)")
    case .challengeFailed(cause: let cause):
        print("The challenge failed due to \(cause)")
    }
}
tip

You can brand this page by adjusting colors, font, and text size 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:

UXComponents.psa.startBiometricPSALogin(completion: { res in
    switch res {
        case .success(let data):
            print("Token obtained: \(data?.token ?? "No token")")
        case .failure(let err):
            print("Error: \(err)")
        }
    }, onForgotPasscode: {
        print("Forgot passcode was called")
    }
)

Check device status for enrollment​

UXComponents.psa.checkIsReadyForEnrollment()

Check device has been enrolled​

UXComponents.psa.checkDeviceIsEnrolled { result in
    switch result {
    case .success(let isEnrolled):
        print("Is enrolled: \(isEnrolled)")
    case .failure(let error):
        print("Error: \(error)")
    }
}

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 expects you to pass the incoming challenges via the UXComponents.psa.startChallenge method

  2. Challenge verification

    • The SDK verifies challenges using biometric authentication
    • Password or passcode fallback is automatically triggered after 3 failed attempts

  3. Challenge UI

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

The component also provides information on the type of challenge that the incoming push notification refers to. WeavrChallengeType provides the following properties:

  • statusMessage (String)

  • challengeType (Enum), which consist of

    • case PAYMENT_INITIATION (confirming an OWT or SendSend 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.)
    • case ACCOUNT_INFORMATION (stepping up a session to view account information)
    • case THREEDS_INITIATION (confirming an ecommerce transaction via 3DS)
    • case BENEFICIARY_MANAGEMENT (confirming the creation of a beneficiary)

  • challengeId (string)

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