Pix Biometria Guide (iOS SDK-Only Integration)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on 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..."
}

<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:belvo.com</string>
</array>

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses location for security and fraud prevention purposes.</string>

Format: TEAM_ID.BUNDLE_ID
Example: ABCDEFGHIJ.com.yourcompany.appname

import BiometricPixSDK

class BiometricPixService {
    private let sdk: BiometricPixSDK
    
    init(accessToken: String) {
        self.sdk = BiometricPixSDK(accessToken: accessToken)
    }
    
    deinit {
        sdk.cleanup()
    }
}

import BiometricPixSDK

class EnrollmentViewModel: ObservableObject {
    private let sdk: BiometricPixSDK
    @Published var institutions: [Institution] = []
    @Published var selectedInstitution: Institution?
    
    init(sdk: BiometricPixSDK) {
        self.sdk = sdk
    }
    
    func loadInstitutions() {
        do {
            institutions = try sdk.getPaymentInstitutions()
        } catch {
            // Handle error (network, authentication, etc.)
            print("Failed to load institutions: \(error)")
        }
    }
}

struct InstitutionPickerView: View {
    @ObservedObject var viewModel: EnrollmentViewModel
    
    var body: some View {
        List(viewModel.institutions) { institution in
            Button(action: { 
                viewModel.selectedInstitution = institution 
            }) {
                HStack {
                    AsyncImage(url: URL(string: institution.iconLogo))
                        .frame(width: 40, height: 40)
                    Text(institution.displayName)
                }
            }
        }
        .onAppear {
            viewModel.loadInstitutions()
        }
    }
}

func requestPermissions() {
    sdk.requestPermission { granted in
        DispatchQueue.main.async {
            if let permissionGranted = granted as? Bool, permissionGranted {
                // Permissions granted, proceed to enrollment
                self.startEnrollment()
            } else {
                // Handle permission denial
                self.showPermissionDeniedAlert()
            }
        }
    }
}

func startEnrollment() {
    guard let institution = selectedInstitution else { return }
    
    do {
        let enrollment = try sdk.createEnrollment(
            cpf: userCPF,                           // User's CPF
            institution: institution.id,             // Selected institution ID
            accountTenure: customerCreatedDate,      // "YYYY-MM-DD" format
            callbackUrl: "https://myapp.com/callback"
        )
        
        // Save enrollment ID and device ID for later
        self.enrollmentId = enrollment.id
        self.deviceId = enrollment.details.riskSignals.deviceId
        
        // Redirect user to institution
        if let redirectUrl = enrollment.details.redirectUrl {
            self.openInstitutionApp(url: redirectUrl)
        }
        
    } catch {
        // Handle error
        print("Enrollment creation failed: \(error)")
    }
}

func openInstitutionApp(url: String) {
    guard let url = URL(string: url) else { return }
    
    if UIApplication.shared.canOpenURL(url) {
        UIApplication.shared.open(url)
    }
}

// In your SceneDelegate or App delegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    
    // Pass the full callback URL to the SDK
    handleEnrollmentCallback(url: url)
}

func handleEnrollmentCallback(url: URL) {
    do {
        let enrollment = try sdk.completeEnrollmentAfterRedirection(
            callbackUrl: url.absoluteString  // SDK parses parameters automatically
        )
        
        // Check if successful
        if enrollment.status == "PENDING" {
            // Success - proceed to FIDO registration
            self.getFidoOptions(enrollmentId: enrollment.id)
        } else if enrollment.status == "FAILED" {
            // Handle failure
            self.showEnrollmentError(
                code: enrollment.statusReasonCode,
                message: enrollment.statusReasonMessage
            )
        }
        
    } catch {
        print("Failed to complete enrollment: \(error)")
    }
}

func getFidoOptions(enrollmentId: String) {
    // SDK polls automatically every 1 second for up to 5 minutes
    if let fidoOptions = sdk.getFidoRegistrationOptions(enrollmentId: enrollmentId) {
        // FIDO options received, proceed to biometric registration
        self.startBiometricRegistration(fidoOptions: fidoOptions)
    } else {
        // Polling timed out (5 minutes passed)
        self.showTimeoutError()
    }
}

class EnrollmentViewModel: NSObject, ObservableObject {
    private let sdk: BiometricPixSDK
    private var enrollmentId: String?
    
    func startBiometricRegistration(fidoOptions: FidoRegistrationOptions) {
        do {
            try sdk.startRegistration(
                fidoResponseString: fidoOptions.toJsonString(),
                callback: self
            )
        } catch {
            print("Failed to start registration: \(error)")
        }
    }
}

// Implement FIDO callback
extension EnrollmentViewModel: FidoRegistrationCallback {
    func onSuccess(credential: PublicKeyCredential, response: AuthenticatorAttestationResponse) {
        // SDK handles payload creation automatically
        guard let enrollmentId = self.enrollmentId else { return }
        
        let success = sdk.confirmEnrollment(
            enrollmentId: enrollmentId,
            credential: credential,
            response: response
        )
        
        if success {
            DispatchQueue.main.async {
                self.showEnrollmentSuccess()
            }
        } else {
            DispatchQueue.main.async {
                self.showEnrollmentError()
            }
        }
    }
    
    func onError(error: String) {
        DispatchQueue.main.async {
            self.showBiometricError(message: error)
        }
    }
}

class PaymentViewModel: ObservableObject {
    private let sdk: BiometricPixSDK
    @Published var enrollments: [Enrollment] = []
    @Published var selectedEnrollment: Enrollment?
    
    func loadEnrollments(deviceId: String) {
        do {
            enrollments = try sdk.listEnrollments(deviceId: deviceId)
        } catch {
            print("Failed to load enrollments: \(error)")
        }
    }
}

struct EnrollmentSelectionView: View {
    @ObservedObject var viewModel: PaymentViewModel
    
    var body: some View {
        List(viewModel.enrollments) { enrollment in
            Button(action: { 
                viewModel.selectedEnrollment = enrollment 
            }) {
                HStack {
                    if let institution = enrollment.institution {
                        AsyncImage(url: URL(string: institution.iconLogo))
                            .frame(width: 40, height: 40)
                        VStack(alignment: .leading) {
                            Text(institution.displayName)
                            Text("Status: \(enrollment.status)")
                                .font(.caption)
                                .foregroundColor(.gray)
                        }
                    }
                }
            }
        }
        .onAppear {
            viewModel.loadEnrollments(deviceId: savedDeviceId)
        }
    }
}

func createPayment(amount: Double, enrollmentId: String, beneficiaryAccountId: String) {
    let payload = CreatePaymentIntentPayload(
        amount: amount,
        customer: Customer(identifier: userCPF),  // User's CPF
        description: "Payment for services",
        statementDescription: "ACME Corp Purchase",
        allowedPaymentMethodTypes: ["open_finance_biometric_pix"],
        paymentMethodDetails: PaymentMethodDetails(
            openFinanceBiometricPix: OpenFinanceBiometricPixPaymentMethodDetails(
                beneficiaryBankAccount: beneficiaryAccountId,
                enrollment: enrollmentId
            )
        ),
        confirm: true
    )
    
    do {
        let paymentIntent = try sdk.createPaymentIntent(payload: payload)
        
        // Save payment intent ID
        self.paymentIntentId = paymentIntent.id
        
        // Extract FIDO options for next step
        if let fidoOptions = paymentIntent.paymentMethodInformation?.openFinanceBiometricPix?.fidoOptions {
            self.promptForBiometric(fidoOptions: fidoOptions)
        }
        
    } catch {
        print("Failed to create payment intent: \(error)")
    }
}

class PaymentViewModel: NSObject, ObservableObject {
    private let sdk: BiometricPixSDK
    private var paymentIntentId: String?
    private var riskSignals: RiskSignals?
    private var assertionResponse: AssertionResponse?
    
    func promptForBiometric(fidoOptions: FidoOptions) {
        // Convert FIDO options to JSON string
        let fidoJsonString = fidoOptions.toJsonString()
        
        do {
            try sdk.startSigning(
                fidoResponseString: fidoJsonString,
                fallbackCredential: nil,  // Optional: provide if you have one
                callback: self
            )
        } catch {
            print("Failed to start signing: \(error)")
        }
    }
    
    func collectRiskSignals() {
        do {
            self.riskSignals = try sdk.collectRiskSignals(
                accountTenure: customerCreatedDate  // "YYYY-MM-DD"
            )
            
            // Once we have both assertion and risk signals, authorize payment
            if assertionResponse != nil && riskSignals != nil {
                self.authorizePayment()
            }
        } catch {
            print("Failed to collect risk signals: \(error)")
        }
    }
}

// Implement FIDO authentication callback
extension PaymentViewModel: FidoAuthenticationCallback {
    func onSuccess(response: AssertionResponse) {
        // Store assertion response
        self.assertionResponse = response
        
        // Collect risk signals
        self.collectRiskSignals()
    }
    
    func onError(error: String) {
        DispatchQueue.main.async {
            self.showPaymentError(message: error)
        }
    }
}

func authorizePayment() {
    guard let paymentIntentId = self.paymentIntentId,
          let riskSignals = self.riskSignals,
          let assertion = self.assertionResponse else {
        return
    }
    
    let payload = AuthorizePaymentIntentPayload(
        platform: "ios",
        riskSignals: riskSignals,
        assertion: assertion
    )
    
    let success = sdk.authorizePaymentIntent(
        paymentIntentId: paymentIntentId,
        payload: payload
    )
    
    DispatchQueue.main.async {
        if success {
            self.showPaymentSuccess()
        } else {
            self.showPaymentError(message: "Authorization failed")
        }
    }
}

do {
    let institutions = try sdk.getPaymentInstitutions()
    // Success
} catch let error as BiometricPixSDKError {
    switch error {
    case .networkError(let message):
        // Handle network issues
        print("Network error: \(message)")
    case .authenticationError:
        // Handle invalid or expired token
        print("Authentication failed - token may be expired")
    case .invalidParameters(let message):
        // Handle invalid input
        print("Invalid parameters: \(message)")
    case .unknown(let message):
        // Handle unknown errors
        print("Error: \(message)")
    }
} catch {
    print("Unexpected error: \(error)")
}