# Biometric Pix Guide (Using Android SDK)
Upcoming Release
This documentation covers features from our upcoming release. While the core functionality and workflow described here will remain unchanged, you may notice some refinements before the final release, such as:
- Android SDK updates and optimizations
- Documentation improvements (links, terminology, diagrams)
- API reference updates for enrollment endpoints
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 Android Device.
## Prerequisites
Before continuing with this guide, make sure that:
1. You have generated your Belvo Payments API Keys
2. Setup Webhooks
3. Installed the Belvo Android SDK
- Installing the Belvo Android SDK
**Minimum Requirements**
- **Android SDK**: API 31 (Android 12) or higher
- **Compile SDK**: 35
- **Java Version**: 11
- **Kotlin**: Compatible with latest stable version
**Instructions**
To install the Belvo Android SDK, add the following SDK dependencies to your app-level `build.gradle.kts`:
```kotlin
dependencies {
implementation("com.belvo.biometricpixsdk:biometricpixsdk:1.0.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}
```
Additionally, you’ll need to add the following permissions to your AndroidManifest.xml file:
```xml
```
4. Enabled credential sharing with Belvo
- Enabling credentials sharing
To complete the integration of the Belvo Android SDK and enable secure credential sharing between your app and Belvo’s domain (`belvo.com`), we need to configure a **Digital Asset Link**.
This setup creates a trusted connection between your app and `belvo.com`, allowing your app to securely access Belvo SDK features like user Enrollment registration and Payment Intent Authorization. This data corresponds to the **`target` section** of a [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started#quick-usage-example) entry. We use this data to update our `assetlinks.json` file hosted at: `https://belvo.com/.well-known/assetlinks.json`
You will need to provide us the following information from your app:
- Your app’s **package name**
- Your app’s **SHA-256 signing certificate fingerprint** (see the [official Android documentation on how to retrieve this fingerprint](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc)).
An example of your target object should look like this:
```json
{
"namespace": "android_app",
"package_name": "com.example.yourapp",
"sha256_cert_fingerprints": [
"12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0"
]
}
```
5. Shared your application's **FACETID** with Belvo. For details on how to generate your app's FACETID, see our dedicated FACETID Generation (Android SDK) guide.
6. 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 Android 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. **Initialize SDK and Collect Risk Signals:** Initialize the Belvo Android SDK, 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 Android SDK `startRegistration()` 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`).
```mermaid
sequenceDiagram
autonumber
participant EndUser
participant ClientAppBackend
participant BiometricPixSDK
participant Payments
participant BankAPP
Note over EndUser,BankAPP: 0. Prompt the user to select the institution to enroll in (Belvo API)
ClientAppBackend ->> Payments: /institutions/
Payments -->> ClientAppBackend: List of institutions
ClientAppBackend ->> EndUser: Display list of institutions
EndUser -->> ClientAppBackend: Selected institution
Note over EndUser,BankAPP: 1. Initialize SDK and Collect Risk Signals (Android SDK)
ClientAppBackend ->> BiometricPixSDK: initialize()
BiometricPixSDK ->> EndUser: requestPermission()
EndUser -->> BiometricPixSDK: Grants permission to collect risk signals
ClientAppBackend ->> BiometricPixSDK: collectRiskSignals(accountTenure)
BiometricPixSDK -->> ClientAppBackend: Returns riskSignals + deviceId (encrypted)
ClientAppBackend ->> ClientAppBackend: Persist deviceId (encrypted)
Note over EndUser,BankAPP: 2. Send Risk Signals to Belvo (Belvo API)
ClientAppBackend ->> Payments: POST /enrollments/ (riskSignals, callback_url)
Payments -->> ClientAppBackend: 201 Created (enrollment_id, redirect_url)
ClientAppBackend ->> ClientAppBackend: Persist enrollment_id associated with deviceId (encrypted)
Note over EndUser,BankAPP: 3. Redirect user to their APP and update enrollment
ClientAppBackend ->> EndUser: Redirect to BankAPP (using the redirect_url)
EndUser ->> BankAPP: Approves enrollment
BankAPP ->> ClientAppBackend: Institution redirects to callback_url with details in query parameters
ClientAppBackend ->> Payments: Update enrollment with received values using POST /enrollments/complete-redirection/
Payments -->> ClientAppBackend: Returns Enrollment updated payload
Note over EndUser,BankAPP: 4. Poll Belvo API for FIDO options
ClientAppBackend ->> Payments: Poll GET /enrollments/{id}/fido-registration-options/
Payments -->> ClientAppBackend: Returns fido_options
Note over EndUser,BankAPP: 5. Prompt for Biometrics (Android SDK)
ClientAppBackend ->> BiometricPixSDK: startRegistration(fido_options)
BiometricPixSDK ->> EndUser: Request biometric data
EndUser -->> BiometricPixSDK: Provides biometric (face/fingerprint/PIN)
BiometricPixSDK -->> ClientAppBackend: attestationObject, clientDataJSON, credential
Note over EndUser,BankAPP: 6. Send biometrics to finalize enrollment and poll for response
ClientAppBackend ->> Payments: POST /enrollments/{id}/confirm/ (attestationObject, clientDataJSON, credential)
Payments -->> ClientAppBackend: 204 - No Content
ClientAppBackend ->> Payments: Poll GET /enrollments/{id}/
Payments -->> ClientAppBackend: status = SUCCEEDED
```
## 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).
## Initialize SDK and Collect Risk Signals (Android SDK)
Next, in your application, you will need to make the following calls:
### initialize()
This method must be called in your `Activity`'s `onCreate()` method before any FIDO operations. You should use `createActivityResultCallback()` to obtain the proper callback function for the `fidoLauncher` parameter.
The `initialize(fidoLauncher)` method sets up the internal activity result handling required for FIDO2 biometric operations. It must be called once during the activity's lifecycle to prepare the SDK for launching biometric prompts and receiving their results.
In the example below, you can see that in the `fidoLauncher` variable that we also use the `createActivityResultCallback()` from Belvo’s Android SDK. This method returns a callback function that should be used when registering the `ActivityResultLauncher` for FIDO operations. It acts as the SDK's internal handler for processing the `ActivityResult` objects received from system activities initiated by the FIDO flow. This allows the SDK to manage the state of biometric operations seamlessly.
```kotlin
class MainActivity : ComponentActivity() {
private lateinit var biometricPixSDK: BiometricPixSDK
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
biometricPixSDK = BiometricPixSDK()
// Use createActivityResultCallback() when setting up the launcher.
// This lambda function will be internally used by the SDK to process FIDO results.
val fidoLauncher = registerForActivityResult(
ActivityResultContracts.StartIntentSenderForResult(),
biometricPixSDK.createActivityResultCallback() // This lambda handles all FIDO activity results
)
// Initialize SDK with the configured launcher
biometricPixSDK.initialize(fidoLauncher)
}
}
```
Once you have initialized the launcher, we can proceed to request the user’s permission to extract risk signals from their device using the `requestPermission()` method**.**
### requestPermission()
This `requestPermission()` method creates and launches a permission request for location and phone state permissions (`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`, and `READ_PHONE_STATE`). It automatically handles the Android runtime permission request flow and provides a callback with the overall result. The method returns `ActivityResultLauncher>`: The permission launcher instance. While returned, typically you can ignore this return value, as the primary interaction is through the `onResult` callback after calling the function.
```kotlin
// Add this to your MainActivity
biometricPixSDK.requestPermission(this) { granted ->
if (granted) {
// All required permissions granted. SDK is ready for full functionality.
Log.d("BiometricSDK", "All necessary permissions granted.")
} else {
// Handle denied permissions.
// Inform the user about features that may be unavailable or guide them to settings.
Log.e("BiometricSDK", "Permissions denied. SDK functionality may be limited.")
}
```
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).
accountTenure Parameter
In the `accountTenure` argument, you must pass the date that the user was created as a Customer in Belvo’s API, in `YYYY-MM-DD format`.
This is derived from the Customer created_at timestamp, however just need to send through the first 10 characters correspoding to the year, month, and date (`YYYY-MM-DD`). A handy regex to extract this from the `created_at` parameter could be: `\d{4}-\d{2}-\d{2}`.
```kotlin
// Add this after your MainActivity class
val riskSignals = biometricPixSDK.collectRiskSignals(accountTenure)
val userDeviceId = riskSignals.deviceId
```
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)
```curl
POST /enrollments/
```
```json
// Request Body
{
"type": "open_finance_biometric_pix",
"details": {
"customer": "{{created_customer_uuid}}",
"institution": "{{selected_institution_uuid}}",
"name": "Name for the enrollment",
"platform": "ANDROID",
"callback_url": "{{https://deeplink_to_your_application}}",
"risk_signals": {}
}
}
```
| Parameter | Type | Description |
| --- | --- | --- |
| `type` | string (enum) | The type of enrollment. For Biometric Pix, this must be set to `open_finance_biometric_pix`. |
| `details` | object | Details regarding the device enrollment. |
| `details.customer` | string (uuid) | The Belvo ID for your user. |
| `details.institution` | string (uuid) | The Belvo ID for the institution your user selected for the enrollment. |
| `details.callback_url` | string (uri) | The deeplink to where your user should be redirected to in your application after they approve the enrollment in their institutions application. Must be HTTPS compliant. |
| `details.name` | string | A human-readable name for the enrollment. |
| `details.platform` | string | The platform that this enrollment relates to. For Android devices, this must be set to `ANDROID`. |
| `details.risk_signals` | object | The `RiskSignals` object (converted to JSON) you received after using the `collectRiskSignals` method. |
Register your callback_url in assetlinks.json
The `callback_url` you provide **must** be registered in your **assetlinks.json** file under your deeplink host. For instance, if your `callback_url` is `https://deeplink.quebom.com.br/callback/`, then you must have a `https://deeplink.quebom.com.br/.well-known/assetlinks.json` file which contains a `relation` that gives permission to handle all URLs and a `target` that contains the public fingerprint. For example:
```json
[{
"relation": ["delegate_permission/common.handle_all_urls"], // [!code highlight]
"target": {
"namespace": "android_app",
"package_name": "com.quebom",
"sha256_cert_fingerprints":[ // [!code highlight]
"82:65:61:6B:CC:E3:67:46:44:83:E8:D0:88:B8:33:EE:42:47:B9:60:B4:6F:B7:43:AE:21:F2:0F:F2:4B:E9:53" // [!code highlight]
] // [!code highlight]
}
}]
```
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.
```json
// 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": "ANDROID",
"name": "First Enrollment",
"callback_url": "deeplink-to-your-application",
"redirect_url": "https://www.user-banking-institituon.com/?enrollment_request=true...", // [!code highlight]
"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.
Success Example
```json
https://redirect.clientApplication.com/
?state=
&code=
&id_token=
```
Error Example
```json
https://redirect.clientApplication.com/
?state=
&error=
&error_description=
```
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:
```json
POST /enrollments/complete-redirection/
```
Success Example
```json Success Request Body
{
"state": "{{state}}",
"code": "{{code}}",
"id_token": "{{id_token}}",
}
```
In the case that it was a successful callback, in the request response the `status` of the enrollment will still be set to `PENDING`.
```json Successful Enrollment Status Update
// 200 OK
{
"id": "{{enrollment.id}}", // [!code highlight]
"type": "open_finance_biometric_pix",
"status": "PENDING", // [!code highlight]
"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": "ANDROID",
"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}}"
}
```
The institution will now process the enrollment data and provide Belvo the FIDO Options that are required to generate the biometric challenge. You will need to poll our API to retrieve this data to then request biometric data from your user.
Error Example
```json
{
"state": "{{state}}",
"error": "{{error}}",
"error_description": "{{error_description}}"
}
```
In the case that it was a error callback, our API will still respond with a `200 - OK` with the `status` of the enrollment will still be set to `FAILED`. Additionally, the `status_reason_code` and `status_reason_message` will be set to provide more information about the failure.
```json Failed Enrollment Status Update
// 200 OK
{
"id": "{{enrollment.id}}", // [!code highlight]
"type": "open_finance_biometric_pix",
"status": "FAILED", // [!code highlight]
"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": "ANDROID",
"redirect_url": "https://example.com/redirect-enrollment/",
"risk_signals": "*******",
"status": "AWAITING_ACCOUNT_HOLDER_VALIDATION"
},
"external_id": null,
"metadata": {},
"status_reason_code": "insufficient_funds", // [!code highlight]
"status_reason_message": "No funds", // [!code highlight]
"created_by": "{{belvo_client.id}}",
"created_at": "{{timestamp}}",
"updated_at": "{{timestamp}}"
}
```
## Poll Belvo API for FIDO options (API)
Polling Tips
Send a request every two seconds until you receive a response or two minutes pass with no response. If you do not receive response after two minutes, display a “Try again” screen to your user and restart the process. In the background, the Enrollment will transition to the `status` = `FAILED`.
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.
```kotlin
GET /enrollments/{enrollment_id}/fido-registration-options/
```
You will receive the following `200 - OK` response from our API. Make sure to save the object as it is a required parameter for the `startRegistration` SDK method.
```json
// 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 (Android SDK)
With the payload received, you need to use the **startRegistration()** 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).
```kotlin
import com.belvo.biometricpixsdk.models.FidoRegistrationCallback
import com.belvo.biometricpixsdk.extensions.encodedRawId
import com.belvo.biometricpixsdk.extensions.encodedAttestationObject
import com.belvo.biometricpixsdk.extensions.encodedClientDataJSON
import com.google.android.gms.fido.fido2.api.common.PublicKeyCredential
import com.google.android.gms.fido.fido2.api.common.AuthenticatorAssertionResponse
// Method
fun startRegistration(
context: Context, //Application or activity context
fidoResponseString: String, //FIDO registration options JSON from server
callback: FidoRegistrationCallback //Registration result callback
)
// Implement the callback interface
val registrationCallback = object : FidoRegistrationCallback {
override fun onSuccess(credential: PublicKeyCredential, response: AuthenticatorAttestationResponse) {
// Handle successful registration
val credentialId = credential.encodedId
val credentialRawId = credential.encodedRawId
val attestationObject = response.encodedAttestationObject
val clientDataJson = response.encodedClientDataJSON
// Send the credential data (credentialId, credentialRawId, attestationObject, and clientDataJson)
// to your server to be then forwarded to the Belvo API to confirm the Enrollment.
}
override fun onError(error: String) {
// Handle registration error
Log.e("FIDO", "Registration failed: $error")
}
}
// Start registration with server response
biometricPixSDK.startRegistration(
context = requireContext(), // if it's used in a Fragment
fidoResponseString = fidoOptions, // Fido registration options collected from GET /enrollments/{id}/fido-registration-options/
callback = registrationCallback
)
```
You need to store the following values in variables as they are used to confirm the Enrollment in the following step:
- `credentialId`
- `credentialRawId`
- `attestationObject`
- `clientDataJson`
## 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:
```kotlin
POST /payments/br/enrollments/{enrollment_id}/confirm/
```
```json
// Request Body
{
"confirmation_data": {
"authenticatorAttachment": "platform",
"id": "{{credentialId}}",
"rawId": "{{credentialRawId}}",
"type": "public-key",
"response": {
"attestationObject": "{{attestationObject}}",
"clientDataJSON": "{{clientDataJson}}"
}
}
}
```
| Parameter | Type | Description |
| --- | --- | --- |
| `authenticatorAttachment` | string | The type of authenticator. Must be set to `platform`. |
| `id` | string | The `credentialId` you received from the `startRegistration()` method. |
| `rawId` | string | The `credentialRawId` you received from the `startRegistration()` method. |
| `type` | string | The type of FIDO credential being generated. Must be set to `public-key`. |
| `response.attestationObject` | string | The `attestationObject` you received from the `startRegistration()` method. |
| `response.clientDataJSON` | string | The `clientDataJson` you received from the `startRegistration()` method. |
Belvo will respond with a `204 - No Content` and forward the information to the institution to complete the enrollment process.
Polling Tips
Send a request every two seconds until you receive a response or two minutes pass with no response. If you do not receive response after two minutes, display a “Try again” screen to your user and restart the process. In the background, the Enrollment will transition to the `status` = `FAILED`.
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.
```bash
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
```mermaid
sequenceDiagram
autonumber
participant EndUser
participant ClientAppBackend
participant BiometricPixSDK
participant Payments
%% 1 - Payment Intent Creation using authorized enrollment
Note over EndUser,Payments: 1. User selects Enrollment (API)
EndUser ->> ClientAppBackend: Clicks "Realizar Pagamento"
ClientAppBackend ->> Payments: GET /enrollments/?device_id=1234
Payments -->> ClientAppBackend: Returns list of enrollments
ClientAppBackend -->> EndUser: Show list of enrollments
EndUser ->> ClientAppBackend: Chooses from enrollment list
Note over EndUser,Payments: 2. Create Payment Intent (API)
ClientAppBackend ->> Payments: POST /payment-intents/ (enrollment_id)
Payments -->> ClientAppBackend: Returns payment_intent data (id, fido_options)
ClientAppBackend ->> ClientAppBackend: Persist Payment Intent ID
%% 2 - Payment Intent Authorization using AttestationObject + RiskSignals
Note over EndUser,Payments: 3. Collect biometric data (SDK)
ClientAppBackend ->> BiometricPixSDK: startSign(fido_options)
ClientAppBackend ->> BiometricPixSDK: collectRiskSignals(accountTenure)
BiometricPixSDK -->> ClientAppBackend: Returns credentialId, attestationObject, clientDataJSON, riskSignals
Note over EndUser,Payments: 4. Authorize payment (API)
ClientAppBackend ->> Payments: POST /payment-intents/{id}/authorize/ (credentialId, attestationObject, clientDataJSON, riskSignals)
Payments -->> ClientAppBackend: 204 - No Content
ClientAppBackend ->> Payments: Poll GET /payment-intents/{id}/
Payments -->> ClientAppBackend: status = SUCCEEDED
ClientAppBackend ->> EndUser: Show success screen
```
## **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).
```bash
GET /enrollments/?device_id={device_id}
```
## **Create Payment Intent (API)**
Once you have the user’s selected Enrollment, you can create a Payment Intent:
```shell
POST /payments/br/payment-intents/
```
```json
{
"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
}
```
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | true | The amount to pay. |
| `allowed_payment_method_types` | string | true | The type of payment method. Must be set to `open_finance_biometric_pix`. |
| `customer` | string (uuid) | true | The `id` of the customer from whom you are requesting payments. |
| `description` | string | true | Your description for the payment. |
| `statement_description` | string | true | The description that will appear on your user’s bank account statement. |
| `payment_method_details.open_finance_biometric_pix.beneficiary_bank_account` | string (uuid) | true | The `id` of the bank account that will receive the funds. |
| `payment_method_details.open_finance_biometric_pix.enrollment` | string (uuid) | true | The `id` of the Enrollment the user selected. |
| `confirm` | boolean | true | Confirms that the payment is ready to be processed. Must be set to `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.
```json
{
"id": "uuid", // [!code highlight]
"status": "PENDING",
"payment_method_information": {
"open_finance_biometric_pix": {
"provider": "belvo",
"consent_id": "urn:nubank:023230b9-1211-3420-bf6d-e7d56e87bdf1",
"fido_options": { // [!code highlight]
"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)
You will need to use the `initialize()` method before `startSigning(fido_options)` and `collectRiskSignals(accountTenure)`. Please see the code example for more details.
Using the `fido_options` received from the payment intent, initiate the biometric authentication process using the `startSigning(fido_options)` method of the Belvo Android SDK. The result from this method will be the `credentialId`, `credentialRawId`, `authenticatorData`, `clientDataJson`, `signature` and `userHandle` values, which you will use to confirm the payment in the Authorize Payment step.
After the `startSigning(fido_options)` method, you need to call the `collectRiskSignals(accountTenure)` to collect information about the device. The returned `RiskSignals` object is then required in the Authorize Payment step.
```kotlin
import com.belvo.biometricpixsdk.BiometricPixSDK
import com.belvo.biometricpixsdk.models.FidoRegistrationCallback
import com.belvo.biometricpixsdk.extensions.encodedRawId
import com.belvo.biometricpixsdk.extensions.encodedClientDataJSON
import com.belvo.biometricpixsdk.extensions.encodedAuthenticatorData
import com.belvo.biometricpixsdk.extensions.encodedSignature
import com.belvo.biometricpixsdk.extensions.encodedUserHandle
import com.google.android.gms.fido.fido2.api.common.PublicKeyCredential
import com.google.android.gms.fido.fido2.api.common.AuthenticatorAssertionResponse
class ExampleActivity : ComponentActivity() {
private lateinit var biometricPixSDK: BiometricPixSDK
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
biometricPixSDK = BiometricPixSDK()
// Create the FIDO launcher with the SDK's activity result callback
val fidoLauncher = registerForActivityResult(
ActivityResultContracts.StartIntentSenderForResult(),
biometricPixSDK.createActivityResultCallback() // This lambda handles all FIDO activity results
)
// Initialize SDK with the configured launcher
biometricPixSDK.initialize(fidoLauncher)
}
fun startAuthenticationProcess(fidoOptions: String) {
// Implement the callback interface
val signingCallback = object : FidoAuthenticationCallback {
override fun onSuccess(credential: PublicKeyCredential, response: AuthenticatorAssertionResponse) {
// Handle successful authentication
val credentialId = credential.encodedId
val credentialRawId = credential.encodedRawId
val authenticatorData = response.encodedAuthenticatorData
val clientDataJson = response.encodedClientDataJSON
val signature = response.encodedSignature
val userHandle = response.encodedUserHandle
// Send the credential data to your server to be forwarded to the Belvo API
// to confirm the authentication
}
override fun onError(error: String) {
// Handle authentication error
Log.e("FIDO", "Signing failed: $error")
}
}
// Start authentication with server response
biometricPixSDK.startSigning(
context = this,
fidoResponseString = fidoOptions,
callback = signingCallback
)
}
override fun onDestroy() {
super.onDestroy()
biometricPixSDK.cleanup()
}
}
```
## Authorize Payment (API)
After retrieving all the required information in the Collect Biometric Data and Risk Signals (SDK) step, you can now authorize the payment using Belvo's API.
```shell
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.
```json
// POST /payment-intents/{id}/authorize/ Request Body Example
{
"risk_signals": {}, // The Risk Signals object collected
"assertion": {
"authenticatorAttachment": "platform",
"id": "{{credentialId}}",
"rawId": "{{credentialRawId}}",
"response": {
"authenticatorData": "{{authenticatorData}}",
"clientDataJSON": "{{clientDataJSON}}",
"signature:": "{{signature}}",
"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:
```shell
GET /payment-intents/{payment_intent_id}/
```
Polling Tips
Send a request every two seconds until you receive a response or two minutes pass with no response. If you do not receive response after two minutes, display a “Try again” screen to your user and restart the process. In the background, the Payment Intent and associated Charge will transition to the `status` = `FAILED`.