Pix Biometria Guide (Android SDK - Simplified Integration)

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter insights do ChatGPT
• Abrir no Claude

  Obter insights do Claude
• Conectar ao Cursor

  Instalar servidor MCP no Cursor
• Conectar ao VS Code

  Instalar servidor MCP no VS Code

POST https://api.belvo.com/payments/api/widget-token/
Authorization: Basic <base64_encoded_secret_id:secret_password>
Content-Type: application/json

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

dependencies {
    implementation("com.belvo:biometric-pix-core:1.0.0")
}

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<activity android:name=".MainActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="yourdomain.com"
            android:pathPrefix="/callback" />
    </intent-filter>
</activity>

# Obtenha sua impressão digital SHA-256
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# Formato para compartilhar com a Belvo:
# Package: com.yourcompany.appname
# SHA-256: AA:BB:CC:DD:EE:FF:...

import com.belvo.biometricpixsdk.BiometricPixSDK
import androidx.activity.ComponentActivity

class EnrollmentActivity : ComponentActivity() {
    private lateinit var sdk: BiometricPixSDK
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // DEVE solicitar permissões ANTES de inicializar o SDK
        requestPermissions()
    }
    
    private fun requestPermissions() {
        BiometricPixSDK.requestPermission(this) { granted ->
            if (granted) {
                // Permissões concedidas, agora inicialize o SDK
                initializeSDK()
            } else {
                // Lidar com a negação de permissão
                showError("Permissão de localização é necessária para o cadastro")
            }
        }
    }
    
    private fun initializeSDK() {
        // Inicializar APÓS as permissões serem concedidas
        sdk = BiometricPixSDK(
            context = this,
            accessToken = getAccessToken() // Do seu backend
        )
        // Agora pronto para prosseguir com o cadastro
    }
    
    override fun onDestroy() {
        super.onDestroy()
        if (::sdk.isInitialized) {
            sdk.cleanup()
        }
    }
}

import com.belvo.biometricpixsdk.BiometricPixSDK
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.launch

class EnrollmentViewModel(
    private val sdk: BiometricPixSDK
) : ViewModel() {
    
    private val _institutions = MutableStateFlow<List<Institution>>(emptyList())
    val institutions: StateFlow<List<Institution>> = _institutions
    
    fun loadInstitutions() {
        viewModelScope.launch {
            try {
                _institutions.value = sdk.getPaymentInstitutions()
            } catch (e: Exception) {
                // Tratar erro (rede, autenticação, etc.)
                _error.value = "Falha ao carregar instituições: ${e.message}"
            }
        }
    }
}

@Composable
fun InstitutionPickerScreen(
    viewModel: EnrollmentViewModel
) {
    val institutions by viewModel.institutions.collectAsState()
    
    LazyColumn {
        items(institutions) { institution ->
            InstitutionItem(
                institution = institution,
                onClick = { viewModel.selectInstitution(institution) }
            )
        }
    }
    
    LaunchedEffect(Unit) {
        viewModel.loadInstitutions()
    }
}

@Composable
fun InstitutionItem(
    institution: Institution,
    onClick: () -> Unit
) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .clickable(onClick = onClick)
            .padding(16.dp)
    ) {
        AsyncImage(
            model = institution.iconLogo,
            contentDescription = institution.displayName,
            modifier = Modifier.size(40.dp)
        )
        Spacer(modifier = Modifier.width(16.dp))
        Text(text = institution.displayName)
    }
}

fun startEnrollment() {
    val institution = _selectedInstitution.value ?: return
    
    viewModelScope.launch {
        try {
            // Criar inscrição
            val enrollment = sdk.createEnrollment(
                cpf = userCPF,                           // CPF do usuário
                institution = institution.id,             // ID da instituição selecionada
                accountTenure = customerCreatedDate,      // Formato "YYYY-MM-DD"
                callbackUrl = "https://yourdomain.com/callback"
            )
            
            // Salvar ID da inscrição e ID do dispositivo para uso posterior
            _enrollmentId.value = enrollment.id
            _deviceId.value = enrollment.details.riskSignals.deviceId
            
            // Imediatamente abrir o app da instituição usando a URL de redirecionamento
            enrollment.details.redirectUrl?.let { url ->
                sdk.openRedirectUrl(context, url)
            } ?: run {
                _error.value = "Nenhuma URL de redirecionamento recebida da inscrição"
            }
            
        } catch (e: Exception) {
            _error.value = "Falha na criação da inscrição: ${e.message}"
        }
    }
}

// No seu MainActivity
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { uri ->
        handleEnrollmentCallback(uri)
    }
}

fun handleEnrollmentCallback(uri: Uri) {
    viewModelScope.launch {
        try {
            val enrollment = sdk.completeEnrollmentAfterRedirection(
                callbackUrl = uri.toString()  // SDK analisa os parâmetros automaticamente
            )
            
            // Verifique se foi bem-sucedido
            when (enrollment.status) {
                "PENDING" -> {
                    // Sucesso - prossiga para o registro FIDO
                    getFidoOptions(enrollment.id)
                }
                "FAILED" -> {
                    // Trate a falha
                    _error.value = "${enrollment.statusReasonCode}: ${enrollment.statusReasonMessage}"
                }
            }
            
        } catch (e: Exception) {
            _error.value = "Falha ao completar o cadastro: ${e.message}"
        }
    }
}

fun getFidoOptions(enrollmentId: String) {
    viewModelScope.launch {
        // O SDK verifica automaticamente a cada 1 segundo por até 5 minutos
        val fidoOptions = sdk.getFidoRegistrationOptions(enrollmentId)
        
        if (fidoOptions != null) {
            // Opções FIDO recebidas, prossiga para o registro biométrico
            startBiometricRegistration(fidoOptions)
        } else {
            // Tempo de verificação esgotado (5 minutos se passaram)
            _error.value = "Tempo esgotado aguardando as opções FIDO. Por favor, tente novamente."
        }
    }
}

class EnrollmentViewModel(
    private val sdk: BiometricPixSDK
) : ViewModel() {
    
    private var enrollmentId: String? = null
    
    fun startBiometricRegistration(fidoOptions: FidoRegistrationOptions) {
        try {
            sdk.startRegistration(
                fidoOptions = fidoOptions.toJsonString(),
                callback = object : FidoRegistrationCallback {
                    override fun onSuccess(credential: PublicKeyCredential, response: AuthenticatorAttestationResponse) {
                        // SDK lida com a criação do payload automaticamente
                        confirmEnrollment(credential, response)
                    }
                    
                    override fun onError(error: String) {
                        _error.value = "Registro biométrico falhou: $error"
                    }
                }
            )
        } catch (e: Exception) {
            _error.value = "Falha ao iniciar o registro: ${e.message}"
        }
    }
    
    private fun confirmEnrollment(
        credential: PublicKeyCredential,
        response: AuthenticatorAttestationResponse
    ) {
        val enrollmentId = this.enrollmentId ?: return
        
        viewModelScope.launch {
            val success = sdk.confirmEnrollment(
                enrollmentId = enrollmentId,
                credential = credential,
                response = response
            )
            
            if (success) {
                _state.value = EnrollmentState.Success
            } else {
                _error.value = "Confirmação de registro falhou"
            }
        }
    }
}

class PaymentViewModel(
    private val sdk: BiometricPixSDK
) : ViewModel() {
    
    private val _enrollments = MutableStateFlow<List<Enrollment>>(emptyList())
    val enrollments: StateFlow<List<Enrollment>> = _enrollments
    
    fun loadEnrollments(deviceId: String) {
        viewModelScope.launch {
            try {
                _enrollments.value = sdk.listEnrollments(deviceId)
            } catch (e: Exception) {
                _error.value = "Falha ao carregar inscrições: ${e.message}"
            }
        }
    }
}

@Composable
fun EnrollmentSelectionScreen(
    viewModel: PaymentViewModel
) {
    val enrollments by viewModel.enrollments.collectAsState()
    
    LazyColumn {
        items(enrollments) { enrollment ->
            enrollment.institution?.let { institution ->
                EnrollmentItem(
                    enrollment = enrollment,
                    institution = institution,
                    onClick = { viewModel.selectEnrollment(enrollment) }
                )
            }
        }
    }
    
    LaunchedEffect(Unit) {
        viewModel.loadEnrollments(savedDeviceId)
    }
}

@Composable
fun EnrollmentItem(
    enrollment: Enrollment,
    institution: Institution,
    onClick: () -> Unit
) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .clickable(onClick = onClick)
            .padding(16.dp)
    ) {
        AsyncImage(
            model = institution.iconLogo,
            contentDescription = institution.displayName,
            modifier = Modifier.size(40.dp)
        )
        Spacer(modifier = Modifier.width(16.dp))
        Column {
            Text(text = institution.displayName)
            Text(
                text = "Status: ${enrollment.status}",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )
        }
    }
}

fun createPayment(
    amount: Double,
    enrollmentId: String,
    beneficiaryAccountId: String
) {
    val payload = CreatePaymentIntentPayload(
        amount = amount,
        customer = Customer(identifier = userCPF),  // CPF do usuário
        description = "Pagamento por serviços",
        statementDescription = "Compra ACME Corp",
        allowedPaymentMethodTypes = listOf("open_finance_biometric_pix"),
        paymentMethodDetails = PaymentMethodDetails(
            openFinanceBiometricPix = OpenFinanceBiometricPixPaymentMethodDetails(
                beneficiaryBankAccount = beneficiaryAccountId,
                enrollment = enrollmentId
            )
        ),
        confirm = true
    )
    
    viewModelScope.launch {
        try {
            val paymentIntent = sdk.createPaymentIntent(payload)
            
            // Salvar ID da intenção de pagamento
            _paymentIntentId.value = paymentIntent.id
            
            // Extrair opções FIDO para o próximo passo
            paymentIntent.paymentMethodInformation?.openFinanceBiometricPix?.fidoOptions?.let { fidoOptions ->
                promptForBiometric(fidoOptions)
            }
            
        } catch (e: Exception) {
            _error.value = "Falha ao criar intenção de pagamento: ${e.message}"
        }
    }
}

class PaymentViewModel(
    private val sdk: BiometricPixSDK
) : ViewModel() {
    
    private var paymentIntentId: String? = null
    private var riskSignals: RiskSignals? = null
    private var assertionResponse: AssertionResponse? = null
    
    fun promptForBiometric(fidoOptions: FidoOptions) {
        try {
            sdk.startSigning(
                fidoOptions = fidoOptions.toJsonString(),
                fallbackCredential = null,  // Opcional: forneça se você tiver um
                callback = object : FidoAuthenticationCallback {
                    override fun onSuccess(response: AssertionResponse) {
                        // Armazene a resposta de asserção
                        assertionResponse = response
                        
                        // Colete sinais de risco
                        collectRiskSignals()
                    }
                    
                    override fun onError(error: String) {
                        _error.value = "Falha na autenticação biométrica: $error"
                    }
                }
            )
        } catch (e: Exception) {
            _error.value = "Falha ao iniciar a assinatura: ${e.message}"
        }
    }
    
    private fun collectRiskSignals() {
        try {
            riskSignals = sdk.collectRiskSignals(
                accountTenure = customerCreatedDate  // "YYYY-MM-DD"
            )
            
            // Assim que tivermos tanto a asserção quanto os sinais de risco, autorize o pagamento
            if (assertionResponse != null && riskSignals != null) {
                authorizePayment()
            }
        } catch (e: Exception) {
            _error.value = "Falha ao coletar sinais de risco: ${e.message}"
        }
    }
}

private fun authorizePayment() {
    val paymentIntentId = this.paymentIntentId ?: return
    val riskSignals = this.riskSignals ?: return
    val assertion = this.assertionResponse ?: return
    
    val payload = AuthorizePaymentIntentPayload(
        platform = "android",
        riskSignals = riskSignals,
        assertion = assertion
    )
    
    viewModelScope.launch {
        val success = sdk.authorizePaymentIntent(
            paymentIntentId = paymentIntentId,
            payload = payload
        )
        
        if (success) {
            _state.value = PaymentState.Success
        } else {
            _error.value = "Falha na autorização do pagamento"
        }
    }
}

try {
    val institutions = sdk.getPaymentInstitutions()
    // Sucesso
} catch (e: BiometricPixSDKException) {
    when (e) {
        is BiometricPixSDKException.NetworkError -> {
            // Tratar problemas de rede
            Log.e(TAG, "Erro de rede: ${e.message}")
        }
        is BiometricPixSDKException.AuthenticationError -> {
            // Tratar token inválido ou expirado
            Log.e(TAG, "Falha na autenticação - o token pode estar expirado")
        }
        is BiometricPixSDKException.InvalidParametersError -> {
            // Tratar entrada inválida
            Log.e(TAG, "Parâmetros inválidos: ${e.message}")
        }
        is BiometricPixSDKException.UnknownError -> {
            // Tratar erros desconhecidos
            Log.e(TAG, "Erro: ${e.message}")
        }
    }
} catch (e: Exception) {
    Log.e(TAG, "Erro inesperado: ${e.message}")
}