Los widgets de nuestra bóveda de pagos es la manera de integrar funcionalidades como wallets, tokenización, etc. sin procesar el pago.

La bóveda de pagos de DEUNA son distintos tipos de widgets que permiten a nuestros comercios realizar tareas como:

Guardar tarjetas de crédito y débito de forma segura por medio de nuestro VAULT Widget.
Realizar pagos con Click To Pay por medio de nuestro Click To Pay Widget.
- Ejemplo:

Paso 1: Completar los Primeros Pasos

Antes de integrar los widgets, es necesario que completes la sección de primeros pasos. En esta sección, te explicamos los requisitos necesarios y cómo inicializar el SDK. Puedes encontrar más información en Primeros Pasos con el SDK de Android.

Una vez que hayas completado estos pasos, podrás continuar con el paso 2.

Paso 2: Mostrar un Widget

2.1 Mostrar el Widget en un Dialogo

Para mostrar el widget en un DialogFragment, llama a la función initElements pasando los siguientes datos:

val callbacks = ElementsCallbacks().apply{
    onSuccess = { response ->
        deunaSDK.close() // Cierra el widget
    },
    onError = { error ->
        // handle the error
        deunaSDK.close() // Cierra el  widget
    },
    onClosed = { action ->
       // El VAULT widget fue cerrado
    },
    onEventDispatch = { type, response ->
       // Escuchar los eventos
    }
}

// Muestra el VAULT widget
deunaSDK.initElements(
  context = YOUR_ACTIVITY_CONTEXT,
  userToken = "<DEUNA user token>", // opcional
  userInfo = DeunaSDK.UserInfo("Esteban", "Posada", "[email protected]"), // optional
  callbacks = callbacks,
  types = ...,// opcional, Si no se pasa este valor por defecto se mostrará el VAULT Widget.
  widgetExperience = ElementsWidgetExperience( // opcional
    userExperience = ElementsWidgetExperience.UserExperience(
      showSavedCardFlow = false, // opcional
      defaultCardFlow = false // opcional
    )
  )
)

2.1. Mostrar el Widget de forma embebida (Jetpack Compose)

Para mostrar el widget de forma embebida en tu aplicación con Compose, usa el composable AndroidView y el view DeunaWidget.

IMPORTANTE: DeunaWiget no admite dimensiones dinámicas por lo que el contenedor del AndroidView debe definir las dimensiones que utilizará el widget de DEUNA.

@Composable
fun YourScreen(
    deunaSDK: DeunaSDK,
    orderToken: String,
    userToken: String,
) {
    // Maintains the Deuna WebView instance across recompositions
    val deunaWidget = remember { mutableStateOf<DeunaWidget?>(null) }

    Column(modifier = Modifier.padding(16.dp)) {
        // Container for the embedded payment widget
        // MUST specify dimensions (e.g., .height(400.dp) or .weight(1f) in parent Column)
        Box(
            modifier = yourModifier 
        ) {
            AndroidView(
                modifier = Modifier.fillMaxSize(),
                factory = { context ->
                    DeunaWidget(context).apply {
                        // Set true to handle payment submission manually via submit()
                        // Set false to use Deuna's built-in payment button
                        hidePayButton = true

                        // Configure payment widget callbacks
                        bridge = ElementsBridge(
                            callbacks = ElementsCallbacks().apply {
                                onSuccess = { response -> 
                                }
                                onError = { error -> 
                                }
                            },
                            deunaWidget = this
                        )

                        // Initialize widget with payment details
                        val widgetUrl = deunaSDK.buildElementsWidgetUrl(
                            orderToken = orderToken,
                            userToken = userToken
                        )
                        loadUrl(widgetUrl)
                        
                        // Store reference for later submission
                        deunaWidget.value = this
                    }
                }
            )
        }

        Spacer(modifier = Modifier.height(16.dp))

        // Custom payment submission button
        // Only needed when hidePayButton = true
        Button(
            onClick = {
                // Programmatically submit payment details to Deuna
                // Required when hidePayButton = true
                deunaWidget.value?.submit { result ->
                    // Handle submission result
                    // result.status: "success"|"error"
                    // result.message: Detailed status message
                }
            },
            modifier = Modifier.fillMaxWidth()
        ) {
            Text("Complete Payment")
        }
    }

    // Critical: Clean up DeunaWidget resources when composable leaves composition
    DisposableEffect(Unit) {
        onDispose {
            deunaWidget.value?.destroy()
            Log.d("DeunaWidget", "WebView resources cleaned up")
        }
    }
}

Parámetros

Parámetro	Dialogo	Embebido	Descripción
`callbacks`	✅	✅	Una instancia de la clase ElementsCallbacks, la cual contiene callbacks que serán llamados en caso de éxito, error, o cuando el widget se cierre.
`closeEvents`	✅	❌	Un conjunto de valores de tipo ElementsEvent que especifican cuándo cerrar automáticamente el Elements widget. Consulta los eventos del Elements widget aquí
`userToken` (Opcional)	✅	✅	El token de un usuario obtenido usando la API de DEUNA https://docs.deuna.com/reference/users-register https://docs.deuna.com/reference/request-otp https://docs.deuna.com/reference/login-with-otp
`orderToken`(Opcional)	✅	✅	El orderToken es un token único generado para la orden de pago. Este token es generado a través del API de DEUNA y debes implementar el endpoint correspondiente en tu backend para obtener esta información. IMPORTANTE: Se puede extraer la información de usuario que esta disponible en billing_address para usar dentro del widget.
`userInfo`(Opcional)	✅	✅	Instancia de la clase `DeunaSDK.UserInfo` que contiene `firstName`, `lastName` y `email`. Importante: en caso que el `userToken` no se enviado o sea un string vacío (""), este parámetro es requerido.
`styleFile` (Opcional)	✅	✅	UUID proporcionado por DEUNA. Esto aplica si quieres configurar un archivo `custom styles` personalizado (Cambiar colores, textos, logo, etc). Si se proporciona un valor válido para `styleFile` el vault widget utilizará la configuración de la UI proporcionada por la configuración del tema que coincida con el UUID proporcionado.
`types`(Opcional)	✅	✅	Una instancia de tipo `List<Map<String,Any>>` con un listado de los tipos de widgets que debe renderizar la función `initElements`. Los valores permitidos son: `vault` y `click_to_pay` . Ejemplo: `listOf( mapOf("name" to ElementsWidget.VAULT) )` NOTA: Si no se pasa este parámetro por defecto se mostrará el Vault Widget de DEUNA para guardar tarjetas de crédito y débito.
`language`(Opcional)	✅	✅	Este parámetro permite especificar el idioma en el que se mostrará la interfaz del widget. Debe proporcionarse como un código de idioma válido (por ejemplo, "es" para español, "en" para inglés, "pt" para portugués). Comportamiento: - Si se proporciona: El widget utilizará el idioma especificado en este parámetro, independientemente de la configuración del comerciante. - Si no se proporciona: El widget utilizará el idioma configurado por el comerciante.
`widgetExperience`(Opcional)	✅	✅	Overrides a configuraciones del merchant. Actualmente soportadas por el widget son las siguientes: userExperience.showSavedCardFlow: Muestra toggle de guardado de tarjetas. userExperience.defaultCardFlow: Muestra toggle para guardar la tarjeta como predeterminada.

Click To Pay Widget

Usando el parámetro types de la función initElements puedes realizar un pago con Click To Pay. El siguiente fragmento de código muestra como mostrar el ClickToPay widget:

NOTA: El parámetro userInfo es obligatorio para poder mostrar el ClickToPay widget.

deunaSDK.initElements(
  context = this,
  userInfo = UserInfo(// Obligatorio para click_to_pay
    firstName = "Esteban",
    lastName = "Posada",
    email = "[email protected]",
  ),
  types = listOf(
    mapOf(
      "name" to ElementsWidget.CLICK_TO_PAY // Muestra el ClickToPay widget
    )
  ),
  callbacks = ElementsCallbacks().apply {
    onSuccess = {
      deunaSdk.close()
    }
    onEventDispatch = ...
    onError = ...
    onClosed = ...
  },
)

Paso 3: Escuchar los Eventos de un Widget

Es crucial manejar adecuadamente los eventos del Widget para ofrecer una experiencia fluida a los usuarios. Define los callbacks necesarios para actualizar la interfaz de tu aplicación.

3.1 Callbacks

Callback	Dialogo	Embebido	¿Cuándo se dispara?
`onSuccess`	✅	✅	Se ejecuta cuando una tarjeta se guarda exitosamente o cuando el pago con Click to Pay fue exitoso. Este callback contiene un parámetro de tipo Map<String,Any> .
`onError`	✅	✅	Se ejecuta cuando ocurre un error la procesar la operación del widget mostrado. Este callback contiene un parámetro de tipo `ElementsError`
`onClosed` (Opcional)	✅	❌	Se ejecuta cuando se cierra el widget de pago. Este callback contiene un parámetro de tipo enum `CloseAction` con los siguientes valores: - `userAction`: Cuando el widget fue cerrado manualmente por el usuario, presionando en el botón cerrar (X) o en el botón de retroceso en Android sin que la operación se haya completado. - `systemAction`: Cuando el widget se cierra debido a la ejecución de la función `close`.
`onEventDispatch` (Opcional)	✅	✅	Se ejecuta cuando se detectan eventos específicos en el widget. Este callback contiene un parámetro de tipo `ElementsEvent`

Paso 4 (Opcional): Cerrar el Widget

Por defecto, los Element Widgets solo se cierran cuando el usuario presiona el botón de cerrar del widget o cuando presiona el botón de "retroceso" en Android. Para cerrar el modal cuando una operación es exitosa o cuando ocurre un error, debes llamar a la función close.

El siguiente código de ejemplo muestra cómo cerrar el widget

val callbacks = ElementsCallbacks().apply {
    onSuccess = { response ->
        deunaSDK.close() // Cierra el Vault Widget
        // Tu código adicional
    }
}

// Muestra el Vault Widget
deunaSDK.initElements(
    context = YOUR_ACTIVITY_CONTEXT,
    userToken = "<DEUNA user token>", // optional
    userInfo = DeunaSDK.UserInfo("Esteban", "Posada", "[email protected]"), // optional
    callbacks = callbacks
)

Paso 5 (Opcional): Personalizar la apariencia del widget

Si el vault widget esta visible y quieres personalizar la apariencia del mismo utiliza la función setCustomStyle.

Consulta la siguiente documentación para conocer más a detalle todas las opciones de personalización del vault widget.

A continuación se muestra como cambiar los colores y el logo del vault widget mediante setCustomStyle

val callbacks = ElementsCallbacks().apply{
    onSuccess = ...,
    onError = ...,
    onClosed = ...,
    onCanceled = ...,
    onEventDispatch = { type, response ->
       // Escuchar los eventos
       deunaSDK.setCustomStyle(
             data = JSONObject(
                        """
                        {
                          "theme": {
                            "colors": {
                              "primaryTextColor": "#023047",
                              "backgroundSecondary": "#8ECAE6",
                              "backgroundPrimary": "#F2F2F2",
                              "buttonPrimaryFill": "#FFB703",
                              "buttonPrimaryHover": "#FFB703",
                              "buttonPrimaryText": "#000000",
                              "buttonPrimaryActive": "#FFB703"
                            }
                          },
                          "HeaderPattern": {
                            "overrides": {
                              "Logo": {
                                "props": {
                                  "url": "https://images-staging.getduna.com/ema/fc78ef09-ffc7-4d04-aec3-4c2a2023b336/test2.png"
                                }
                              }
                            }
                          }
                        }
                        """
         ).toMap()
        )
    }
}

// Muestra el VAULT widget
deunaSDK.initElements(
    context = YOUR_ACTIVITY_CONTEXT,
    userToken = "<DEUNA user token>", // optional
    userInfo = DeunaSDK.UserInfo("Esteban", "Posada", "[email protected]"), // optional
    callbacks = callbacks
)

Paso 6 (Opcional): Revisar Ejemplo Demo App

Para comprender mejor la integración de los Element Widgets, revisa el proyecto de ejemplo proporcionado por DEUNA. Este ejemplo te ayudará a entender mejor cómo implementar los widgets en tu aplicación Android.

Para acceder al proyecto de ejemplo y obtener más información, consulta la documentación del Ejemplo de Proyecto para Android.

Ocultar el botón de pago (Widget Embebido)

Cuando se muestra el widget de forma embebida se puede utilizar la propiedad hidePayButton para esconder el botón de pago del DeunaWidget.

// Maintains the Deuna WebView instance across recompositions
val deunaWidget = remember { mutableStateOf<DeunaWidget?>(null) }
.
.
.

DeunaWidget(context).apply {
   // Set true to handle payment submission manually via submit()
   // Set false to use Deuna's built-in payment button
   hidePayButton = true
   .
   .
   .
 }

deunaWidget.value?.isValid { it ->  }
deunaWidget.value?.submit {result -> }

Puedes emplear las siguientes funciones para validar y ejecutar el pago.

Método	Descripción	Respuesta
`.isValid{...}`	Valida si la información ingresada es correcta y si el pago puede ser procesado.	`true` si la información es válida, `false` en caso contrario.
`.submit{...}`	Ejecuta el proceso de pago, equivalente a presionar el botón de pagar. Realiza las mismas validaciones internas.	`{ status: "success", message: "Pago procesado exitosamente" }` o `{ status: "error", message: "The submit flow is not available" }`

Consideraciones

Se recomienda usar isValid{} antes de llamar a submit{} para evitar errores en el proceso de pago.
Si el flujo de pago aún no está disponible, submit{} siempre devolverá un error con el mensaje "The submit flow is not available"