Documentación

Payment Vault - Web

Suggest Edits

Elements Widget es una herramienta integrada que permite a los comercios ofrecer múltiples métodos de pago a sus clientes de manera sencilla y eficiente. Este widget permite guardar tarjetas de crédito a nuestra red sin procesar una compra.

Payment Vault de DEUNA es un widgets que permite 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.

También puedes integrar el Click To Pay widget via iframe. Consulta la documentación aquí.


Paso 1: Completar los Primeros Pasos

Antes de integrar el Payment Vault, 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.

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

Paso 2: Mostrar el Widget

Para mostrar Vault Widget, llama a la función initElementsWidget pasando los siguientes datos:

await DeunaSDK.initElements({
  orderToken: "<DEUNA order token>", // opcional: Se puede extraer informacion del usuario de la orden
  userToken: ..., // opcional
  styleFile: ..., // opcional
  language: ..., // opcional
  manualSubmit: ..., // opcional
  widgetExperience: { // OPCIONAL
    userExperience: {
      showSavedCardFlow: true, // Opcional: muestra toggle/checkbox para guardar tarjetas
      defaultCardFlow: true // Opcional: muestra toggle/checkbox para guardar la tarjeta como predeterminada
    }
	},
  userInfo: { // Opcional
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
  },
  types: ...// opcional, Si no se pasa este valor por defecto se mostrará el VAULT Widget.
  callbacks: {
    // opcionales
    onClosed: (action) => console.log("cerrado desde Payment Widget"),
    onSuccess: (data) => console.log("purchaseResponse: ", data),
    onInstallmentSelected: (data) => console.log("installment selected"),
    onCardBinDetected: (payload) => console.log("bin detected"),
    onError: (error) => console.log("error", error),
    onEventDispatch: (event, payload) => {
      console.log("onEventDispatch: ", { event, payload });
    },
  },
});

Parámetros

AtributosDescripción
orderTokenEl 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 informacion de usuario que esta disponible en billing_address para usar dentro del widget.
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: para que este userToken sea usado y se le muestren las tarjetas guardadas al cliente, el correo asociado a ese userToken debe ser el mismo que se envía al crear la orden en billing_address.email. En caso que ambos correos no coincidan, se usará el flujo sin mostrar las tarjetas por seguridad.
userInfoInformacion de usuario que se pasara al widget, informacion posible disponible a pasar son: email, firstName, lastName. Todas son opcionales.
widgetExperienceOverrides 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.
language
(Opcional)		El idioma del widget de pago se puede sobrescribir enviando un parámetro con un idioma soportado. Los principales idiomas disponibles son en (inglés), es (español) y pt (portugués). Si no se envía este parámetro, se utilizará el idioma configurado por defecto.
callbacksLos callbacks son funciones de retorno que se encargan de escuchar y manejar los eventos del widget de pago. Estos eventos permiten gestionar acciones específicas basadas en el estado del pago. Los principales callbacks incluyen: onSuccess, onError, onClosed, onCanceled, onCardBinDetected, onInstallmentSelected
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 payment widget utilizará la configuración de la UI proporcionada por la configuración del tema que coincida con el UUID proporcionado.
paymentMethods (Opcional)Una lista métodos de pago permitidos. Este parámetro determina qué tipo de widget se debe renderizar.
target(Opcional)Por defecto, los widgets de DEUNA se despliegan en un modal.
Si prefieres mostrar el widget dentro de un elemento HTML específico, utiliza el parámetro target para especificar el ID o el nombre de la clase del elemento HTML (mediante selectores) donde deseas renderizar el widget.

Ejemplos: #my-container , .my-container
types (Opcional)Una instancia 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": "click_to_pay" } ]

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.

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:

await DeunaSDK.initElements({
  orderToken: "<DEUNA order token>", // opcional: Se puede extraer informacion del usuario de la orden
  userInfo: { // Opcional
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
  },
  types: [{ name: "click_to_pay" }],
  callbacks: {
    // opcionales
    onClosed: (action) => console.log("cerrado desde Click to Pay"),
    onSuccess: (data) => console.log("purchaseResponse: ", data),
    onInstallmentSelected: (data) => console.log("installment selected"),
    onCardBinDetected: (payload) => console.log("bin detected"),
    onError: (error) => console.log("error", error),
    onEventDispatch: (event, payload) => {
      console.log("onEventDispatch: ", { event, payload });
    },
  },
});

Paso 3: Escuchar los Eventos de Vault Widget

Cuando el guardado de una tarjeta se realiza exitosamente o falla, esto lo puedes realizar escuchando los eventos de Vault Widget mediante los callbacks.

Los callbacks pasados a la función initElementsWidget te permite escuchar los eventos del widget. Define los callbacks respectivos para actualizar la interfaz de tu app.

3.1. Callbacks

Callback¿Cuándo se dispara?
onSuccessSe ejecuta cuando se guardó una tarjeta exitosamente. Este callback contiene un parámetro de tipo JSON con la información de la orden.
onErrorSe ejecuta cuando ocurre un error al guardar la tarjeta. Este callback contiene un parámetro tipo JSON el cual identifica el tipo de error producido.
onClosed (Opcional)Se ejecuta cuando se cierra el widget de pago.

Este callback contiene un parámetro de tipo string cuyos valores pueden ser uno de los siguientes:

- userAction: Cuando el widget fue cerrado manualmente por el usuario (presionando en el botón cerrar X) sin que la operación se haya completado.

- systemAction: Cuando el widget se cierra debido a la ejecución de la función close.
onCardBinDetected (Opcional)Se ejecuta cuando el widget de pago detecta el BIN de una tarjeta de crédito o débito ingresada o cuando el usuario borra el número de la tarjeta ingresada.

Este callback contiene un parámetro de tipo JSON con la información del bin y la marca de la tarjeta ingresada.

NOTA: El parámetro de tipo JSON será nulo cuando el usuario elimina el texto ingresado en el campo del número de tarjeta.
onInstallmentSelected (Opcional)Si la orden se puede diferir, este callback se ejecutará cuando el usuario seleccione los meses a diferir.

Este callback contiene un parámetro de tipo JSON con la información de los meses a diferir seleccionados por el usuario.

NOTA: El parámetro de tipo JSON será nulo cuando el usuario selecciona pago corriente (Sin cuotas).
onEventDispatch (Opcional)Se ejecuta en todas los eventos que pueda producir el widget.
Este callback contiene un parámetro de tipo string y la data (JSON) asociada a dicho evento

Ejemplo:

await DeunaSDK.initElements({
  orderToken: "<DEUNA order token>",
  userToken: "...",
  callbacks: {
    onSuccess: ...,
    onCardBinDetected: async (cardBinMetadata) => {
      if (cardBinMetadata) {
        // ...
      }
    },
    onError: (error) => console.log("error", error),
    onEventDispatch: (event, payload) => {
	    console.log("onEventDispatch: ", { event, payload });
	  }
  },
});

Paso 4 (Opcional): Cerrar el Widget

Por defecto, Vault Widget solo se cierra cuando el usuario presiona el botón de cerrar del widget. Para cerrar el modal cuando un pago es exitoso o cuando ocurre un error, debes llamar a la función close.

await DeunaSDK.close();

El siguiente código de ejemplo muestra cómo cerrar el widget cuando el guardado de una tarjeta es exitoso.

await DeunaSDK.initElements({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  callbacks: {
    // opcionales
    onSuccess: async (data) => {
      await DeunaSDK.close(); // Cierra el widget de pago
      console.log("purchaseResponse: ", data);
    },
  },
});

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.

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

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

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

await DeunaSDK.initElements({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  callbacks: {
    onSuccess: ...,
    onCardBinDetected: async (cardBinMetadata) => {
      await DeunaSDK.setCustomStyle({
        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",
              },
            },
          },
        },
      });
    },
  },
});

Métodos para el Guardado de Tarjeta

Cuando se utiliza DeunaSDK, el usuario puede emplear los siguientes métodos para validar y ejecutar el guardado de tarjeta, independientemente de si manualSubmit está activado.

MétodoDescripciónRespuesta
DeunaSDK.isValid()Valida si la información de la tarjeta ingresada es correcta y si puede ser guardada.true si la información es válida, false en caso contrario.
DeunaSDK.submit()Ejecuta el proceso de guardado de tarjeta, equivalente a presionar el botón de guardar.{ status: "success", message: "Tarjeta guardada exitosamente" } o { status: "error", message: "The submit flow is not available" }

Consideraciones

  • isValid() y submit() pueden usarse en cualquier momento, sin depender de manualSubmit.
  • Si manualSubmit es true, el botón de guardar tarjeta no se mostrará y el guardado deberá ser gestionado con submit().
  • Se recomienda usar isValid() antes de llamar a submit() para evitar errores en el proceso de guardado.
  • Si el flujo de guardado aún no está disponible, submit() siempre devolverá un error con el mensaje "The submit flow is not available".

Updated 2 days ago