Guía de Pix Biometria (Android SDK - Integración Simplificada)

Copiar

• Copiar para LLM

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

  Abrir esta página como Markdown
• Abrir en ChatGPT

  Obtener información de ChatGPT
• Abrir en Claude

  Obtener información de Claude
• Conectar a Cursor

  Instalar servidor MCP en Cursor
• Conectar a VS Code

  Instalar servidor MCP en 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>

# Obtén tu huella digital SHA-256
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# Formato para compartir con 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)
        
        // DEBE solicitar permisos ANTES de inicializar el SDK
        requestPermissions()
    }
    
    private fun requestPermissions() {
        BiometricPixSDK.requestPermission(this) { granted ->
            if (granted) {
                // Permisos concedidos, ahora inicializar el SDK
                initializeSDK()
            } else {
                // Manejar la denegación de permisos
                showError("Se requiere permiso de ubicación para el registro")
            }
        }
    }
    
    private fun initializeSDK() {
        // Inicializar DESPUÉS de que se concedan los permisos
        sdk = BiometricPixSDK(
            context = this,
            accessToken = getAccessToken() // Desde tu backend
        )
        // Ahora listo para proceder con el registro
    }
    
    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) {
                // Manejar error (red, autenticación, etc.)
                _error.value = "Error al cargar instituciones: ${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 {
            // Crear inscripción
            val enrollment = sdk.createEnrollment(
                cpf = userCPF,                           // CPF del usuario
                institution = institution.id,             // ID de la institución seleccionada
                accountTenure = customerCreatedDate,      // Formato "YYYY-MM-DD"
                callbackUrl = "https://yourdomain.com/callback"
            )
            
            // Guardar ID de inscripción e ID de dispositivo para más tarde
            _enrollmentId.value = enrollment.id
            _deviceId.value = enrollment.details.riskSignals.deviceId
            
            // Inmediatamente abrir la aplicación de la institución usando la URL de redirección
            enrollment.details.redirectUrl?.let { url ->
                sdk.openRedirectUrl(context, url)
            } ?: run {
                _error.value = "No se recibió URL de redirección de la inscripción"
            }
            
        } catch (e: Exception) {
            _error.value = "La creación de la inscripción falló: ${e.message}"
        }
    }
}

// En tu 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 analiza los parámetros automáticamente
            )
            
            // Verifica si fue exitoso
            when (enrollment.status) {
                "PENDING" -> {
                    // Éxito - procede al registro FIDO
                    getFidoOptions(enrollment.id)
                }
                "FAILED" -> {
                    // Maneja el fallo
                    _error.value = "${enrollment.statusReasonCode}: ${enrollment.statusReasonMessage}"
                }
            }
            
        } catch (e: Exception) {
            _error.value = "Error al completar el registro: ${e.message}"
        }
    }
}

fun getFidoOptions(enrollmentId: String) {
    viewModelScope.launch {
        // El SDK consulta automáticamente cada 1 segundo durante hasta 5 minutos
        val fidoOptions = sdk.getFidoRegistrationOptions(enrollmentId)
        
        if (fidoOptions != null) {
            // Opciones FIDO recibidas, proceder al registro biométrico
            startBiometricRegistration(fidoOptions)
        } else {
            // El tiempo de espera de la consulta se agotó (pasaron 5 minutos)
            _error.value = "Tiempo de espera agotado para las opciones FIDO. Por favor, inténtalo de nuevo."
        }
    }
}

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 maneja la creación de payload automáticamente
                        confirmEnrollment(credential, response)
                    }
                    
                    override fun onError(error: String) {
                        _error.value = "El registro biométrico falló: $error"
                    }
                }
            )
        } catch (e: Exception) {
            _error.value = "Error al iniciar el 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 = "La confirmación de inscripción falló"
            }
        }
    }
}

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 = "Failed to load enrollments: ${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 = "Estado: ${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 del usuario
        description = "Pago por servicios",
        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)
            
            // Guardar ID de la intención de pago
            _paymentIntentId.value = paymentIntent.id
            
            // Extraer opciones FIDO para el siguiente paso
            paymentIntent.paymentMethodInformation?.openFinanceBiometricPix?.fidoOptions?.let { fidoOptions ->
                promptForBiometric(fidoOptions)
            }
            
        } catch (e: Exception) {
            _error.value = "Error al crear la intención de pago: ${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: proporcionar si tienes uno
                callback = object : FidoAuthenticationCallback {
                    override fun onSuccess(response: AssertionResponse) {
                        // Almacenar respuesta de aserción
                        assertionResponse = response
                        
                        // Recopilar señales de riesgo
                        collectRiskSignals()
                    }
                    
                    override fun onError(error: String) {
                        _error.value = "La autenticación biométrica falló: $error"
                    }
                }
            )
        } catch (e: Exception) {
            _error.value = "Error al iniciar la firma: ${e.message}"
        }
    }
    
    private fun collectRiskSignals() {
        try {
            riskSignals = sdk.collectRiskSignals(
                accountTenure = customerCreatedDate  // "YYYY-MM-DD"
            )
            
            // Una vez que tenemos tanto la aserción como las señales de riesgo, autorizar el pago
            if (assertionResponse != null && riskSignals != null) {
                authorizePayment()
            }
        } catch (e: Exception) {
            _error.value = "Error al recopilar señales de riesgo: ${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 = "Payment authorization failed"
        }
    }
}

try {
    val institutions = sdk.getPaymentInstitutions()
    // Éxito
} catch (e: BiometricPixSDKException) {
    when (e) {
        is BiometricPixSDKException.NetworkError -> {
            // Manejar problemas de red
            Log.e(TAG, "Error de red: ${e.message}")
        }
        is BiometricPixSDKException.AuthenticationError -> {
            // Manejar token inválido o expirado
            Log.e(TAG, "Autenticación fallida - el token puede estar expirado")
        }
        is BiometricPixSDKException.InvalidParametersError -> {
            // Manejar entrada inválida
            Log.e(TAG, "Parámetros inválidos: ${e.message}")
        }
        is BiometricPixSDKException.UnknownError -> {
            // Manejar errores desconocidos
            Log.e(TAG, "Error: ${e.message}")
        }
    }
} catch (e: Exception) {
    Log.e(TAG, "Error inesperado: ${e.message}")
}