Guia do Biometric Pix (Usando Android SDK)
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:
Você gerou suas Chaves de API de Pagamentos Belvo
Configurou Webhooks
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: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:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" />
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.Por que isso é necessário?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 de usuário e Autorização de Intenção de Pagamento. Esses dados correspondem à seçãotarget
de uma entrada de Digital Asset Links. Usamos esses dados para atualizar nosso arquivoassetlinks.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 (consulte a documentação oficial do Android sobre como recuperar essa impressão digital).
Um exemplo do seu objeto alvo deve se parecer com isto:
{ "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" ] }
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.
- Listar Instituições: Solicite ao usuário que selecione sua instituição financeira desejada para se inscrever, usando a Belvo API para exibir as opções disponíveis.
- 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.
- 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.
- Consultar Opções FIDO: Consulte continuamente a Belvo API (
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. - 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. - Finalizar Inscrição: Envie os dados públicos biométricos para a Belvo usando
POST /enrollments/{id}/confirm/
. Depois disso, consulteGET /enrollments/{id}/
até que uma resposta seja recebida (status da inscrição =SUCCEEDED
ouFAILED
).
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.
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<Array<String>>
: 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.
// Adicione isso ao seu MainActivity
biometricPixSDK.requestPermission(this) { granted ->
if (granted) {
// Todas as permissões necessárias foram concedidas. O SDK está pronto para funcionalidade completa.
Log.d("BiometricSDK", "Todas as permissões necessárias foram 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()
.
collectRiskSignals()
O método collectRiskSignals()
reúne 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).
// Adicione isso após sua classe MainActivity
val riskSignals = biometricPixSDK.collectRiskSignals(this)
val userDeviceId = riskSignals.deviceId
Depois de obter os sinais de risco e o ID do dispositivo, você pode encaminhar essas informações para a Belvo usando o método Create Enrollment.
Enviar Sinais de Risco para Belvo (API)
POST /enrollments/
// 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 da Belvo para o seu usuário. |
details.institution | string (uuid) | O ID da 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 . |
No payload de resposta, você receberá um redirect_url
que precisa ser exibido para seu usuário para que ele possa ser redirecionado para sua instituição para confirmar sua inscrição.
// 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...",
"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.
https://redirect.clientApplication.com/
?state=<state>
&code=<code>
&id_token=<long_id_token>
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:
PATCH /enrollments/callback/
{
"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
.
// 200 OK
{
"id": "uuid",
"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": "BROWSER",
"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": "uuid",
"created_at": <datetime>,
"updated_at": <datetime>
}
A instituição agora processará os dados da 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, em seguida, solicitar dados biométricos do seu usuário.
Consultar a API da Belvo para opções FIDO (API)
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 irá transitar para o state
= 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.
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.
// 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)
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).
import com.belvo.biometricpixsdk.models.FidoRegistrationCallback
import com.belvo.biometricpixsdk.extensions.encodedId
import com.belvo.biometricpixsdk.extensions.encodedRawId
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 registro bem-sucedido
val credentialId = credential.encodedId
val credentialRawId = credential.encodedRawId
val attestationObject = response.attestationObject
val clientDataJson = response.clientDataJSON
// 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:
POST /payments/br/enrollments/{enrollment_id}/confirm/
// 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.
Envie uma solicitação a cada dois segundos até receber uma resposta ou dois minutos se passarem 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 state
= FAILED
.
Você precisará verificar o seguinte endpoint até receber uma resposta da API da Belvo. Assim que receber uma resposta, verifique o campo status
.
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:
- Selecionar um Registro
- Criar uma intenção de pagamento
- Coletar dados de autenticação biométrica
- Autorizar o pagamento
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).
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:
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
}
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.
{
"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"
}
}
}
Coletar Dados Biométricos e Sinais de Risco (SDK)
Você precisará usar o método initialize()
antes de startSigning(fido_options)
e collectRiskSignals()
. 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()
para coletar informações sobre o dispositivo. O objeto RiskSignals
retornado é então necessário na etapa Autorizar Pagamento.
import com.belvo.biometricpixsdk.BiometricPixSDK
import com.belvo.biometricpixsdk.models.FidoRegistrationCallback
import com.belvo.biometricpixsdk.extensions.encodedId
import com.belvo.biometricpixsdk.extensions.encodedRawId
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 API da Belvo
// 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 recuperar 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.
POST /payment-intents/{payment_intent_id}/authorize/
A Belvo processará a autorização. Você precisará fazer polling em
GET /payment-intents/{id}/
até que ostatus
da intenção de pagamento se torneSUCCEEDED
.Estratégia de Polling: Similar ao cadastro, recomendamos fazer polling do status da intenção de pagamento (
GET /payment-intents/{payment_intent_is}/
) a cada dois segundos por até dois minutos até que o status sejaSUCCEEDED
. 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.
// POST /payment-intents/{id}/authorize/ Exemplo de Corpo de Requisição
{
"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 recuperar o status final do pagamento:
GET /payment-intents/{payment_intent_id}/
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 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 state
= FAILED
.