Payment Widget - Web

El Payment 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 es compatible tanto con Métodos de Pago Alternativos (APMs) como con tarjetas de crédito y débito, proporcionando flexibilidad en las opciones de pago para los usuarios.

El Payment Widget soporta:

• Métodos de Pago Alternativos (APMs): como OXXO, KueskiPay, Aplazo, entre otros.
• Tarjetas de Crédito y Débito: MasterCard, Visa, American Express, etc.

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: (payload) => console.log("bin detected"),
    onError: (error) => console.log("error", error),
    onEventDispatch: (event, payload) => {
      console.log("onEventDispatch: ", { event, payload });
    },
  },
});

Parámetros

2.1. Mostrar u ocultar métodos de pago

El Payment Widget puede desplegar varios métodos de pago disponibles para una orden, sin que el comercio tenga que agregar individualmente cada botón de APM en su Frontend.

Al invocar la función initPaymentWidget, el parámetro paymentMethods define los métodos de pago que el widget mostrará:

• Si se pasa 1 solo método en paymentMethods el widget abre automáticamente el formulario del método de pago sin mostrar botones de otros AMPs.

  

// example of OXXO
await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>",
    callbacks: ...,
    paymentMethods: [
        {
            paymentMethod: "voucher",
            processors: ["payu_oxxo_cash"],
        },
    ],
});

// example of Click to Pay
await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>",
    callbacks: ...,
    paymentMethods: [
        {
            paymentMethod: "wallet",
            processors: ["click_to_pay"],
        },
    ],
});

• Si se especifica más de 1 método de pago en el parámetro paymentMethods, el widget solo mostrará esos métodos habilitados los cuales deben estar configurados a nivel comercio.

  • 📘

    For credit card processing there is no need to pass the processors's array since the merchant can have multiple configured for the use of routing

    

await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>",
    callbacks: ...,
    paymentMethods: [
        {
           paymentMethod: "credit_card",
        },
        {
            paymentMethod: "bnpl",
            processors: ["kueski"],
        },
        {
            paymentMethod: "voucher",
            processors: ["payu_oxxo_cash"],
        },
    ],
});

• Si no se especifica una lista de métodos en paymentMethods y no se utilizó el parámetro include_payment_options al crear la orden, el widget mostrará todos los métodos de pago configurados para el comercio.

  
  JavaScript

  await DeunaSDK.initPaymentWidget({
      orderToken: "<DEUNA order token>",
      callbacks: ...,
  });
  

2.2. Tabla de Prioridades de Configuración de Métodos de Pago

La siguiente tabla muestra como el payment widget decide que formas de pago debe mostrar cuando no se pasa el parámetro paymentMethods.

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

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