API Reference

Instalación

Resumen

Esta guía te llevará paso a paso por una solución sencilla para aceptar pagos dentro de tu aplicación Android. El SDK de Milio para Android te permite integrar múltiples métodos de pago en tu aplicación, incluyendo Visa y MasterCard.

Además, como se observa en la interfaz de usuario, podrás implementar funcionalidades relacionadas con la gestión de saldos y transferencias. Entre las acciones posibles están:

Transferencia con QR: Permite realizar pagos o transferencias escaneando un código QR.

Transferencia manual: Da la opción de ingresar manualmente los datos para efectuar una transferencia.

Transferencia inmediata: Ofrece la funcionalidad de realizar transferencias de forma rápida y sin complicaciones.

Recargar mi billetera: Facilita la recarga del saldo disponible en la billetera digital.

Estas características mejoran la experiencia del usuario, haciendo que la gestión de pagos sea fluida y eficiente desde tu aplicación Android.


Instalación

Antes de poder utilizar el SDK, es necesario realizar algunas configuraciones en los archivos build.gradle.kts del módulo de tu aplicación y settings.gradle.kts.


Configuración inicial

  1. Agregar el repositorio del SDK. Debes incluir el repositorio donde se aloja el SDK en el archivo settings.gradle.kts. Para ello, añade la siguiente línea:

dependencyResolutionManagement {
  
    repositories {
        mavenCentral() // Asegúrate de que Maven Central esté incluido
        maven { url = uri("https://jitpack.io") } // URL del repositorio del SDK
    }
    
}

A continuación, necesitamos habilitar la función de Data Binding en nuestro proyecto de Android. Para ello, debemos agregar el complemento kotlin-kapt y luego incluir las siguientes configuraciones dentro del bloque android en el archivo build.gradle.kts del módulo de la aplicación:


  1. Habilitar el complemento Kotlin Kapt : En el bloque superior del archivo build.gradle.kts (donde se encuentran los complementos o plugins), Configurar Data Binding dentro del bloque android, agrega lo siguiente para habilitar Data Binding , añade el siguiente código:

plugins {
    id("kotlin-kapt")
}

android {
    ...
    buildFeatures {
        dataBinding = true
    }
}

Con esto, se activa el soporte para Data Binding en tu proyecto, permitiéndote vincular directamente los componentes de la interfaz de usuario con tus datos de manera más eficiente y con menos código boilerplate. Asegúrate de sincronizar el proyecto después de realizar estos cambios.


  1. Añadir la dependencia del SDK. Una vez configurado el repositorio, agrega la dependencia del SDK en el archivo build.gradle.kts del módulo de la aplicación:

dependencies {
    implementation("org.bitbucket.miliopay:sdk-mobile-android:v0.3.2") // Reemplaza con la versión más reciente del SDK
}

Permisos

Para asegurarte de que tu aplicación tenga los permisos necesarios, debes agregar los permisos requeridos en el archivo AndroidManifest.xml. Este archivo es crucial para declarar las capacidades que tu aplicación necesita para interactuar con recursos específicos del dispositivo o con servicios de red.

Instrucciones para agregar permisos:

  1. Abre el archivo AndroidManifest.xml, ubicado en la carpeta src/main.
  2. Añade los permisos necesarios dentro del elemento , asegurándote de incluirlos antes de la etiqueta .

Por ejemplo, si necesitas acceso a la red y a la ubicación del dispositivo, tu archivo podría verse así:


<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">

    <!-- Permiso para acceder a Internet -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Permiso para acceder a la ubicación del dispositivo -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Otros permisos que puedas necesitar -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.CAMERA" />
  
      <uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="18" />
  
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <application
        android:allowBackup="true"
        android:label="@string/app_name"
        android:theme="@style/Theme.MyApp">
        <!-- Configuración de tu aplicación -->
    </application>
</manifest>

Transacciones

En resumen, el inputData funciona como un contenedor que le dice al SDK dónde debe enviarse la transferencia y qué cantidad debe transferirse, eliminando cualquier posible error manual.

🔐 Proceso de Encriptación y Seguridad en el SDK

El sistema de transferencias y recargas del SDK utiliza un mecanismo de encriptación de datos basado en criptografía de clave pública para garantizar la seguridad de la información en cada transacción.

🔑 1. ¿Por qué se usa una llave pública?

La llave pública, generada por un endpoint especializado, es la herramienta que permite cifrar la información antes de enviarla a través del SDK. Al encriptar los datos con esta llave, aseguramos que solo el servidor que tiene la llave privada correspondiente pueda descifrarlos, evitando accesos no autorizados o modificaciones en la información.

📲 2. Procesos que requieren encriptación con la llave pública

Cada una de las transacciones en el SDK debe pasar por este proceso de encriptación antes de ser enviada al servidor:

1️⃣ Transferencia con QR

Se escanea un código QR con los datos de la transacción.
La información se encripta con la llave pública antes de enviarla.
El servidor recibe los datos cifrados y los desencripta con su llave privada.

2️⃣ Transferencia Manual

El usuario ingresa manualmente los datos de la transacción (monto, cuenta destino, etc.).
Antes de enviarlos al SDK, los datos se cifran con la llave pública.
El servidor procesa la información tras desencriptarla.

3️⃣ Transferencia Inmediata

Similar a la transferencia manual, pero con una ejecución más rápida.
La información viaja encriptada con la llave pública para evitar manipulación en el proceso.

4️⃣ Recarga de Billetera

Para recargar fondos en la billetera digital, los datos (monto, origen, destino) se protegen con encriptación.
Solo el servidor, con su llave privada, podrá acceder a la información real y procesar la recarga.

🚀 3. Beneficios de este proceso de seguridad

✅ Protección de datos sensibles en cada transacción.
✅ Evita que terceros accedan o modifiquen la información.
✅ Cumple con estándares de seguridad y auditoría en encriptación.

Cada vez que se realiza una transferencia o recarga en el SDK, los datos deben encriptarse con la llave pública antes de enviarse. Solo el servidor con la llave privada correcta podrá descifrarlos y procesar la transacción, garantizando un entorno seguro y confiable para el usuario. 🔒


Configuración del SDK y personalización de colores

Antes de ejecutar cualquier transacción, el SDK se inicializa y se configuran los colores del tema.

🔹 Código relevante:

TransactionConfigSdk.setThemeColors(
    this,
    btnColorEnabled       = "#0e6655",  // Verde activo
    btnColorDisabled      = "#D3D3D3",  // Gris deshabilitado
    btnTextColorEnabled   = "#ffffff",  // Texto blanco
    btnTextColorDisabled  = "#888888",  // Texto gris
    layoutBackgroundColor = "#a2d9ce",  // Fondo verde claro
    textViewColor         = "#0b5345"   // Texto verde oscuro
)
TransactionConfigSdk.initialize(this)

Antes de enviar la información al SDK, los datos de la tarjeta deben ser encriptados utilizando la llave pública generada por el servidor. Este proceso protege la información del usuario y evita que terceros accedan a datos sensibles.


Ejemplo global de Encriptación

Este método se debe utilizar antes de enviar la información en las siguientes transacciones:

  1. Transferencia por QR
  2. Transferencia manual
  3. Transferencia inmediata
  4. Recarga de billetera

Cada transacción debe encriptar los datos sensibles antes de enviarlos al SDK de Milio.

import android.util.Base64
import java.security.KeyFactory
import java.security.PublicKey
import java.security.spec.X509EncodedKeySpec
import javax.crypto.Cipher

// Llave pública proporcionada por Milio (esto es solo un ejemplo, usa la real en producción)
private const val PUBLIC_KEY_PEM = """
-----BEGIN RSA PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7...
-----END RSA PUBLIC KEY-----
""".trimIndent()

/**
 *  Método para encriptar información con la llave pública de Milio.
 *
 * @param publicKeyPem Llave pública en formato PEM.
 * @param data Información que se desea encriptar.
 * @return Datos encriptados en Base64 o null en caso de error.
 */
fun encryptWithPublicKey(publicKeyPem: String, data: String): String? {
    return try {
        // Convertir la llave pública de formato PEM a PublicKey
        val publicKey = getPublicKeyFromPem(publicKeyPem)

        // Configurar el cifrado RSA con el padding OAEP seguro
        val cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")
        cipher.init(Cipher.ENCRYPT_MODE, publicKey)

        // Cifrar los datos y convertirlos a Base64
        val encryptedBytes = cipher.doFinal(data.toByteArray(Charsets.UTF_8))
        Base64.encodeToString(encryptedBytes, Base64.NO_WRAP)
    } catch (e: Exception) {
        e.printStackTrace()
        null
    }
}

/**
 * 🔑 Convierte una clave pública en formato PEM a un objeto PublicKey.
 */
private fun getPublicKeyFromPem(publicKeyPem: String): PublicKey {
    val keyBytes = Base64.decode(
        publicKeyPem.replace("-----BEGIN RSA PUBLIC KEY-----", "")
            .replace("-----END RSA PUBLIC KEY-----", "")
            .replace("\\s".toRegex(), ""),
        Base64.DEFAULT
    )
    val keySpec = X509EncodedKeySpec(keyBytes)
    return KeyFactory.getInstance("RSA").generatePublic(keySpec)
}

Transferencia por QR

Al momento de inicializar el SDK y abrir la ventana para la transferencia por QR, el parámetro inputData contiene un JSON que incluye el token asociado a la cuenta destino. Este token es generado previamente y representa la información necesaria para identificar la cuenta receptora y el monto a transferir. Al leer este token, el SDK utiliza sus credenciales y configuración para procesar la transferencia automáticamente, garantizando que el dinero sea enviado a la cuenta correcta con el valor especificado.

Permite escanear un código QR para realizar una transacción.

btnOpenSdk.setOnClickListener {
    val clientData = """
    { 
        "cardName": "Buffy Lanz",
        "cardNumber": "4364749491074401",
        "cardExpiry": "220801",
        "cardCVV": "652"                    
    }
    """.trimIndent()

    // Encriptar los datos antes de enviarlos al SDK
    val encryptedData = encryptWithPublicKey(PUBLIC_KEY_PEM, clientData)

    if (encryptedData != null) {
        TransactionConfigSdk.OpenMilioSdkQr(this, encryptedData)
    } else {
        println("❌ Error al encriptar la información")
    }
}

Transferencia manual

La transferencia manual permite enviar dinero sin necesidad de tokenizar previamente la cuenta de destino. En este caso, el usuario ingresa manualmente los datos de la tarjeta de crédito/débito y otros detalles requeridos para completar la transacción.

{
    "amount": 2500.00,
    "type": "OUT",
    "card": {
        "cardNumber": "4364749491074401",
        "cardExpiryDate": "12/26",
        "cardCVV": "652",
        "cardName": "Buffy Lanz"
    },
    "phone": "3026580102",
    "third": "Buffy Lanz"
}

Pago tokenizado

{
    "amount": 1500.00,
    "type": "OUT", 
    "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
}

📌 ¿Cómo llamar al SDK?

btnOpenSdk2.setOnClickListener {
    if (authToken != null) {
        val jsonData = """
        {
            "amount": 1500.00,
            "type": "OUT", 
            "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
        }
        """.trimIndent()

        // Encriptar los datos antes de enviarlos al SDK
        val encryptedData = encryptWithPublicKey(PUBLIC_KEY_PEM, jsonData)

        if (encryptedData != null) {
            TransactionConfigSdk.OpenMilioPayManualCard(this, authToken!!, encryptedData)
        } else {
            CustomToast.showError(this, "Error al encriptar la información", Toast.LENGTH_SHORT)
        }
    } else {
        CustomToast.showError(this, "El token no está disponible", Toast.LENGTH_SHORT)
    }
}

🚀 Formato optimizado y listo para usarse! 🎉

Cuando se ejecuta el código, el SDK abre una ventana interactiva para que el usuario pueda completar la transferencia de dinero. Los detalles del proceso, como el monto y la cuenta receptora, se gestionan automáticamente, proporcionando una experiencia de usuario fluida y segura.

Transferencia inmediata

La transferencia inmediata permite enviar dinero de forma rápida, ya sea ingresando manualmente los datos de la tarjeta de crédito/débito (sin tokenizar) o utilizando un identificador bancario (tokenizado).


🔹 Opción 1: Transferencia Sin Tokenizar (Ingresando los datos manualmente)

{
    "amount": 2500.00,
    "type": "OUT",
    "card": {
        "cardNumber": "4364749491074401",
        "cardExpiryDate": "12/26",
        "cardCVV": "652",
        "cardName": "Buffy Lanz"
    },
    "phone": "3026580102",
    "third": "Buffy Lanz"
}

🔹 Opción 2: Transferencia Tokenizada (Usando un banco previamente registrado)

{
    "amount": 1500.00,
    "type": "OUT", 
    "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
}

📍 ¿Cómo ejecutar la Transferencia Inmediata en el SDK?

btnOpenSdk3.setOnClickListener {
    if (authToken != null) {
        val jsonData = """
        {
            "amount": 1500.00,
            "type": "OUT", 
            "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
        }
        """.trimIndent()

        // Encriptar los datos antes de enviarlos al SDK
        val encryptedData = encryptWithPublicKey(PUBLIC_KEY_PEM, jsonData)

        if (encryptedData != null) {
            TransactionConfigSdk.OpenMilioPayAddFoundManualCard(this, authToken!!, encryptedData)
        } else {
            CustomToast.showError(this, "Error al encriptar la información", Toast.LENGTH_SHORT)
        }
    } else {
        CustomToast.showError(this, "El token no está disponible", Toast.LENGTH_SHORT)
    }
}

📍 Beneficios

✅ Permite realizar transferencias en segundos.
✅ Soporta dos modalidades: con tarjeta manual o con cuenta bancaria tokenizada.
✅ Evita pasos adicionales en transferencias recurrentes con bancos registrados.

🚀 Esta función permite procesar transferencias inmediatas con máxima flexibilidad! 🎉


Recargar billetera

Configuración para Recarga de Billetera con el SDK

Este ejemplo muestra cómo configurar y llamar al SDK para realizar una recarga de billetera, asegurando que la operación sea exitosa con los parámetros correctos.

La recarga de billetera permite agregar fondos a la cuenta del usuario. Se puede realizar de dos maneras:

  1. Ingresando manualmente los datos de la tarjeta de crédito/débito (sin tokenizar).
  2. Usando una cuenta bancaria previamente registrada (tokenizada).

🔹 Opción 1: Recarga Sin Tokenizar (Ingresando los datos manualmente)

{
    "amount": 2500.00,
    "type": "IN",
    "card": {
        "cardNumber": "4364749491074401",
        "cardExpiryDate": "12/26",
        "cardCVV": "652",
        "cardName": "Buffy Lanz"
    },
    "phone": "3026580102",
    "third": "Buffy Lanz"
}

🔹 Opción 2: Recarga Tokenizada (Usando un banco previamente registrado)

{
    "amount": 1500.00,
    "type": "IN", 
    "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
}

📍 ¿Cómo ejecutar la Recarga de Billetera en el SDK?

rbilletera2.setOnClickListener {
    if (authToken != null) {
        val jsonData = """
        {
            "amount": 1500.00,
            "type": "IN", 
            "thirdBankUUID": "dfb56715-ed55-4839-b5d0-18645da02dd0"
        }
        """.trimIndent()

        // Encriptar los datos antes de enviarlos al SDK
        val encryptedData = encryptWithPublicKey(PUBLIC_KEY_PEM, jsonData)

        if (encryptedData != null) {
            TransactionConfigSdk.OpenMilioPayRechargeWallet(
                this, 
                fragmentManager = supportFragmentManager, 
                authToken!!, 
                encryptedData
            )
        } else {
            CustomToast.showError(this, "Error al encriptar la información", Toast.LENGTH_SHORT)
        }
    } else {
        CustomToast.showError(this, "El token no está disponible", Toast.LENGTH_SHORT)
    }
}

📍 Beneficios

✅ Permite agregar fondos a la billetera del usuario de manera rápida.
✅ Compatible con tarjetas de crédito/débito o cuentas bancarias tokenizadas.
✅ Facilita la integración con múltiples métodos de pago.

🚀 Esta función permite gestionar recargas de billetera con total flexibilidad! 🎉



Resumen del SDK de Transferencias Milio

El SDK de Transferencias Milio, desarrollado en Kotlin para aplicaciones Android, proporciona una solución eficiente y segura para manejar diferentes tipos de transacciones financieras directamente desde tu aplicación. Este SDK permite a los usuarios realizar transferencias y gestionar su billetera de manera rápida y sencilla, ofreciendo las siguientes funcionalidades principales:

Funciones Principales

  1. Transferencia con QR
    Los usuarios pueden escanear un código QR para realizar transferencias inmediatas a cuentas específicas. Esto simplifica el proceso al evitar la necesidad de ingresar manualmente información del destinatario.
  2. Transferencia Manual
    Permite realizar transferencias ingresando manualmente los datos del destinatario, como número de cuenta o identificadores bancarios, ideal para situaciones en las que no se dispone de un QR.
  3. Transferencia Inmediata
    Ofrece la posibilidad de transferir dinero de manera instantánea entre cuentas bancarias, garantizando rapidez y seguridad en el proceso.
  4. Recargar mi Billetera
    Los usuarios pueden añadir saldo a su billetera digital desde cuentas bancarias u otras fuentes, lo que les permite gestionar su dinero de manera centralizada.

Características Técnicas

  • Desarrollado en Kotlin: Aprovecha las características modernas y concisas de Kotlin para garantizar un desarrollo eficiente y compatible con Android.
  • Modularidad: Cada funcionalidad está encapsulada, permitiendo una integración flexible según las necesidades de la aplicación.
  • Interfaz de Usuario Personalizable: La integración incluye ventanas y flujos visuales que pueden adaptarse a la estética de tu aplicación.
  • Seguridad: Todas las operaciones están respaldadas por autenticación mediante tokens, lo que asegura que las transacciones sean seguras y confiables.

Beneficios del SDK de Milio

  • Rápida Integración: Con unas pocas líneas de código, puedes añadir poderosas capacidades de transferencia y recarga a tu aplicación.
  • Experiencia de Usuario Intuitiva: Diseñado pensando en la facilidad de uso, proporciona flujos interactivos y eficientes.
  • Adaptado a Distintos Escenarios: Desde transferencias manuales hasta recargas automáticas, el SDK cubre las necesidades principales de transacciones digitales.
  • Soporte para Transacciones Locales e Internacionales: Facilita el manejo de transferencias tanto dentro como fuera de tu ecosistema financiero.

Este SDK es una herramienta poderosa para desarrolladores que buscan integrar soluciones financieras innovadoras y seguras en sus aplicaciones Android. ¡Descubre cómo el SDK de Transferencias Milio puede potenciar tu aplicación!

Para garantizar la seguridad de las transacciones en el SDK, es obligatorio encriptar la data antes de enviarla. Esto significa que los datos sensibles, como la información de la tarjeta o la cuenta, deben ser protegidos con la llave pública antes de ser transmitidos.