Biometric Pix Guide (Using iOS SDK)

With Belvo's Biometric Pix, collecting payments from users becomes seamless, removing the need for users to navigate to their financial institution to approve each individual payment request.

The first step in enabling biometric payment collection is to enroll the user’s device with their institution. During enrollment, key data about the device and the user's public key credentials is securely registered with their institution, ensuring that future payments can be confirmed using biometric authentication alone.

Once enrollment is complete, you can start requesting payments directly from the user’s device.

In this guide, we’ll take you through each step, from device enrollment to successfully initiating a payment request on an iOS Device.

Prerequisites

Before continuing with this guide, make sure that:

1. You have generated your Belvo Payments API Keys

2. Setup Webhooks to receive updates about the status of your payments and enrollments.

3. Installed the Belvo iOS SDK:

   Minimum Requirements

   • iOS: 15.0 or higher
   • Swift: 5.0 or higher

   Instructions:

   To integrate the Belvo Biometric PIX SDK into your Xcode project using Swift Package Manager:

   1. In Xcode, select File → Add Packages....
   2. Enter the package repository URL: https://github.com/belvo-finance-opensource/biometric-pix-ios-sdk.
   3. Select the version requirements and click Add Package.
   4. Choose the BiometricPixSDK product and click Add Package.

4. Add the required entitlements to your app's entitlements file:

   <key>com.apple.developer.associated-domains</key>
     <array>
      <string>webcredentials:belvo.com</string>
     </array>

5. Add location usage description in your Info.plist file:

      <key>NSLocationWhenInUseUsageDescription</key>
      <string>This app uses location for security and fraud prevention purposes.</string>

6. Share your Team ID and Bundle Identifier with Belvo in the following format

       ## Format
       TEAM_ID.BUNDLE_ID
   
       ## Example
       ABCDEFGHIJ.com.yourcompany.appname

7. Additionally, for each user that you want to enroll into the Biometric Pix system, you will first need to create a Belvo Customer.

Enrollment

Enrollment is the process of registering a user’s device in their institution to allow for biometric payments for a given merchant. During the process, you will use a combination of the Belvo Payments iOS SDK and API to retrieve key details about the device as well as the biometric public data.

1. List Institutions: Prompt the user to select their desired financial institution to enroll in, using the Belvo API to display the available options.
2. Request Location Permissions and Collect Risk Signals: Prompt the user for necessary permissions and collect risk signals, including the device ID.
3. Create and Update Enrollment: Send the collected risk signals, along with the customer ID, institution ID, and a callback URL, to Belvo's server to create the enrollment. Then, redirect the user to their institution's app for approval. Once they're redirected back to your callback URL with details, send these to Belvo to update the enrollment state.
4. Poll for FIDO Options: Continuously poll the Belvo API (GET /enrollments/{id}/fido-registration-options/) to retrieve the necessary FIDO options for biometric registration. ⚠️ Polling Strategy: We recommend polling our server every two seconds for up to two minutes. If no response is received within this timeframe, instruct the user to try again.
5. Prompt for Biometrics: Take the FIDO options from Belvo's API and use the Belvo iOS SDK startRegistration(fidoOptions) method to prompt the user for their biometric gesture.
6. Finalize Enrollment: Send the biometric public data to Belvo using POST /enrollments/{id}/confirm/. After that, poll GET /enrollments/{id}/ until a response is received (enrollment status = SUCCEEDED or FAILED).

Prompt the user to select the institution to enroll in (Belvo API)

In your application, prompt your user to select the institution where they want to enroll the device in. Use the List all payment institutions request to get a list of all the possible institutions. Once the user selects the institution, save the id of the institution (required in Send Risk Signals to Belvo (API) step).

Request Location Permissions and Collect Risk Signals (iOS SDK)

Next, in your application, you will need to make the following calls:

requestPermission()

This requestPermission() method creates and launches a permission request for location and phone state permissions.

import SwiftUI
import BiometricPixSDK
import Foundation

struct PermissionRequestExample: View {
    @State private var permissionGranted: Bool? = nil
    private let sdk = BiometricPixSDK()

    private func requestPermission() {
        sdk.requestPermission { granted in
            DispatchQueue.main.async {
								// If needed, cast granted to Bool
                permissionGranted = granted as? Bool
								// If needed, handle UI
            }
        }
    }
}

When the user grants their permission, you can then extract the device’s risk signals using collectRiskSignals(accountTenure).

collectRiskSignals(accountTenure)

The collectRiskSignals(accountTenure) method gathers comprehensive device fingerprinting data and security signals. The collected data includes device ID, security status, hardware information, and behavioral signals, which are crucial for the institution to perform risk assessment and fraud detection. The method returns a RiskSignals object which you need save and forward on to Belvo’s servers in an API call. Additionally, you need to persist the value of deviceId that the the RiskSignals object returns so that later you can associate it with the Enrollment ID (later, when listing Enrollments, you need to provide the deviceID to receive all Enrollments).

import SwiftUI
import BiometricPixSDK
import Foundation

struct RiskSignalsView: View {
    private let sdk = BiometricPixSDK()

    private func collectRiskSignals() {
        do {
            // Collect risk signals with the user creation date
            signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
        } catch {
            // Handle errors that might occur during risk signal collection.
            // Possible errors include:
            // - Invalid `accountTenure` format
            // - Network connectivity issues
            // Consider logging the error or displaying an appropriate message to the user.
        }
    }
}

Once you have the risk signals and device ID, you can forward this information to Belvo using Create Enrollment method.

Create Enrollment Using Risk Signals (API)

POST /enrollments/

// Request Body
{
    "type": "open_finance_biometric_pix",
    "details": {
        "customer": "{{created_customer_uuid}}",
        "institution": "{{selected_institution_uuid}}",
        "name": "Name for the enrollment",
        "platform": "IOS",
        "callback_url": "{{https://deeplink_to_your_application}}",
        "risk_signals": {} 
    }
}

In the response payload, you will receive a redirect_url that you need to display to your user so that they can be redirected to their institution to confirm their enrollment.

// 201 Created
{
  "id": "82666cde-3f80-4350-b0f7-24cb8e9294c9",
  "created_by": "56689ef8-4c92-44ae-b2c1-60505da4a7e1",
  "created_at": "2024-11-26T11:20:57.389056Z",
  "updated_at": "2024-11-26T11:20:57.389056Z",
  "type": "open_finance_biometric_pix",
  "status": "PENDING",
  "details": {
    "status": "AWAITING_ACCOUNT_HOLDER_VALIDATION",
    "customer": "f78b14f3-5c1a-409a-966f-7b052b067cf0",
    "institution": "188716fb-39ad-44a7-a992-6c278d2b24a4",
    "platform": "IOS",
    "name": "First Enrollment",
    "callback_url": "deeplink-to-your-application",
    "redirect_url": "https://www.user-banking-institituon.com/?enrollment_request=true...", 
    "risk_signals": "*****"
  }
}

Redirect user to their APP and update enrollment

You now need to redirect your user to their institution using the redirect_url so that they can confirm the enrollment process. During the process, they will log in to their institution, review the enrollment request, and then authorize it. Once the user authorizes the enrollment, the institution will redirect them back to the callback_url you provided.

https://redirect.clientApplication.com/
	?state=<state>
	&code=<code>
	&id_token=<long_id_token>

The institution will pass data in the query parameters that you must forward on to Belvo using the Update Enrollment State API request. We recommend transforming the query parameters into a JSON object and sending it directly through to Belvo.

Update Enrollment State

With the value of the query string saved as a JSON object, you can make the following request:

POST /enrollments/complete-redirection/

{
    "state": "{{state}}",
    "code": "{{code}}",
    "id_token": "{{id_token}}",
}

// 200 OK
{
    "id": "{{enrollment.id}}", 
    "type": "open_finance_biometric_pix",
    "status": "PENDING",  
    "details": {
        "callback_url": "https://merchant.com/enrollment-success/",
        "customer": "{{customer.id}}",
        "expires_at": "2022-10-31T00:00:00Z",
        "institution": "uuid",
        "name": "My Enrollment",
        "payer_information": {
            "bank_account": {
                "institution_id": "{{institution.id}}",
                "agency": "1234",
                "number": "*****6789",
                "account_type": "CHECKINGS"
            }
        },
        "platform": "IOS",
        "redirect_url": "https://example.com/redirect-enrollment/",
        "risk_signals": "*******",
        "status": "AWAITING_ACCOUNT_HOLDER_VALIDATION"
    },
    "external_id": null,
    "metadata": {},
    "status_reason_code": null,
    "status_reason_message": null,
    "created_by": "{{belvo_client.id}}",
    "created_at": "{{timestamp}}",
    "updated_at": "{{timestamp}}"
}

Poll Belvo API for FIDO options (API)

After you receive the successful response from the Update Enrollment State request, you need to poll the endpoint below in order to receive the FIDO registration options required to prompt for biometric data.

GET /enrollments/{enrollment_id}/fido-registration-options/

You will receive the following 200 - OK response from our API. Make sure to save the object (fidoOptions) as it is a required parameter for the startRegistration() SDK method.

// 200 OK
{
    "rp": {
        "id": "belvo.com",
        "name": "Raidiam Mockbank - Pipeline NRJ"
    },
    "user": {
        "id": "a5bd0ef9-f8ab-41a2-b968-489761a91de6",
        "name": "Ralph Bragg",
        "displayName": "Ralph Bragg"
    },
    "challenge": "R3dsT2REOE5oZ25JbVE",
    "pubKeyCredParams": [
        {
            "alg": -257,
            "type": "public-key"
        },
        {
            "alg": -7,
            "type": "public-key"
        }
    ],
    "extensions": {
        "appid": "true"
    }
}

Prompt for Biometrics (iOS SDK)

With the payload received, you need to use the startRegistration(fidoOptions) method. This method starts the biometric credential registration using FIDO2 protocols. It processes the FIDO registration options (a JSON string) received from your backend server and launches the device's native biometric authentication flow (e.g., fingerprint or face scan).

import Foundation
import BiometricPixSDK

class FidoRegistrationViewModel : NSObject, ObservableObject {
    private let sdk = BiometricPixSDK()

    func startRegistration(fidoOptions: String) {
        do {
            sdk.startRegistration(
                fidoResponseString: fidoOptions, 
                callback: self // Callback instance
            )
        } catch {
            // Handle errors
        }
    }
}

// Implementing callback for registration
extension FidoRegistrationViewModel: FidoRegistrationCallback {
    func onError(error: String) {
            // Handle registration errors
    }

    func onSuccess(response attestationResponse: AttestationResponse) {
            // Handle successful registration
            // The attestationResponse object contains the data needed for the next step.
            let encodedId = attestationResponse.encodedId
            let rawId = attestationResponse.rawId
            let encodedAttestationObject = attestationResponse.encodedAttestationObject
            let encodedClientDataJSON = attestationResponse.encodedClientDataJSON
            
            // Persist these values to be sent to your backend.
    }
}

import SwiftUI

struct MyView: View {
    @ObservedObject var registrationViewModel = FidoRegistrationViewModel()
// ...
}

You need to store the following values in variables as they are used to confirm the Enrollment in the following step:

• encodedId
• rawId
• encodedAttestationObject
• encodedClientDataJSON

Send biometrics to finalize enrollment and poll for response (API)

To complete the Enrollment process you will need to send the values you received to the following endpoint:

POST /payments/br/enrollments/{enrollment_id}/confirm/

// Request Body
{
  "confirmation_data": {
    "authenticatorAttachment": "platform",
    "id": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "type": "public-key",
    "response": {
      "attestationObject": "{{encodedAttestationObject}}",
      "clientDataJSON": "{{encodedClientDataJSON}}"
    }
  }
}

Belvo will respond with a 204 - No Content and forward the information to the institution to complete the enrollment process.

You will need to poll the following endpoint until you receive a response from Belvo’s API. Once you receive a response, check the status field.

GET /enrollments/{enrollment_id}/

If the status is SUCCEEDED, perfect! The enrollment is ready and you can start making payments!

Making a Payment

Once a user's device is successfully enrolled, you can initiate payment requests using their stored biometric credentials. This process involves:

1. Selecting an Enrollment
2. Creating a payment intent
3. Collecting biometric authentication data
4. Authorizing the payment

Select Enrollment (API)

Use the List all enrollments API method, with the required device_id query parameter, to request all the enrollments your user has made using your application and their current device. Display this list of enrollments to the user, allowing them to choose which enrollment to use for the payment. Save the id of that enrollment (used in the following Create Payment Intent step).

GET /enrollments/?device_id={device_id}

Create Payment Intent (API)

Once you have the user’s selected Enrollment, you can create a Payment Intent:

POST /payments/br/payment-intents/

{
    "amount": 0.13,
    "allowed_payment_method_types": [
        "open_finance_biometric_pix"
    ],
    "customer": "{{customer.id}}",
    "description": "Test Payment Intent with Enrollment",
    "statement_description": "Description to show on statement",
    "payment_method_details": {
        "open_finance_biometric_pix": {
            "beneficiary_bank_account": "{{bank_account.id}}",
            "enrollment": "{{enrollment.id}}"
        }
    },
    "confirm": true
}

In the response, Belvo will return the payment_intent.id and the fido_options object that are required for the next step of biometric authentication. You need to:

• Persist the payment_intent.id on your backend.
• Save the fido_options in a variable to be used in the next step in the Belvo SDK.

{
  "id": "uuid", 
  "status": "PENDING",
  "payment_method_information": {
	  "open_finance_biometric_pix": {
	      "provider": "belvo",
	      "consent_id": "urn:nubank:023230b9-1211-3420-bf6d-e7d56e87bdf1",
	      "fido_options": { 
	          "rpId": "belvo.com",
	          "timeout": 300000,
	          "challenge": "oGW096Hvr8sVUIOf-10iqWI7ZfSx2GhoU359bBRK9h4",
	          "allowCredentials": [
	              {
	                  "id": "AfD-uI4LUzJAuzyLBRrPncocLusMgZ8yHNuuUl-7NSFbBlqrW2rMF0D_Ao-orNqdX3YZVf8_wk1jj--HuNH1uKE",
	                  "type": "public-key"
	              }
	          ]
	      },
	      "end_to_end_id": "E432158152025061315009OzwiMmDSO7",
	      "external_payment_id": "bde3bb4d-5b48-4875-b69d-7f2beee4fb42",
	      "provider_request_id": "afc99a8b-e0c7-4a8b-85d7-193bd70e4cc0"
	  }
	}
}

Collect Biometric Data and Risk Signals (SDK)

Using the fido_options received from the payment intent, initiate the biometric authentication process using the startSigning(fidoOptions) method of the Belvo iOS SDK. After the user authenticates, you will also need to call collectRiskSignals(accountTenure) to gather device information.

The results from these methods contain the values you will need to send to your backend to authorize the payment.

import Foundation
import BiometricPixSDK

class FidoAuthenticationViewModel : NSObject, ObservableObject {
    private let sdk = BiometricPixSDK()

    func startSigning(fidoOptions: String) {
        do {
            // Note: The method to initiate payment authentication is startSigning.
            sdk.startSigning(
                fidoResponseString: fidoOptions,// json string requested from the backend api
                fallbackCredential: nil,//fallback credential string if avaliable
                callback: self// callback instance
            )
        } catch {
                        // Error handling
        }
    }
    
    private func collectRiskSignals() {
        do {
            // Collect risk signals with the user creation date
            let signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
            // Send the signals to your backend to be used in the authorize step.
        } catch {
            // handle error
        }
    }
}

// implementing callback for authentication
extension FidoAuthenticationViewModel: FidoAuthenticationCallback {
    func onError(error: String) {
                // Handle authentication errors
    }

    func onSuccess(response assertionResponse: AssertionResponse) {
                // Handle successful authentication
        // Extract data from assertionResponse and send to your backend.
        // Then, call collectRiskSignals.
        collectRiskSignals()
    }
}

import SwiftUI

struct MyView: View {
    @ObservedObject var registrationViewModel = FidoRegistrationViewModel()
// ...
}

Authorize Payment (API)

After retrieving the required information in the Collect Biometric Data and Risk Signals (SDK) step, you can now authorize the payment using Belvo's API.

POST /payment-intents/{payment_intent_id}/authorize/

• Belvo will process the authorization. You will need to poll GET /payment-intents/{id}/ until the status of the payment intent becomes SUCCEEDED.

  Polling Strategy: Similar to enrollment, we recommend polling the payment intent status (GET /payment-intents/{payment_intent_id}/) every two seconds for up to two minutes until the status is SUCCEEDED. If the status does not change or an error occurs, inform the user and suggest retrying.

• Once the payment is successful, display a confirmation screen to the End User.

// POST /payment-intents/{id}/authorize/ Request Body Example
{
  "risk_signals": {}, // The Risk Signals object collected
  "assertion": {
    "authenticatorAttachment": "platform",
    "id": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "response": {
      "authenticatorData": "{{encodedAuthenticatorData}}",
      "clientDataJSON": "{{encodedClientDataJSON}}",
      "signature": "{{encodedSignature}}",
      "userHandle": "{{userHandle}}"
      
    },
    "type": "public-key"
  }
}

Belvo's API will return a 204 - Not Content. After which, you need to poll the following endpoint in order to retrieve the final status of the payment:

GET /payment-intents/{payment_intent_id}/