Guia do Biometric Pix (Usando iOS SDK)

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 usando apenas 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 iOS.

Pré-requisitos

Antes de continuar com este guia, certifique-se de que:

1. Você gerou suas Chaves de API do Belvo Payments.

2. Configurou Webhooks para receber atualizações sobre o status de seus pagamentos e inscrições.

3. Instalou o SDK iOS da Belvo:

   Requisitos Mínimos

   • iOS: 15.0 ou superior
   • Swift: 5.0 ou superior

   Instruções:

   Para integrar o Belvo Biometric PIX SDK em seu projeto Xcode usando o Swift Package Manager:

   1. No Xcode, selecione File → Add Packages....
   2. Insira a URL do repositório do pacote: https://github.com/belvo-finance-opensource/biometric-pix-ios-sdk.
   3. Selecione os requisitos de versão e clique em Add Package.
   4. Escolha o produto BiometricPixSDK e clique em Add Package.

4. Adicione as permissões necessárias ao arquivo de permissões do seu aplicativo:

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

5. Adicione a descrição de uso de localização no seu arquivo Info.plist:

      <key>NSLocationWhenInUseUsageDescription</key>
      <string>Este aplicativo usa localização para fins de segurança e prevenção de fraudes.</string>

6. Compartilhe seu Team ID e Bundle Identifier com a Belvo no seguinte formato

       ## Formato
       TEAM_ID.BUNDLE_ID
   
       ## Exemplo
       ABCDEFGHIJ.com.yourcompany.appname

7. Além disso, para cada usuário que você deseja inscrever no sistema Biometric Pix, você precisará primeiro 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 iOS 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. Solicitar Permissões de Localização e Coletar Sinais de Risco: 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(fidoOptions) do Belvo iOS 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).

Solicitar ao usuário que selecione a instituição para se inscrever (Belvo API)

Em seu aplicativo, solicite ao seu usuário que selecione a instituição onde deseja inscrever o dispositivo. Use a solicitação Listar todas as instituições de pagamento 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)).

Solicitar Permissões de Localização e Coletar Sinais de Risco (SDK iOS)

Em seguida, no seu aplicativo, você precisará fazer as seguintes chamadas:

requestPermission()

Este método requestPermission() cria e lança uma solicitação de permissão para permissões de localização e estado do telefone.

import SwiftUI
import BiometricPixSDK
import Foundation

struct PermissionRequestExample: View {
    @State private var permissionGranted: Bool? = nil
    private let sdk = BiometricPixSDK()

    private func requestPermission() {
        sdk.requestPermission { granted in
            DispatchQueue.main.async {
								// Se necessário, converta granted para Bool
                permissionGranted = granted as? Bool
								// Se necessário, manipule a UI
            }
        }
    }
}

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) 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).

import SwiftUI
import BiometricPixSDK
import Foundation

struct RiskSignalsView: View {
    private let sdk = BiometricPixSDK()

    private func collectRiskSignals() {
        do {
            // Coletar sinais de risco com a data de criação do usuário
            signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
        } catch {
            // Lidar com erros que podem ocorrer durante a coleta de sinais de risco.
            // Possíveis erros incluem:
            // - Formato inválido de `accountTenure`
            // - Problemas de conectividade de rede
            // Considere registrar o erro ou exibir uma mensagem apropriada para o usuário.
        }
    }
}

Uma vez que você tenha os sinais de risco e o ID do dispositivo, você pode encaminhar essa informação para a Belvo usando o método Create Enrollment.

Criar Inscrição Usando Sinais de Risco (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": "IOS",
        "callback_url": "{{https://deeplink_to_your_application}}",
        "risk_signals": {} 
    }
}

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 e 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": "IOS",
    "name": "Primeira Inscrição",
    "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:

POST /enrollments/complete-redirection/

{
    "state": "{{state}}",
    "code": "{{code}}",
    "id_token": "{{id_token}}",
}

// 200 OK
{
    "id": "{{enrollment.id}}", 
    "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": "IOS",
        "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}}"
}

Consultar a API da Belvo para opções FIDO (API)

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 (fidoOptions) 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 para Biometria (iOS SDK)

Com o payload recebido, você precisa usar o método startRegistration(fidoOptions). 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 Foundation
import BiometricPixSDK

class FidoRegistrationViewModel : NSObject, ObservableObject {
    private let sdk = BiometricPixSDK()

    func startRegistration(fidoOptions: String) {
        do {
            sdk.startRegistration(
                fidoResponseString: fidoOptions, 
                callback: self // Instância de Callback
            )
        } catch {
            // Lidar com erros
        }
    }
}

// Implementando callback para registro
extension FidoRegistrationViewModel: FidoRegistrationCallback {
    func onError(error: String) {
            // Lidar com erros de registro
    }

    func onSuccess(response attestationResponse: AttestationResponse) {
            // Lidar com registro bem-sucedido
            // O objeto attestationResponse contém os dados necessários para o próximo passo.
            let encodedId = attestationResponse.encodedId
            let rawId = attestationResponse.rawId
            let encodedAttestationObject = attestationResponse.encodedAttestationObject
            let encodedClientDataJSON = attestationResponse.encodedClientDataJSON
            
            // Persistir esses valores para serem enviados ao seu backend.
    }
}

import SwiftUI

struct MyView: View {
    @ObservedObject var registrationViewModel = FidoRegistrationViewModel()
// ...
}

Você precisa armazenar os seguintes valores em variáveis, pois eles são usados para confirmar a Inscrição na etapa seguinte:

• encodedId
• rawId
• encodedAttestationObject
• encodedClientDataJSON

Enviar biometria para finalizar a inscrição e verificar a resposta (API)

Para completar o processo de Inscrição, 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": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "type": "public-key",
    "response": {
      "attestationObject": "{{encodedAttestationObject}}",
      "clientDataJSON": "{{encodedClientDataJSON}}"
    }
  }
}

A Belvo responderá com um 204 - No Content e encaminhará a informação para a instituição para completar o processo de inscrição.

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! A inscrição está pronta e você pode começar a fazer pagamentos!

Realizando um Pagamento

Uma vez que o dispositivo de um usuário esteja inscrito com sucesso, você pode iniciar solicitações de pagamento usando suas credenciais biométricas armazenadas. Este processo envolve:

1. Selecionar uma Inscrição
2. Criar uma intenção de pagamento
3. Coletar dados de autenticação biométrica
4. Autorizar o pagamento

Selecionar Inscrição (API)

Use o método da API Listar todas as inscrições, com o parâmetro de consulta device_id necessário, 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 etapa seguinte Criar Intenção de Pagamento).

GET /enrollments/?device_id={device_id}

Criar Intenção de Pagamento (API)

Uma vez que você tenha a Inscrição selecionada pelo usuário, você pode criar uma Intenção de Pagamento:

POST /payments/br/payment-intents/

{
    "amount": 0.13,
    "allowed_payment_method_types": [
        "open_finance_biometric_pix"
    ],
    "customer": "{{customer.id}}",
    "description": "Teste de Intenção de Pagamento com Inscrição",
    "statement_description": "Descrição para mostrar no extrato",
    "payment_method_details": {
        "open_finance_biometric_pix": {
            "beneficiary_bank_account": "{{bank_account.id}}",
            "enrollment": "{{enrollment.id}}"
        }
    },
    "confirm": true
}

Na resposta, a Belvo retornará o payment_intent.id e o objeto fido_options que são necessários para a próxima etapa de 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 na próxima etapa 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)

Usando o fido_options recebido da intenção de pagamento, inicie o processo de autenticação biométrica usando o método startSigning(fidoOptions) do SDK iOS da Belvo. Após o usuário autenticar, você também precisará chamar collectRiskSignals(accountTenure) para coletar informações do dispositivo.

Os resultados desses métodos contêm os valores que você precisará enviar para o seu backend para autorizar o pagamento.

import Foundation
import BiometricPixSDK

class FidoAuthenticationViewModel : NSObject, ObservableObject {
    private let sdk = BiometricPixSDK()

    func startSigning(fidoOptions: String) {
        do {
            // Nota: O método para iniciar a autenticação de pagamento é startSigning.
            sdk.startSigning(
                fidoResponseString: fidoOptions,// string json solicitada da api backend
                fallbackCredential: nil,// string de credencial alternativa se disponível
                callback: self// instância de callback
            )
        } catch {
                        // Tratamento de erro
        }
    }
    
    private func collectRiskSignals() {
        do {
            // Coletar sinais de risco com a data de criação do usuário
            let signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
            // Envie os sinais para o seu backend para serem usados na etapa de autorização.
        } catch {
            // lidar com erro
        }
    }
}

// implementando callback para autenticação
extension FidoAuthenticationViewModel: FidoAuthenticationCallback {
    func onError(error: String) {
                // Lidar com erros de autenticação
    }

    func onSuccess(response assertionResponse: AssertionResponse) {
                // Lidar com autenticação bem-sucedida
        // Extrair dados de assertionResponse e enviar para o seu backend.
        // Em seguida, chame collectRiskSignals.
        collectRiskSignals()
    }
}

import SwiftUI

struct MyView: View {
    @ObservedObject var registrationViewModel = FidoRegistrationViewModel()
// ...
}

Autorizar Pagamento (API)

Após recuperar 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á verificar GET /payment-intents/{id}/ até que o status da intenção de pagamento se torne SUCCEEDED.

  Estratégia de Verificação: Semelhante à inscrição, recomendamos verificar o 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 seja bem-sucedido, exiba uma tela de confirmação para o Usuário Final.

// Exemplo de Corpo da Requisição POST /payment-intents/{id}/authorize/
{
  "risk_signals": {}, // O objeto de Sinais de Risco coletado
  "assertion": {
    "authenticatorAttachment": "platform",
    "id": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "response": {
      "authenticatorData": "{{encodedAuthenticatorData}}",
      "clientDataJSON": "{{encodedClientDataJSON}}",
      "signature": "{{encodedSignature}}",
      "userHandle": "{{userHandle}}"
      
    },
    "type": "public-key"
  }
}

A API da Belvo retornará um 204 - No Content. Após isso, você precisará verificar o seguinte endpoint para recuperar o status final do pagamento:

GET /payment-intents/{payment_intent_id}/