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

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

Paso 2: Mostrar un Widget

Para mostrar un Widget, primero define los callbacks y luego levanta el widget con initElements

let callbacks = ElementsCallbacks(
  onSuccess: { response in
    self.deunaSDK.close() // Cierra el Vault Widget
  },
  onError: { error in
    // Manejo de errores
    self.deunaSDK.close() // Cierra el Vault Widget
  },
  onClosed: {
    // El Vault Widget fue cerrado
  },
  onCanceled: {
    // El Vault Widget fue cerrado por el usuario
    // No es necesario llamar a close()
  },
  onEventDispatch: { type, response in
    // Escuchar los eventos
  }
)

// Muestra el Vault Widget
deunaSDK.initElements(
  userToken = "<DEUNA user token>", // optional
  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.
)

Parámetros

Parámetro	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 Widget. Consulta los eventos del Elements widget aquí
`userToken` (Opcional)	El bearer token del usuario de DEUNA. Cuando este es enviado, todas las acciones dentro del widget van a hacer sobre este usuario de DEUNA. Importante: si este campo es usado, el campo `userInfo` no se debe mandar.
`userInfo` (Opcional)	Instancia de la clase `DeunaSDK.ElementsUserInfo`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.
cssFile (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 `cssFile` 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 `[[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: `[ [ "name": 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.

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(
            callbacks: ElementsCallbacks(
                onSuccess: { data in 
                },
                onError: { error in 
                },
                onClosed: nil,
                onCanceled: {
                },
                onEventDispatch: { type, data in
                }
            ),
            userInfo: DeunaSDK.UserInfo(// required for Click To Pay
              firstName: "Esteban", 
              lastName: "Posada",
              email: "[email protected]"
            ),
            types: [
                [
                    "name": ElementsWidget.clickToPay // PASS THIS FOR CLICK TO PAY
                ]
            ]
        )

Paso 3: Escuchar los Eventos del 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	¿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 [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`	Se ejecuta cuando el widget se cierra, independientemente de si la operación fue exitosa o ocurrió un error. NOTA: El orden de ejecución de `onCanceled` y `onClosed` es el siguiente: - Si el usuario cierra manualmente el widget (presionando el botón X o deslizando el modal hacia abajo): `onCanceled` > `onClosed`. - Si se cierra el widget mediante código llamando a la función `close`, solo se ejecuta `onClosed`.
`onCanceled`	Se ejecuta cuando el usuario de forma intencional cierra el widget (presionando el botón X o deslizando el modal hacia abajo) sin que la operación se haya completado.
`onEventDispatch`	Se ejecuta cuando se detectan eventos específicos en el widget. Este callback contiene un parámetro de tipo `ElementsEvent` y la data `[String:Any]` vinculada al evento.

Paso 4 (Opcional): Cerrar el Widget

Por defecto, un Widget solo se cierra cuando el usuario presiona el botón de cerrar del widget o cuando presiona el botón de "retroceso" en iOS. 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:

let callbacks = ElementsCallbacks(
  onSuccess: { response in
    self.deunaSDK.close() // Cierra el Vault Widget
    // Tu código adicional
  }
)

// Muestra el Vault Widget
deunaSDK.initElements(
  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 un ejemplo de como cambiar los colores y el logo del vault widget mediante setCustomStyle

// Extension to convert a String to a Dictionary(JSON)
extension String {
    func toDictionary() -> [String: Any]? {
        guard let data = data(using: .utf8) else {
            return nil
        }
        do {
            let dictionary = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]
            return dictionary
        } catch {
            print("Error: \(error.localizedDescription)")
            return nil
        }
    }
}

.
.
.
let callbacks = ElementsCallbacks(
  onSuccess: ...,
  onError: ...,
  onClosed: ...,
  onCanceled: ...,
  onEventDispatch: { type, response in
    // Escuchar los eventos
           self.deunaSDK.setCustomStyle(data: """
                        {
                          "theme": {
                            "colors": {
                              "primaryTextColor": "#023047",
                              "backgroundSecondary": "#8ECAE6",
                              "backgroundPrimary": "#8ECAE6",
                              "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"
                                }
                              }
                            }
                          }
                        }
                        """.toDictionary() ?? [:]
        )     
  }
)
.
.
.

deunaSDK.initElements(
  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 del Vault Widget, revisa el proyecto de ejemplo proporcionado por DEUNA. Este ejemplo te ayudará a entender mejor cómo implementar el widget en tu aplicación iOS.

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