Guía de Pix Biometria (Usando iOS SDK)

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

Con Pix Biometria de Belvo, la recolección de pagos de los usuarios se vuelve sencilla, eliminando la necesidad de que los usuarios naveguen a su institución financiera para aprobar cada solicitud de pago individual.

El primer paso para habilitar la recolección de pagos biométricos es inscribir el dispositivo del usuario con su institución. Durante la inscripción, los datos clave sobre el dispositivo y las credenciales de clave pública del usuario se registran de manera segura con su institución, asegurando que los pagos futuros puedan ser confirmados usando solo la autenticación biométrica.

Una vez que la inscripción esté completa, puedes comenzar a solicitar pagos directamente desde el dispositivo del usuario.

En esta guía, te llevaremos a través de cada paso, desde la inscripción del dispositivo hasta iniciar con éxito una solicitud de pago en un dispositivo iOS.

Requisitos previos

Antes de continuar con esta guía, asegúrate de que:

1. Has generado tus Claves de la API de Pagos de Belvo.

2. Configuraste Webhooks para recibir actualizaciones sobre el estado de tus pagos e inscripciones.

3. Instalaste el SDK de iOS de Belvo:

   Requisitos mínimos

   • iOS: 15.0 o superior
   • Swift: 5.0 o superior

   Instrucciones:

   Para integrar el SDK de Biometric PIX de Belvo en tu proyecto de Xcode usando Swift Package Manager:

   1. En Xcode, selecciona File → Add Packages....
   2. Ingresa la URL del repositorio del paquete: https://github.com/belvo-finance-opensource/biometric-pix-ios-sdk.
   3. Selecciona los requisitos de versión y haz clic en Add Package.
   4. Elige el producto BiometricPixSDK y haz clic en Add Package.

4. Agrega los derechos requeridos al archivo de derechos de tu aplicación:

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

5. Agrega la descripción del uso de la ubicación en tu archivo Info.plist:

      <key>NSLocationWhenInUseUsageDescription</key>
      <string>Esta aplicación utiliza la ubicación para propósitos de seguridad y prevención de fraude.</string>

6. Comparte tu Team ID y Bundle Identifier con Belvo en el siguiente formato

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

7. Además, para cada usuario que desees inscribir en el sistema de Pix Biometria, primero necesitarás crear un Cliente de Belvo.

Inscripción

La inscripción es el proceso de registrar el dispositivo de un usuario en su institución para permitir pagos biométricos para un comerciante determinado. Durante el proceso, utilizarás una combinación del SDK de iOS de Belvo Payments y la API para recuperar detalles clave sobre el dispositivo, así como los datos públicos biométricos.

1. Listar Instituciones: Solicita al usuario que seleccione su institución financiera deseada para inscribirse, utilizando la API de Belvo para mostrar las opciones disponibles.
2. Solicitar Permisos de Ubicación y Recopilar Señales de Riesgo: Solicita al usuario los permisos necesarios y recopila señales de riesgo, incluyendo el ID del dispositivo.
3. Crear y Actualizar Inscripción: Envía las señales de riesgo recopiladas, junto con el ID del cliente, el ID de la institución y una URL de callback, al servidor de Belvo para crear la inscripción. Luego, redirige al usuario a la aplicación de su institución para su aprobación. Una vez que sean redirigidos de vuelta a tu URL de callback con detalles, envía estos a Belvo para actualizar el estado de la inscripción.
4. Consultar Opciones de FIDO: Consulta continuamente la API de Belvo (GET /enrollments/{id}/fido-registration-options/) para recuperar las opciones FIDO necesarias para el registro biométrico. ⚠️ Estrategia de Consulta: Recomendamos consultar nuestro servidor cada dos segundos durante un máximo de dos minutos. Si no se recibe respuesta dentro de este período, instruye al usuario para que lo intente de nuevo.
5. Solicitar Biométricos: Toma las opciones FIDO de la API de Belvo y utiliza el método startRegistration(fidoOptions) del SDK de iOS de Belvo para solicitar al usuario su gesto biométrico.
6. Finalizar Inscripción: Envía los datos públicos biométricos a Belvo usando POST /enrollments/{id}/confirm/. Después de eso, consulta GET /enrollments/{id}/ hasta recibir una respuesta (estado de inscripción = SUCCEEDED o FAILED).

Solicitar al usuario que seleccione la institución para inscribirse (Belvo API)

En tu aplicación, solicita a tu usuario que seleccione la institución donde desea inscribir el dispositivo. Usa la solicitud de Listar todas las instituciones de pago para obtener una lista de todas las posibles instituciones. Una vez que el usuario seleccione la institución, guarda el id de la institución (requerido en el paso de Enviar Señales de Riesgo a Belvo (API)).

Solicitar permisos de ubicación y recopilar señales de riesgo (iOS SDK)

A continuación, en tu aplicación, necesitarás realizar las siguientes llamadas:

requestPermission()

Este método requestPermission() crea y lanza una solicitud de permiso para permisos de ubicación y estado del teléfono.

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 {
								// Si es necesario, convertir granted a Bool
                permissionGranted = granted as? Bool
								// Si es necesario, manejar la UI
            }
        }
    }
}

Cuando el usuario concede su permiso, puedes entonces extraer las señales de riesgo del dispositivo usando collectRiskSignals(accountTenure).

collectRiskSignals(accountTenure)

El método collectRiskSignals(accountTenure) recopila datos completos de huellas digitales del dispositivo y señales de seguridad. Los datos recopilados incluyen ID del dispositivo, estado de seguridad, información de hardware y señales de comportamiento, que son cruciales para que la institución realice evaluaciones de riesgo y detección de fraude. El método devuelve un objeto RiskSignals que necesitas guardar y enviar a los servidores de Belvo en una llamada de API. Además, necesitas persistir el valor de deviceId que el objeto RiskSignals devuelve para que más tarde puedas asociarlo con el ID de Inscripción (más adelante, al listar Inscripciones, necesitas proporcionar el deviceID para recibir todas las Inscripciones).

import SwiftUI
import BiometricPixSDK
import Foundation

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

    private func collectRiskSignals() {
        do {
            // Recopilar señales de riesgo con la fecha de creación del usuario
            signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
        } catch {
            // Manejar errores que puedan ocurrir durante la recopilación de señales de riesgo.
            // Los posibles errores incluyen:
            // - Formato `accountTenure` inválido
            // - Problemas de conectividad de red
            // Considera registrar el error o mostrar un mensaje apropiado al usuario.
        }
    }
}

Una vez que tengas las señales de riesgo y el ID del dispositivo, puedes enviar esta información a Belvo utilizando el método Create Enrollment.

Crear Inscripción Usando Señales de Riesgo (API)

POST /enrollments/

// Cuerpo de la Solicitud
{
    "type": "open_finance_biometric_pix",
    "details": {
        "customer": "{{created_customer_uuid}}",
        "institution": "{{selected_institution_uuid}}",
        "name": "Nombre para la inscripción",
        "platform": "IOS",
        "callback_url": "{{https://deeplink_to_your_application}}",
        "risk_signals": {} 
    }
}

En la respuesta, recibirás un redirect_url que necesitas mostrar a tu usuario para que puedan ser redirigidos a su institución para confirmar su inscripción.

// 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": "Primera Inscripción",
    "callback_url": "deeplink-to-your-application",
    "redirect_url": "https://www.user-banking-institituon.com/?enrollment_request=true...", 
    "risk_signals": "*****"
  }
}

Redirigir al usuario a su APP y actualizar la inscripción

Ahora necesitas redirigir a tu usuario a su institución usando el redirect_url para que puedan confirmar el proceso de inscripción. Durante el proceso, iniciarán sesión en su institución, revisarán la solicitud de inscripción y luego la autorizarán. Una vez que el usuario autorice la inscripción, la institución los redirigirá de vuelta al callback_url que proporcionaste.

https://redirect.clientApplication.com/
	?state=<state>
	&code=<code>
	&id_token=<long_id_token>

La institución pasará datos en los parámetros de consulta que debes enviar a Belvo usando la solicitud de Update Enrollment State API. Recomendamos transformar los parámetros de consulta en un objeto JSON y enviarlo directamente a Belvo.

Actualizar Estado de Inscripción

Con el valor de la cadena de consulta guardado como un objeto JSON, puedes hacer la siguiente solicitud:

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 la API de Belvo para opciones FIDO (API)

Después de recibir la respuesta exitosa de la solicitud Update Enrollment State, necesitas consultar el siguiente endpoint para recibir las opciones de registro FIDO necesarias para solicitar datos biométricos.

GET /enrollments/{enrollment_id}/fido-registration-options/

Recibirás la siguiente respuesta 200 - OK de nuestra API. Asegúrate de guardar el objeto (fidoOptions) ya que es un parámetro requerido para el método startRegistration() del 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"
    }
}

Solicitud de Biometría (iOS SDK)

Con la carga útil recibida, necesitas usar el método startRegistration(fidoOptions). Este método inicia el registro de credenciales biométricas utilizando protocolos FIDO2. Procesa las opciones de registro FIDO (una cadena JSON) recibidas de tu servidor backend y lanza el flujo de autenticación biométrica nativa del dispositivo (por ejemplo, huella digital o escaneo facial).

import Foundation
import BiometricPixSDK

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

    func startRegistration(fidoOptions: String) {
        do {
            sdk.startRegistration(
                fidoResponseString: fidoOptions, 
                callback: self // Instancia de Callback
            )
        } catch {
            // Manejar errores
        }
    }
}

// Implementación del callback para el registro
extension FidoRegistrationViewModel: FidoRegistrationCallback {
    func onError(error: String) {
            // Manejar errores de registro
    }

    func onSuccess(response attestationResponse: AttestationResponse) {
            // Manejar registro exitoso
            // El objeto attestationResponse contiene los datos necesarios para el siguiente paso.
            let encodedId = attestationResponse.encodedId
            let rawId = attestationResponse.rawId
            let encodedAttestationObject = attestationResponse.encodedAttestationObject
            let encodedClientDataJSON = attestationResponse.encodedClientDataJSON
            
            // Persistir estos valores para enviarlos a tu backend.
    }
}

import SwiftUI

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

Necesitas almacenar los siguientes valores en variables ya que se utilizan para confirmar la Inscripción en el siguiente paso:

• encodedId
• rawId
• encodedAttestationObject
• encodedClientDataJSON

Enviar biometría para finalizar el registro y consultar la respuesta (API)

Para completar el proceso de Registro, necesitarás enviar los valores que recibiste al siguiente endpoint:

POST /payments/br/enrollments/{enrollment_id}/confirm/

// Cuerpo de la Solicitud
{
  "confirmation_data": {
    "authenticatorAttachment": "platform",
    "id": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "type": "public-key",
    "response": {
      "attestationObject": "{{encodedAttestationObject}}",
      "clientDataJSON": "{{encodedClientDataJSON}}"
    }
  }
}

Belvo responderá con un 204 - No Content y enviará la información a la institución para completar el proceso de registro.

Necesitarás consultar el siguiente endpoint hasta que recibas una respuesta de la API de Belvo. Una vez que recibas una respuesta, verifica el campo status.

GET /enrollments/{enrollment_id}/

Si el status es SUCCEEDED, ¡perfecto! ¡El registro está listo y puedes comenzar a realizar pagos!

Realizando un Pago

Una vez que el dispositivo de un usuario está registrado exitosamente, puedes iniciar solicitudes de pago utilizando sus credenciales biométricas almacenadas. Este proceso involucra:

1. Seleccionar un Registro
2. Crear una intención de pago
3. Recopilar datos de autenticación biométrica
4. Autorizar el pago

Seleccionar Inscripción (API)

Utiliza el método de API Listar todas las inscripciones, con el parámetro de consulta requerido device_id, para solicitar todas las inscripciones que tu usuario ha realizado usando tu aplicación y su dispositivo actual. Muestra esta lista de inscripciones al usuario, permitiéndoles elegir qué inscripción usar para el pago. Guarda el id de esa inscripción (utilizado en el siguiente paso de Crear Intención de Pago).

GET /enrollments/?device_id={device_id}

Crear Payment Intent (API)

Una vez que tengas la Enrollment seleccionada por el usuario, puedes crear un 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
}

En la respuesta, Belvo devolverá el payment_intent.id y el objeto fido_options que son necesarios para el siguiente paso de autenticación biométrica. Necesitas:

• Persistir el payment_intent.id en tu backend.
• Guardar el fido_options en una variable para ser usado en el siguiente paso en el SDK de 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"
	  }
	}
}

Recopilar Datos Biométricos y Señales de Riesgo (SDK)

Usando las fido_options recibidas del intento de pago, inicia el proceso de autenticación biométrica utilizando el método startSigning(fidoOptions) del SDK de Belvo para iOS. Después de que el usuario se autentique, también necesitarás llamar a collectRiskSignals(accountTenure) para recopilar información del dispositivo.

Los resultados de estos métodos contienen los valores que necesitarás enviar a tu backend para autorizar el pago.

import Foundation
import BiometricPixSDK

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

    func startSigning(fidoOptions: String) {
        do {
            // Nota: El método para iniciar la autenticación de pago es startSigning.
            sdk.startSigning(
                fidoResponseString: fidoOptions,// cadena json solicitada desde la API del backend
                fallbackCredential: nil,//cadena de credenciales de respaldo si está disponible
                callback: self// instancia de callback
            )
        } catch {
                        // Manejo de errores
        }
    }
    
    private func collectRiskSignals() {
        do {
            // Recopilar señales de riesgo con la fecha de creación del usuario
            let signals = sdk.collectRiskSignals(
                accountTenure: "YYYY-MM-DD"
            )
            // Envía las señales a tu backend para ser usadas en el paso de autorización.
        } catch {
            // manejar error
        }
    }
}

// implementando callback para autenticación
extension FidoAuthenticationViewModel: FidoAuthenticationCallback {
    func onError(error: String) {
                // Manejar errores de autenticación
    }

    func onSuccess(response assertionResponse: AssertionResponse) {
                // Manejar autenticación exitosa
        // Extraer datos de assertionResponse y enviar a tu backend.
        // Luego, llama a collectRiskSignals.
        collectRiskSignals()
    }
}

import SwiftUI

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

Autorizar Pago (API)

Después de obtener la información requerida en el paso de Recolectar Datos Biométricos y Señales de Riesgo (SDK), ahora puedes autorizar el pago utilizando la API de Belvo.

POST /payment-intents/{payment_intent_id}/authorize/

• Belvo procesará la autorización. Necesitarás hacer sondeos a GET /payment-intents/{id}/ hasta que el status de la intención de pago se convierta en SUCCEEDED.

  Estrategia de Sondeo: Similar a la inscripción, recomendamos sondear el estado de la intención de pago (GET /payment-intents/{payment_intent_id}/) cada dos segundos por hasta dos minutos hasta que el estado sea SUCCEEDED. Si el estado no cambia o ocurre un error, informa al usuario y sugiere reintentar.

• Una vez que el pago sea exitoso, muestra una pantalla de confirmación al Usuario Final.

// POST /payment-intents/{id}/authorize/ Ejemplo de Cuerpo de Solicitud
{
  "risk_signals": {}, // El objeto de Señales de Riesgo recolectado
  "assertion": {
    "authenticatorAttachment": "platform",
    "id": "{{encodedId}}",
    "rawId": "{{rawId}}",
    "response": {
      "authenticatorData": "{{encodedAuthenticatorData}}",
      "clientDataJSON": "{{encodedClientDataJSON}}",
      "signature": "{{encodedSignature}}",
      "userHandle": "{{userHandle}}"
      
    },
    "type": "public-key"
  }
}

La API de Belvo devolverá un 204 - Not Content. Después de esto, necesitas sondear el siguiente endpoint para obtener el estado final del pago:

GET /payment-intents/{payment_intent_id}/