Los widgets de Payment Vault integran funcionalidades como wallets y tokenización sin procesar el pago.

El Payment Vault de DEUNA contiene distintos tipos de widgets que te permiten:

Guardar tarjetas de crédito y débito de forma segura en el Vault.
Realizar pagos con Click To Pay con el Click To Pay Widget.

Inicializa el Widget

Antes de integrar el Payment Widget, completa los Primeros Pasos - iOS.

1. Muestra el Widget

Muestra el Payment Vault Widget de dos formas:

Modal: Llama una función para mostrar el Widget.
SwiftUI: Muestra el Widget embebido.

Mostrar en un Modal

Para mostrar el Payment Widget en un modal (pageSheet) llama a la función initElements pasando los siguientes datos:

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: { action in
    // El Vault Widget fue cerrado
  },
  onEventDispatch: { type, response in
    // Escuchar los eventos
  }
)

// Muestra el Vault Widget
deunaSDK.initElements(
  userToken = "<DEUNA user token>", // optional
  userInfo = DeunaSDK.UserInfo("Esteban", "Posada", "eposada@deuna.com"), // 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: true, // Opcional
        defaultCardFlow: true // Opcional
      )
   )
)

Mostrar el Widget embebido (SwiftUI)

Utiliza el view DeunaWidget para mostrar el payment widget de forma embebida en tu app con SwiftUI.

import DeunaSDK
import SwiftUI

struct YourView: View {
    let deunaSDK: DeunaSDK
    var body: some View {
        VStack {
            DeunaWidget(
                deunaSDK: deunaSDK,
                configuration: ElementsWidgetConfiguration(
                    ...
                    callbacks: PaymentWidgetCallbacks(
                        onSuccess: { res in
                           // NOTE: Explicitly release widget resources
                           // when no longer needed
                           // to prevent memory leaks and ensure proper cleanup.
                            deunaSDK.dispose()
                        },
                        onError: { error in
                            
                        },
                        onEventDispatch: { event, data in
                            
                        }
                    )
                )
            )
        }
    }
}

Parámetros

Parámetro	Modal	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.
`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.
`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.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.
`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 `[[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.
`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

Realiza pagos con Click to Pay usando el parámetro types de la función initElements.

📘
El parámetro userInfo es obligatorio para poder mostrar el ClickToPay Widget.

        deunaSDK.initElements(
            callbacks: ElementsCallbacks(
                onSuccess: { data in 
                },
                onError: { error in 
                },
                onClosed: nil,
                onEventDispatch: { type, data in
                }
            ),
            userInfo: DeunaSDK.UserInfo(// required for Click To Pay
              firstName: "Esteban", 
              lastName: "Posada",
              email: "esteban@deuna.com"
            ),
            types: [
                [
                    "name": ElementsWidget.clickToPay // PASS THIS FOR CLICK TO PAY
                ]
            ]
        )

2. Escucha 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.

Callbacks

Callback	Modal	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 [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 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 deslizando el modal hacia abajo) 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`	✅	✅	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.

3. Cierra el Widget

Cuando se muestra el widget en un modal, este 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", "eposada@deuna.com"), // optional
  callbacks: callbacks
)

Funcionalidades opcionales

Además de los pasos obligatorios para operar el widget, tienes las siguientes opciones de personalización:

Personalizar la apariencia del widget

Utiliza la función setCustomStyle para personalizar la apariencia del Widget.

await DeunaSDK.setCustomStyle({...});

📘
Para más información, ve a Personalización de estilos.

Ejemplo

// 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: ...,
  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", "eposada@deuna.com"), // optional
  callbacks: callbacks
)

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.

Ocultar el botón de pago (Widget Embebido)

Cuando se muestra el widget de forma embebida con el view DeunaWidget puedes ocultar el botón de pago del widget usando el parámetro hidePayButton: true.

DeunaWidget(
  deunaSDK: deunaSDK,
  configuration: ElementsWidgetConfiguration(
    hidePayButton: true // Set true to hide the pay button
    ...
  )
)

Si se oculta el botón de pago del widget de DEUNA deberás utilizar las funciones .isValid {} y .submit{} para completar el flujo de pago.

Método	Descripción	Respuesta
`deunaSdk.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.
`deunaSdk.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:

Si hidePayButton es false o no se define, el botón de pagar será visible y el flujo de pago funcionará de manera automática.
Si hidePayButton es true, el botón de pagar no se mostrará y el pago debe ser gestionado con submit{}.
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"