Payment Widget

Con el Payment Widget de DEUNA, acepta pagos de forma ágil y rápida en tu app Web. Sigue los siguientes pasos para capturar un pago utilizando el Payment Widget.

Paso 1: Completar los Primeros Pasos

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

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

Paso 2: Mostrar el Widget

Para mostrar el Payment Widget, llama a la función initPaymentWidget pasando los siguientes datos:

await DeunaSDK.initPaymentWidget({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  userToken: ..., // opcional
  styleFile: ..., // opcional
  callbacks: {
    // opcionales
    onClosed: (action) => console.log("cerrado desde Payment Widget"),
    onSuccess: (data) => console.log("purchaseResponse: ", data),
    onInstallmentSelected: (data) => console.log("installment selected"),
    onCardBinDetected: (paylod) => console.log("bin detected"),
    onError: (error) => console.log("error", error),
    onEventDispatch: (event, payload) => {
      console.log("onEventDispatch: ", { event, payload });
    },
  },
});

Parámetros

Atributos	Descripción
`orderToken`	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: Al momento de crear la orden con la API de DEUNA no se debe definir una URL de redirección (redirect_url) para que el callback onSuccess se ejecute correctamente.
`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.
`callbacks`	Los 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`

Ejemplo uso del parámetro `paymentMethods`

await DeunaSDK.initPaymentWidget({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  callbacks: ...,
  paymentMethods: [
    {
      paymentMethod: "<payment-method>",
      processors: ["<processor-name>"],
    },
  ],
});

Prioridad métodos de pago

Prioridad	Fuente de Configuración	Descripción	Comportamiento en caso de un solo método de pago
1	Métodos de pago pasados al ejecutar la función `.initPaymentWidget`	Los métodos de pago se muestran según los que se pasan al iniciar el widget, siempre y cuando estén activados y configurados a nivel comercio.	Si solo se pasa un método de pago, el widget abre automáticamente el formulario del método de pago sin mostrar botones.
2	Orden e `include_payment_options`	Se revisa la orden para verificar si `include_payment_options` tiene métodos de pago que estén configurados y activados a nivel comercio. Los métodos no configurados no se muestran.	Si solo se pasa un método de pago, el widget abre automáticamente el formulario del método de pago sin mostrar botones.
3	Métodos configurados a nivel comercio (API `/payment-methods`)	Si no se pasa ningún método de pago ni en la función `.initPaymentWidget` ni en `include_payment_options` al momento de crear la order, se toman los métodos configurados a nivel comercio.	Si solo se pasa un método de pago, el widget abre automáticamente el formulario del método de pago sin mostrar botones.

Paso 3: Escuchar los Eventos del Widget de Pago

Cuando una transacción es exitosa o falla, es importante actualizar tu interfaz para notificar a los usuarios sobre el resultado de la transacción. Esto lo puedes realizar escuchando los eventos del widget de pago mediante los callbacks.

Los callbacks pasados a la función initPaymentWidget 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?
`onSuccess`	Se ejecuta cuando se completó el pago. Este callback contiene un parámetro de tipo JSON con la información de la orden.
`onError`	Se ejecuta cuando ocurre un error al procesar el pago. Este callback contiene un parámetro tipo JSON el cual identifica el tipo de error producido al momento de procesar el pago.
`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).
`onPaymentProcessing` (Opcional)	Este callback se ejecutará cuando el usuario presiona en el botón pagar y se esta procesando el pago. NOTA: Si existe algún campo incorrecto en el formulario de pago este evento no se ejecutará.
`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.initPaymentWidget({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  callbacks: {
    onSuccess: ...,
    onInstallmentSelected: (data) => {
    },
    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, el widget de pago 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 un pago es exitoso.

await DeunaSDK.initPaymentWidget({
  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 payment 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.initPaymentWidget({
  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",
              },
            },
          },
        },
      });
    },
  },
});

Refrescar el widget de pago

La función refetchOrder actualiza el widget de pago y retorna los datos de la orden actualizada.

const order = await DeunaSDK.refetchOrder();

Esta función es útil, por ejemplo, cuando el comercio ofrece promociones. Un caso común es una "promoción del 20% al pagar con Mastercard". En este escenario, el comercio escucha el evento onCardBinDetected para identificar la franquicia de la tarjeta. Luego, el comercio actualiza la orden en DEUNA (siendo el responsable de calcular las promociones) y, a través de esta función, notifica al widget para que se actualice, ya que el monto de la orden podría haber cambiado.

A continuación se muestra un ejemplo del uso de la función refetchOrder.

await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
    callbacks: {
        onCardBinDetected: async (cardBinMetadata) => {
            if (cardBinMetadata.cardBrand === "Mastercard") {
                const order = await DeunaSDK.refetchOrder();
                if (order) {
                    console.log("ORDER", order);
                }
            }
        },
    },
});