Developer tools

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.

Inicializa el Widget

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

1. Muestra el Widget

Para mostrar el Payment Widget:

  1. Llama a la función initPaymentWidget
  2. Pasa los siguientes datos:
await DeunaSDK.initPaymentWidget({
  orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
  userToken: ..., // opcional
  styleFile: ..., // opcional
  language: ..., // opcional
  hidePayButton: ..., // 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

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: 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.
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
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.
behavior (Opcional)Utiliza este parámetro para configurar el comportamiento del widget.
hidePayButton(Opcional)Al establecer hidePayButton: true, el botón de pago predeterminado del widget se ocultará, transfiriendo el control completo del flujo de pago al integrador.

2. Muestra u oculta métodos de pago

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

Muestra u oculta métodos de pago:

  1. Invoca la función initaymentWidget
  2. El parámetro paymentMethods define los métodos de pago que el widget mostrará:
    • Si se pasa un método en paymentMethods, el Eidget abre automáticamente el formulario del método de pago sin mostrar botones de otros métodos de pago.
    • Si se especifica más de un método de pago en el parámetro paymentMethods, el widget mostrará los métodos habilitados los cuales deben estar configurados en tu tienda.
    • 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.
// 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"],
        },
    ],
});





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





📘

No se necesita pasar el array de procesador para procesar tarjetas de crédito. Puedes tener múltiples procesadores configurados para el uso de routing.

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


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:

PrioridadFuente de ConfiguraciónDescripciónComportamiento en caso de un solo método de pago
1Métodos de pago pasados al ejecutar la función .initPaymentWidgetLos 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.
2Orden e include_payment_optionsSe 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.
3Mé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.

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

Callbacks

Callback¿Cuándo se dispara?
onSuccessSe ejecuta cuando se completó el pago. Este callback contiene un parámetro de tipo JSON con la información de la orden.
onErrorSe 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.
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.
onResize (Opcional)Este callback te permite "escuchar" los cambios en la altura del contenido del widget de DEUNA

Ajusta la altura del contenedor de tu widget embebido

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

4. Cerrar el Widget

Por defecto, el widget de pago 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, llama 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);
    },
  },
});

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

6. Refrescar el widget de pago

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

const order = await DeunaSDK.refetchOrder();

Caso de uso

La función refetchOrder es útil para ofrecer promociones.

Un caso de uso es: Promoción del 20% al pagar con Mastercard.

En este escenario:

  1. Tu comercio escucha el evento onCardBinDetected para identificar la franquicia de la tarjeta.
  2. Tu comercio actualiza la orden en DEUNA (siendo el responsable de calcular las promociones).
  3. A través de la función refetchOrder, tu comercio notifica al widget para que se actualice.
  4. El monto de la orden se refresca y cambia.

Ejemplo

await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
    callbacks: {
        onCardBinDetected: async (cardBinMetadata) => {
            if (cardBinMetadata.cardBrand === "mastercard") {
                // Aquí el comercio debe hacer sus calculos y posteriormente actualizar la orden
                // de DEUNA por API usando: https://docs.deuna.com/reference/order_token
                const order = await DeunaSDK.refetchOrder();
                if (order) {
                    console.log("ORDER", order);
                }
            }
        },
    },
});