# Guia do Biometric Pix (Usando Android SDK)
Próximo Lançamento
Esta documentação cobre recursos do nosso próximo lançamento. Embora a funcionalidade principal e o fluxo de trabalho descritos aqui permaneçam inalterados, você pode notar algumas melhorias antes do lançamento final, como:
- Atualizações e otimizações do Android SDK
- Melhorias na documentação (links, terminologia, diagramas)
- Atualizações de referência da API para endpoints de inscrição
Com o Biometric Pix da Belvo, coletar pagamentos de usuários se torna simples, eliminando a necessidade de os usuários navegarem até sua instituição financeira para aprovar cada solicitação de pagamento individual.
O primeiro passo para habilitar a coleta de pagamentos biométricos é **inscrever** o dispositivo do usuário com sua instituição. Durante a inscrição, dados chave sobre o dispositivo e as credenciais de chave pública do usuário são registrados de forma segura com sua instituição, garantindo que pagamentos futuros possam ser confirmados apenas com autenticação biométrica.
Uma vez que a inscrição esteja completa, você pode começar a solicitar pagamentos diretamente do dispositivo do usuário.
Neste guia, vamos conduzi-lo por cada etapa, desde a inscrição do dispositivo até a iniciação bem-sucedida de uma solicitação de pagamento em um dispositivo Android.
## Pré-requisitos
Antes de continuar com este guia, certifique-se de que:
1. Você gerou suas Chaves de API de Pagamentos Belvo
2. Configurou Webhooks
3. Instalou o Belvo Android SDK
- Instalando o Belvo Android SDK
**Requisitos Mínimos**
- **Android SDK**: API 31 (Android 12) ou superior
- **Compile SDK**: 35
- **Versão Java**: 11
- **Kotlin**: Compatível com a versão estável mais recente
**Instruções**
Para instalar o Belvo Android SDK, adicione as seguintes dependências do SDK ao seu `build.gradle.kts` no nível do aplicativo:
```kotlin
dependencies {
implementation("com.belvo.biometricpixsdk:biometricpixsdk:1.0.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}
```
Além disso, você precisará adicionar as seguintes permissões ao seu arquivo AndroidManifest.xml:
```xml
```
4. Habilitou o compartilhamento de credenciais com a Belvo
- Habilitando o compartilhamento de credenciais
Para completar a integração do Belvo Android SDK e habilitar o compartilhamento seguro de credenciais entre seu aplicativo e o domínio da Belvo (`belvo.com`), precisamos configurar um **Digital Asset Link**.
Esta configuração cria uma conexão confiável entre seu aplicativo e `belvo.com`, permitindo que seu aplicativo acesse com segurança recursos do SDK da Belvo, como registro de Inscrição do usuário e Autorização de Intenção de Pagamento. Esses dados correspondem à **seção `target`** de uma entrada de [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started#quick-usage-example). Usamos esses dados para atualizar nosso arquivo `assetlinks.json` hospedado em: `https://belvo.com/.well-known/assetlinks.json`
Você precisará nos fornecer as seguintes informações do seu aplicativo:
- O **nome do pacote** do seu aplicativo
- A **impressão digital do certificado de assinatura SHA-256** do seu aplicativo (veja a [documentação oficial do Android sobre como recuperar essa impressão digital](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc)).
Um exemplo do seu objeto target deve se parecer com isto:
```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. Compartilhou o **FACETID** do seu aplicativo com a Belvo. Para detalhes sobre como gerar o FACETID do seu aplicativo, consulte nosso guia de Geração de FACETID (Android SDK) dedicado.
6. Além disso, para cada usuário que você deseja inscrever no sistema Biometric Pix, você **primeiro precisará criar um Cliente Belvo.**
## Inscrição
A inscrição é o processo de registrar o dispositivo de um usuário em sua instituição para permitir pagamentos biométricos para um determinado comerciante. Durante o processo, você usará uma **combinação** do Belvo Payments Android SDK e API para recuperar detalhes chave sobre o dispositivo, bem como os dados públicos biométricos.
1. **Listar Instituições:** Solicite ao usuário que selecione sua instituição financeira desejada para se inscrever, usando a API da Belvo para exibir as opções disponíveis.
2. **Inicializar SDK e Coletar Sinais de Risco:** Inicialize o Belvo Android SDK, solicite ao usuário as permissões necessárias e colete sinais de risco, incluindo o ID do dispositivo.
3. **Criar e Atualizar Inscrição:** Envie os sinais de risco coletados, juntamente com o ID do cliente, ID da instituição e uma URL de callback, para o servidor da Belvo para criar a inscrição. Em seguida, redirecione o usuário para o aplicativo de sua instituição para aprovação. Uma vez que eles sejam redirecionados de volta para sua URL de callback com detalhes, envie-os para a Belvo para atualizar o estado da inscrição.
4. **Consultar Opções FIDO:** Consulte continuamente a API da Belvo (`GET /enrollments/{id}/fido-registration-options/`) para recuperar as opções FIDO necessárias para o registro biométrico.
⚠️ **Estratégia de Consulta:** Recomendamos consultar nosso servidor a cada dois segundos por até dois minutos. Se nenhuma resposta for recebida dentro desse período, instrua o usuário a tentar novamente.
5. **Solicitar Biometria:** Pegue as opções FIDO da API da Belvo e use o método `startRegistration()` do Belvo Android SDK para solicitar ao usuário seu gesto biométrico.
6. **Finalizar Inscrição:** Envie os dados públicos biométricos para a Belvo usando `POST /enrollments/{id}/confirm/`. Depois disso, consulte `GET /enrollments/{id}/` até que uma resposta seja recebida (status da inscrição = `SUCCEEDED` ou `FAILED`).
```mermaid
sequenceDiagram
autonumber
participant EndUser
participant ClientAppBackend
participant BiometricPixSDK
participant Payments
participant BankAPP
Note over EndUser,BankAPP: 0. Solicite ao usuário que selecione a instituição para se inscrever (API da Belvo)
ClientAppBackend ->> Payments: /institutions/
Payments -->> ClientAppBackend: Lista de instituições
ClientAppBackend ->> EndUser: Exibir lista de instituições
EndUser -->> ClientAppBackend: Instituição selecionada
Note over EndUser,BankAPP: 1. Inicializar SDK e Coletar Sinais de Risco (Android SDK)
ClientAppBackend ->> BiometricPixSDK: initialize()
BiometricPixSDK ->> EndUser: requestPermission()
EndUser -->> BiometricPixSDK: Concede permissão para coletar sinais de risco
ClientAppBackend ->> BiometricPixSDK: collectRiskSignals(accountTenure)
BiometricPixSDK -->> ClientAppBackend: Retorna riskSignals + deviceId (criptografado)
ClientAppBackend ->> ClientAppBackend: Persiste deviceId (criptografado)
Note over EndUser,BankAPP: 2. Enviar Sinais de Risco para a Belvo (API da Belvo)
ClientAppBackend ->> Payments: POST /enrollments/ (riskSignals, callback_url)
Payments -->> ClientAppBackend: 201 Created (enrollment_id, redirect_url)
ClientAppBackend ->> ClientAppBackend: Persiste enrollment_id associado com deviceId (criptografado)
Note over EndUser,BankAPP: 3. Redirecionar usuário para seu APP e atualizar inscrição
ClientAppBackend ->> EndUser: Redirecionar para BankAPP (usando o redirect_url)
EndUser ->> BankAPP: Aprova inscrição
BankAPP ->> ClientAppBackend: Instituição redireciona para callback_url com detalhes nos parâmetros de consulta
ClientAppBackend ->> Payments: Atualizar inscrição com valores recebidos usando POST /enrollments/complete-redirection/
Payments -->> ClientAppBackend: Retorna payload de Inscrição atualizada
Note over EndUser,BankAPP: 4. Consultar API da Belvo para opções FIDO
ClientAppBackend ->> Payments: Consultar GET /enrollments/{id}/fido-registration-options/
Payments -->> ClientAppBackend: Retorna fido_options
Note over EndUser,BankAPP: 5. Solicitar Biometria (Android SDK)
ClientAppBackend ->> BiometricPixSDK: startRegistration(fido_options)
BiometricPixSDK ->> EndUser: Solicitar dados biométricos
EndUser -->> BiometricPixSDK: Fornece biometria (rosto/impressão digital/PIN)
BiometricPixSDK -->> ClientAppBackend: attestationObject, clientDataJSON, credential
Note over EndUser,BankAPP: 6. Enviar biometria para finalizar inscrição e consultar resposta
ClientAppBackend ->> Payments: POST /enrollments/{id}/confirm/ (attestationObject, clientDataJSON, credential)
Payments -->> ClientAppBackend: 204 - No Content
ClientAppBackend ->> Payments: Consultar GET /enrollments/{id}/
Payments -->> ClientAppBackend: status = SUCCEEDED
```
## Peça ao usuário para selecionar a instituição para se inscrever (Belvo API)
Em seu aplicativo, peça ao seu usuário para selecionar a instituição onde deseja inscrever o dispositivo. Use a solicitação List all payment institutions para obter uma lista de todas as possíveis instituições. Assim que o usuário selecionar a instituição, salve o id da instituição (necessário na etapa Enviar Sinais de Risco para Belvo (API)).
## Inicializar SDK e Coletar Sinais de Risco (SDK Android)
Em seguida, no seu aplicativo, você precisará fazer as seguintes chamadas:
### initialize()
Este método deve ser chamado no método `onCreate()` do seu `Activity` antes de qualquer operação FIDO. Você deve usar `createActivityResultCallback()` para obter a função de callback adequada para o parâmetro `fidoLauncher`.
O método `initialize(fidoLauncher)` configura o tratamento interno de resultados de atividades necessário para operações biométricas FIDO2. Ele deve ser chamado uma vez durante o ciclo de vida da atividade para preparar o SDK para iniciar prompts biométricos e receber seus resultados.
No exemplo abaixo, você pode ver que na variável `fidoLauncher` também usamos o `createActivityResultCallback()` do SDK Android da Belvo. Este método retorna uma função de callback que deve ser usada ao registrar o `ActivityResultLauncher` para operações FIDO. Ele atua como o manipulador interno do SDK para processar os objetos `ActivityResult` recebidos de atividades do sistema iniciadas pelo fluxo FIDO. Isso permite que o SDK gerencie o estado das operações biométricas de forma contínua.
```kotlin
class MainActivity : ComponentActivity() {
private lateinit var biometricPixSDK: BiometricPixSDK
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
biometricPixSDK = BiometricPixSDK()
// Use createActivityResultCallback() ao configurar o launcher.
// Esta função lambda será usada internamente pelo SDK para processar resultados FIDO.
val fidoLauncher = registerForActivityResult(
ActivityResultContracts.StartIntentSenderForResult(),
biometricPixSDK.createActivityResultCallback() // Esta lambda lida com todos os resultados de atividades FIDO
)
// Inicialize o SDK com o launcher configurado
biometricPixSDK.initialize(fidoLauncher)
}
}
```
Uma vez que você tenha inicializado o launcher, podemos prosseguir para solicitar a permissão do usuário para extrair sinais de risco do dispositivo usando o método `requestPermission()`.
### requestPermission()
Este método `requestPermission()` cria e inicia uma solicitação de permissão para permissões de localização e estado do telefone (`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` e `READ_PHONE_STATE`). Ele lida automaticamente com o fluxo de solicitação de permissão em tempo de execução do Android e fornece um callback com o resultado geral. O método retorna `ActivityResultLauncher>`: A instância do permission launcher. Embora seja retornado, normalmente você pode ignorar este valor de retorno, pois a interação principal é através do callback `onResult` após chamar a função.
```kotlin
// Adicione isso ao seu MainActivity
biometricPixSDK.requestPermission(this) { granted ->
if (granted) {
// Todas as permissões necessárias concedidas. O SDK está pronto para funcionalidade completa.
Log.d("BiometricSDK", "Todas as permissões necessárias concedidas.")
} else {
// Lidar com permissões negadas.
// Informe o usuário sobre recursos que podem estar indisponíveis ou guie-os para as configurações.
Log.e("BiometricSDK", "Permissões negadas. A funcionalidade do SDK pode ser limitada.")
}
```
Quando o usuário concede sua permissão, você pode então extrair os sinais de risco do dispositivo usando `collectRiskSignals(accountTenure)`.
### collectRiskSignals(accountTenure)
O método `collectRiskSignals(accountTenure)` coleta dados abrangentes de impressão digital do dispositivo e sinais de segurança. Os dados coletados incluem ID do dispositivo, status de segurança, informações de hardware e sinais comportamentais, que são cruciais para a instituição realizar avaliação de risco e detecção de fraude. O método retorna um objeto RiskSignals que você precisa salvar e encaminhar para os servidores da Belvo em uma chamada de API. Além disso, você precisa persistir o valor de `deviceId` que o objeto RiskSignals retorna para que mais tarde você possa associá-lo ao ID de Inscrição (posteriormente, ao listar Inscrições, você precisa fornecer o `deviceID` para receber todas as Inscrições).
Parâmetro accountTenure
No argumento `accountTenure`, você deve passar a data em que o usuário foi criado como um Cliente na API da Belvo, no formato `YYYY-MM-DD`.
Isso é derivado do timestamp created_at do Cliente, no entanto, você só precisa enviar os primeiros 10 caracteres correspondentes ao ano, mês e data (`YYYY-MM-DD`). Uma regex útil para extrair isso do parâmetro `created_at` poderia ser: `\d{4}-\d{2}-\d{2}`.
```kotlin
// Adicione isso após sua classe MainActivity
val riskSignals = biometricPixSDK.collectRiskSignals(accountTenure)
val userDeviceId = riskSignals.deviceId
```
Depois de ter os sinais de risco e o ID do dispositivo, você pode encaminhar essas informações para a Belvo usando o método Create Enrollment.
## Criar Inscrição Usando Sinais de Risco (API)
```curl
POST /enrollments/
```
```json
// Corpo da Requisição
{
"type": "open_finance_biometric_pix",
"details": {
"customer": "{{created_customer_uuid}}",
"institution": "{{selected_institution_uuid}}",
"name": "Nome para a inscrição",
"platform": "ANDROID",
"callback_url": "{{https://deeplink_to_your_application}}",
"risk_signals": {}
}
}
```
| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `type` | string (enum) | O tipo de inscrição. Para Biometric Pix, isso deve ser definido como `open_finance_biometric_pix`. |
| `details` | object | Detalhes sobre a inscrição do dispositivo. |
| `details.customer` | string (uuid) | O ID Belvo para o seu usuário. |
| `details.institution` | string (uuid) | O ID Belvo para a instituição que seu usuário selecionou para a inscrição. |
| `details.callback_url` | string (uri) | O deeplink para onde seu usuário deve ser redirecionado em seu aplicativo após aprovar a inscrição no aplicativo da instituição. Deve ser compatível com HTTPS. |
| `details.name` | string | Um nome legível para a inscrição. |
| `details.platform` | string | A plataforma à qual esta inscrição se refere. Para dispositivos Android, isso deve ser definido como `ANDROID`. |
| `details.risk_signals` | object | O objeto `RiskSignals` (convertido para JSON) que você recebeu após usar o método `collectRiskSignals`. |
Registre seu callback_url no assetlinks.json
O `callback_url` que você fornecer **deve** ser registrado no seu arquivo **assetlinks.json** sob o host do seu deeplink. Por exemplo, se o seu `callback_url` for `https://deeplink.quebom.com.br/callback/`, então você deve ter um arquivo `https://deeplink.quebom.com.br/.well-known/assetlinks.json` que contém uma `relation` que dá permissão para lidar com todas as URLs e um `target` que contém a impressão digital pública. Por exemplo:
```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]
}
}]
```
No payload de resposta, você receberá um `redirect_url` que precisa ser exibido para o seu usuário para que ele possa ser redirecionado para a instituição e confirmar sua inscrição.
```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": "*****"
}
}
```
## Redirecionar o usuário para o APP e atualizar a inscrição
Agora você precisa redirecionar seu usuário para a instituição dele usando o `redirect_url` para que ele possa confirmar o processo de inscrição. Durante o processo, ele fará login na instituição, revisará a solicitação de inscrição e, em seguida, a autorizará. Uma vez que o usuário autoriza a inscrição, a instituição o redirecionará de volta para o `callback_url` que você forneceu.
Exemplo de Sucesso
```json
https://redirect.clientApplication.com/
?state=
&code=
&id_token=
```
Exemplo de Erro
```json
https://redirect.clientApplication.com/
?state=
&error=
&error_description=
```
A instituição passará dados nos parâmetros de consulta que você deve encaminhar para a Belvo usando a solicitação da **API de Atualização do Estado de Inscrição**. Recomendamos transformar os parâmetros de consulta em um objeto JSON e enviá-lo diretamente para a Belvo.
## Atualizar Estado da Inscrição
Com o valor da string de consulta salvo como um objeto JSON, você pode fazer a seguinte solicitação:
```json
POST /enrollments/complete-redirection/
```
Exemplo de Sucesso
```json Corpo da Solicitação de Sucesso
{
"state": "{{state}}",
"code": "{{code}}",
"id_token": "{{id_token}}",
}
```
No caso de um callback bem-sucedido, na resposta da solicitação o `status` da inscrição ainda será definido como `PENDING`.
```json Atualização de Status de Inscrição Bem-Sucedida
// 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}}"
}
```
A instituição agora processará os dados de inscrição e fornecerá à Belvo as Opções FIDO necessárias para gerar o desafio biométrico. Você precisará consultar nossa API para recuperar esses dados e então solicitar dados biométricos do seu usuário.
Exemplo de Erro
```json
{
"state": "{{state}}",
"error": "{{error}}",
"error_description": "{{error_description}}"
}
```
No caso de um callback de erro, nossa API ainda responderá com um `200 - OK` com o `status` da inscrição ainda definido como `FAILED`. Além disso, o `status_reason_code` e o `status_reason_message` serão definidos para fornecer mais informações sobre a falha.
```json Atualização de Status de Inscrição Falha
// 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}}"
}
```
## Consultar a API da Belvo para opções FIDO (API)
Dicas de Polling
Envie uma solicitação a cada dois segundos até receber uma resposta ou até que passem dois minutos sem resposta. Se você não receber uma resposta após dois minutos, exiba uma tela de “Tente novamente” para o seu usuário e reinicie o processo. Em segundo plano, o Enrollment será alterado para `status` = `FAILED`.
Após receber a resposta bem-sucedida da solicitação **Update Enrollment State**, você precisa consultar o endpoint abaixo para receber as opções de registro FIDO necessárias para solicitar dados biométricos.
```kotlin
GET /enrollments/{enrollment_id}/fido-registration-options/
```
Você receberá a seguinte resposta `200 - OK` da nossa API. Certifique-se de salvar o objeto, pois ele é um parâmetro necessário para o método `startRegistration` do SDK.
```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 para Biometrics (Android SDK)
Com o payload recebido, você precisa usar o método **startRegistration()**. Este método inicia o registro de credenciais biométricas usando protocolos FIDO2. Ele processa as opções de registro FIDO (uma string JSON) recebidas do seu servidor backend e inicia o fluxo de autenticação biométrica nativa do dispositivo (por exemplo, impressão digital ou reconhecimento facial).
```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
// Método
fun startRegistration(
context: Context, //Contexto da aplicação ou atividade
fidoResponseString: String, //Opções de registro FIDO JSON do servidor
callback: FidoRegistrationCallback //Callback do resultado do registro
)
// Implementar a interface de callback
val registrationCallback = object : FidoRegistrationCallback {
override fun onSuccess(credential: PublicKeyCredential, response: AuthenticatorAttestationResponse) {
// Lidar com o registro bem-sucedido
val credentialId = credential.encodedId
val credentialRawId = credential.encodedRawId
val attestationObject = response.encodedAttestationObject
val clientDataJson = response.encodedClientDataJSON
// Enviar os dados da credencial (credentialId, credentialRawId, attestationObject e clientDataJson)
// para o seu servidor para então serem encaminhados para a API da Belvo para confirmar a Inscrição.
}
override fun onError(error: String) {
// Lidar com erro de registro
Log.e("FIDO", "Falha no registro: $error")
}
}
// Iniciar registro com resposta do servidor
biometricPixSDK.startRegistration(
context = requireContext(), // se for usado em um Fragment
fidoResponseString = fidoOptions, // Opções de registro Fido coletadas de GET /enrollments/{id}/fido-registration-options/
callback = registrationCallback
)
```
Você precisa armazenar os seguintes valores em variáveis, pois eles são usados para confirmar a Inscrição na etapa seguinte:
- `credentialId`
- `credentialRawId`
- `attestationObject`
- `clientDataJson`
## Enviar biometria para finalizar o cadastro e verificar a resposta (API)
Para completar o processo de Cadastro, você precisará enviar os valores que recebeu para o seguinte endpoint:
```kotlin
POST /payments/br/enrollments/{enrollment_id}/confirm/
```
```json
// Corpo da Requisição
{
"confirmation_data": {
"authenticatorAttachment": "platform",
"id": "{{credentialId}}",
"rawId": "{{credentialRawId}}",
"type": "public-key",
"response": {
"attestationObject": "{{attestationObject}}",
"clientDataJSON": "{{clientDataJson}}"
}
}
}
```
| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `authenticatorAttachment` | string | O tipo de autenticador. Deve ser definido como `platform`. |
| `id` | string | O `credentialId` que você recebeu do método `startRegistration()`. |
| `rawId` | string | O `credentialRawId` que você recebeu do método `startRegistration()`. |
| `type` | string | O tipo de credencial FIDO sendo gerada. Deve ser definido como `public-key`. |
| `response.attestationObject` | string | O `attestationObject` que você recebeu do método `startRegistration()`. |
| `response.clientDataJSON` | string | O `clientDataJson` que você recebeu do método `startRegistration()`. |
A Belvo responderá com um `204 - No Content` e encaminhará a informação para a instituição para completar o processo de cadastro.
Dicas de Verificação
Envie uma requisição a cada dois segundos até receber uma resposta ou até que passem dois minutos sem resposta. Se você não receber uma resposta após dois minutos, exiba uma tela de “Tente novamente” para o seu usuário e reinicie o processo. Em segundo plano, o Cadastro irá transitar para o `status` = `FAILED`.
Você precisará verificar o seguinte endpoint até receber uma resposta da API da Belvo. Assim que receber uma resposta, verifique o campo `status`.
```bash
GET /enrollments/{enrollment_id}/
```
Se o `status` for `SUCCEEDED`, perfeito! O cadastro está pronto e você pode começar a fazer pagamentos!
## Realizando um Pagamento
Uma vez que o dispositivo de um usuário está registrado com sucesso, você pode iniciar solicitações de pagamento usando suas credenciais biométricas armazenadas. Este processo envolve:
1. Selecionar um Registro
2. Criar uma intenção de pagamento
3. Coletar dados de autenticação biométrica
4. Autorizar o pagamento
```mermaid
sequenceDiagram
autonumber
participant EndUser
participant ClientAppBackend
participant BiometricPixSDK
participant Payments
%% 1 - Criação de Intenção de Pagamento usando registro autorizado
Note over EndUser,Payments: 1. Usuário seleciona Registro (API)
EndUser ->> ClientAppBackend: Clica "Realizar Pagamento"
ClientAppBackend ->> Payments: GET /enrollments/?device_id=1234
Payments -->> ClientAppBackend: Retorna lista de registros
ClientAppBackend -->> EndUser: Mostra lista de registros
EndUser ->> ClientAppBackend: Escolhe da lista de registros
Note over EndUser,Payments: 2. Criar Intenção de Pagamento (API)
ClientAppBackend ->> Payments: POST /payment-intents/ (enrollment_id)
Payments -->> ClientAppBackend: Retorna dados de payment_intent (id, fido_options)
ClientAppBackend ->> ClientAppBackend: Persiste ID da Intenção de Pagamento
%% 2 - Autorização de Intenção de Pagamento usando AttestationObject + RiskSignals
Note over EndUser,Payments: 3. Coletar dados biométricos (SDK)
ClientAppBackend ->> BiometricPixSDK: startSign(fido_options)
ClientAppBackend ->> BiometricPixSDK: collectRiskSignals(accountTenure)
BiometricPixSDK -->> ClientAppBackend: Retorna credentialId, attestationObject, clientDataJSON, riskSignals
Note over EndUser,Payments: 4. Autorizar pagamento (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: Mostra tela de sucesso
```
## **Selecionar Inscrição (API)**
Use o método de API Listar todas as inscrições, com o parâmetro de consulta obrigatório `device_id`, para solicitar todas as inscrições que seu usuário fez usando seu aplicativo e seu dispositivo atual. Exiba esta lista de inscrições para o usuário, permitindo que ele escolha qual inscrição usar para o pagamento. Salve o `id` dessa inscrição (usado na próxima etapa Criar Intenção de Pagamento).
```bash
GET /enrollments/?device_id={device_id}
```
## **Criar Payment Intent (API)**
Uma vez que você tenha a Enrollment selecionada pelo usuário, você pode criar um 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
}
```
| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `amount` | número | sim | O valor a ser pago. |
| `allowed_payment_method_types` | string | sim | O tipo de método de pagamento. Deve ser definido como `open_finance_biometric_pix`. |
| `customer` | string (uuid) | sim | O `id` do cliente de quem você está solicitando pagamentos. |
| `description` | string | sim | Sua descrição para o pagamento. |
| `statement_description` | string | sim | A descrição que aparecerá no extrato bancário do seu usuário. |
| `payment_method_details.open_finance_biometric_pix.beneficiary_bank_account` | string (uuid) | sim | O `id` da conta bancária que receberá os fundos. |
| `payment_method_details.open_finance_biometric_pix.enrollment` | string (uuid) | sim | O `id` da Enrollment que o usuário selecionou. |
| `confirm` | booleano | sim | Confirma que o pagamento está pronto para ser processado. Deve ser definido como `true`. |
Na resposta, a Belvo retornará o `payment_intent.id` e o objeto `fido_options` que são necessários para o próximo passo da autenticação biométrica. Você precisa:
- Persistir o `payment_intent.id` no seu backend.
- Salvar o `fido_options` em uma variável para ser usado no próximo passo no SDK da Belvo.
```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"
}
}
}
```
## Coletar Dados Biométricos e Sinais de Risco (SDK)
Você precisará usar o método `initialize()` antes de `startSigning(fido_options)` e `collectRiskSignals(accountTenure)`. Por favor, veja o exemplo de código para mais detalhes.
Usando o `fido_options` recebido da intenção de pagamento, inicie o processo de autenticação biométrica usando o método `startSigning(fido_options)` do Belvo Android SDK. O resultado deste método será os valores `credentialId`, `credentialRawId`, `authenticatorData`, `clientDataJson`, `signature` e `userHandle`, que você usará para confirmar o pagamento na etapa Autorizar Pagamento.
Após o método `startSigning(fido_options)`, você precisa chamar o `collectRiskSignals(accountTenure)` para coletar informações sobre o dispositivo. O objeto `RiskSignals` retornado é então necessário na etapa Autorizar Pagamento.
```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()
// Crie o lançador FIDO com o callback de resultado de atividade do SDK
val fidoLauncher = registerForActivityResult(
ActivityResultContracts.StartIntentSenderForResult(),
biometricPixSDK.createActivityResultCallback() // Esta lambda lida com todos os resultados de atividade FIDO
)
// Inicialize o SDK com o lançador configurado
biometricPixSDK.initialize(fidoLauncher)
}
fun startAuthenticationProcess(fidoOptions: String) {
// Implemente a interface de callback
val signingCallback = object : FidoAuthenticationCallback {
override fun onSuccess(credential: PublicKeyCredential, response: AuthenticatorAssertionResponse) {
// Lide com a autenticação bem-sucedida
val credentialId = credential.encodedId
val credentialRawId = credential.encodedRawId
val authenticatorData = response.encodedAuthenticatorData
val clientDataJson = response.encodedClientDataJSON
val signature = response.encodedSignature
val userHandle = response.encodedUserHandle
// Envie os dados de credenciais para o seu servidor para serem encaminhados para a Belvo API
// para confirmar a autenticação
}
override fun onError(error: String) {
// Lide com o erro de autenticação
Log.e("FIDO", "Falha na assinatura: $error")
}
}
// Inicie a autenticação com a resposta do servidor
biometricPixSDK.startSigning(
context = this,
fidoResponseString = fidoOptions,
callback = signingCallback
)
}
override fun onDestroy() {
super.onDestroy()
biometricPixSDK.cleanup()
}
}
```
## Autorizar Pagamento (API)
Após obter todas as informações necessárias na etapa Coletar Dados Biométricos e Sinais de Risco (SDK), você pode agora autorizar o pagamento usando a API da Belvo.
```shell
POST /payment-intents/{payment_intent_id}/authorize/
```
- A Belvo processará a autorização. Você precisará fazer polling em `GET /payment-intents/{id}/` até que o `status` da intenção de pagamento se torne `SUCCEEDED`.
**Estratégia de Polling:** Semelhante ao cadastro, recomendamos fazer polling do status da intenção de pagamento (`GET /payment-intents/{payment_intent_id}/`) a cada dois segundos por até dois minutos até que o status seja `SUCCEEDED`. Se o status não mudar ou ocorrer um erro, informe o usuário e sugira tentar novamente.
- Uma vez que o pagamento for bem-sucedido, exiba uma tela de confirmação para o Usuário Final.
```json
// Exemplo de Corpo de Requisição POST /payment-intents/{id}/authorize/
{
"risk_signals": {}, // O objeto de Sinais de Risco coletado
"assertion": {
"authenticatorAttachment": "platform",
"id": "{{credentialId}}",
"rawId": "{{credentialRawId}}",
"response": {
"authenticatorData": "{{authenticatorData}}",
"clientDataJSON": "{{clientDataJSON}}",
"signature:": "{{signature}}",
"userHandle": "{{userHandle}}"
},
"type": "public-key"
}
}
```
A API da Belvo retornará um `204 - Not Content`. Após isso, você precisará fazer polling no seguinte endpoint para obter o status final do pagamento:
```shell
GET /payment-intents/{payment_intent_id}/
```
Dicas de Polling
Envie uma requisição a cada dois segundos até receber uma resposta ou até que passem dois minutos sem resposta. Se você não receber uma resposta após dois minutos, exiba uma tela de “Tente novamente” para o seu usuário e reinicie o processo. Em segundo plano, a Intenção de Pagamento e a Cobrança associada irão transitar para o `status` = `FAILED`.