Payment Vault - Web

Vault es una herramienta que permite almacenar tarjetas de crédito o débito en nuestra red sin necesidad de procesar una compra.

Entre sus principales funcionalidades se incluyen:

• 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 initElements 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
  hidePayButton: ..., // 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

Parámetro behavior (Opcional)

El método initElements acepta el parámetro behavior que permite personalizar el comportamiento del widget de pago, incluyendo:

• Habilitar pagos con múltiples tarjetas.
• Entre otras opciones de configuración.

Nota: Estas configuraciones aplican a todos los métodos de pago habilitados en el widget.

Comportamiento de los métodos de pago paymentMethods

El parámetro paymentMethods dentro de behavior permite configurar comportamientos globales para todos los métodos de pago habilitados en el widget.

• flowType (Tipo de Flujo)

  Valores (string): twoStep o singleStep

  Compatibilidad actual: Exclusivo para PayPal.

  Controla el flujo de visualización para métodos de pago específicos que requieren mostrar información previa antes del formulario de pago.

DeunaSDK.initPaymentWidget({
  orderToken: "TOKEN",
  ...
  behavior:{
		paymentMethods:{
      flowType: 'twoStep'
    }
  }
});

Pago Dividido en Múltiples Tarjetas (Split Payments)

La función de Split Payments permite a los clientes dividir el pago de una compra entre múltiples tarjetas de crédito/débito.

Requisitos Previos:

• La opción debe estar habilitada en la configuración del comercio.
• Actualmente solo se admite división entre 2 tarjetas como máximo.

DeunaSDK.initPaymentWidget({
  orderToken: "TOKEN",
  ...
  behavior:{
		paymentMethods:{
      creditCard: {
        splitPayments: {
          maxCards: 2 // Número máximo de tarjetas permitidas
        }
      }
    }
  }
});

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 initElements te permite escuchar los eventos del widget. Define los callbacks respectivos para actualizar la interfaz de tu app.

3.1. Callbacks

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",
              },
            },
          },
        },
      });
    },
  },
});

Personalización del Botón "Pagar": Usa tu propio botón 😌

El SDK de DEUNA permite ocultar el botón nativo de “Guardar” incluido en el Payment Vault y reemplazarlo por un botón personalizado integrado en la interfaz del comercio.

Esta funcionalidad es ideal para:

• Mantener una experiencia de usuario consistente con el diseño del comercio.
• Integrar el guardado de tarjetas dentro de flujos propios o pasos personalizados.
• Tener un mayor control sobre el momento exacto en que se dispara la acción de guardar el método de pago.

1. Ocultar el botón nativo

Al inicializar el widget, activa el parámetro hidePayButton:

await DeunaSDK.initElements({
  orderToken: "order_ABC123",
  hidePayButton: true, // ← Oculta el botón nativo (default: false),
  ...
});

Comportamiento:

• Si hidePayButton: false (o no se define), el widget muestra su botón estándar.
• Esta configuración no puede cambiarse dinámicamente después de inicializar el widget.

2. Botón personalizado: Validar datos y ejecutar el pago

Cuando se utiliza DeunaSDK.initElements(...), el usuario puede emplear los siguientes métodos para validar y ejecutar el guardado de tarjeta.

Consideraciones

❗️

Se recomienda usar isValid() antes de llamar a submit() para evitar errores en el proceso de guardado

• isValid() y submit() pueden usarse en cualquier momento, sin depender de manualSubmit.
• Si hidePayButton es true, el botón de guardar tarjeta no se mostrará y el guardado deberá ser gestionado con submit().
• Si el flujo de guardado aún no está disponible, submit() siempre devolverá un error con el mensaje "The submit flow is not available".
• Las respuestas de estos dos métodos isValid y submit devuelven una promesa