Integración: Payment Widget

Introducción

El Payment Widget es una herramienta diseñada para facilitar a los comercios la integración de múltiples métodos de pago de manera rápida y sencilla. Este widget permite aceptar pagos tanto a través de Métodos de Pago Alternativos (APMs) como con tarjetas de crédito y débito, brindando a los usuarios mayor flexibilidad en sus transacciones.

El Payment Widget soporta:

Métodos de Pago Alternativos (APMs): OXXO, KueskiPay, y más.
Tarjetas de Crédito y Débito: Visa, MasterCard, American Express, entre otras.

📘

El Payment Widget es "white-labelled" es decir que el look-and-feel es completamente personalizable.

Pros de la integración Widget

• Le permite a los comercios activar en un solo click al usuario nuevos métodos de pago sin cambios en la integración. Con solo activar el método de pago en el admin (portal de comercio) de DEUNA, en tiempo real aparecería disponible para el usuario final dentro del widget de pagos.
• El widget en sí se encarga de permitirle al usuario guardar sus tarjetas y administrarlas. Esta función es opcional y personalizable por parte del comercio.
• El widget se encarga de soportar y controlar el flujo de 3DS de forma nativa.
• No requiere re-dirección a otra pestaña/página web (si es requerido por el comercio, se puede conservar la re-dirección)
• Se puede personalizar con los colores, logo y estilos que se ajusten a los del comercio. Consulta nuestra sección de personalización aquí.

Casos de uso

El Payment Widget permite a los comercios configurar y personalizar la forma en que los métodos de pago se presentan a los clientes, de acuerdo con sus necesidades. A continuación, se detallan los diferentes casos de uso:

• Pagos con tarjetas de crédito y débito

  Permite a los clientes pagar utilizando tarjetas de crédito o débito, compatibles con redes como Visa, MasterCard, American Express, entre otras.

  

• Pagos con tarjetas de crédito / débito y métodos de pago alternativos (APMs)

  Muestra tanto las tarjetas de crédito y débito como los métodos de pago alternativos (APMs) en una única interfaz, permitiendo que los usuarios elijan el método de pago de su preferencia.

• Mostrar directamente un método de pago alternativo

  Ofrece directamente un método de pago alternativo específico, ideal para casos donde el comercio desea promocionar un APM en particular.

  

• Web embebido directamente en el sitio web del comercio

  Integra el widget directamente en la página web del comercio, brindando una experiencia de pago fluida y sin redirecciones.

  
  

Ambientes

https://docs.deuna.com/reference/environments

Métodos de integración

Uso de SDKs (recomendado): 

Recomendamos integrar el Payment Widget mediante nuestros SDKs, ya que ofrecen una experiencia más optimizada y simplifican la comunicación entre las aplicaciones y las páginas web. A continuación, se listan los SDKs disponibles:

• SDK para Web 
• SDK nativo para iOS: Swift (iOS)
• SDK nativo para Android: Kotlin (Android)

Consideraciones:

• Web: En entornos web, el widget puede abrirse en un elemento HTML objetivo o mostrarse como un modal.
• Mobile: En aplicaciones móviles (iOS y Android), el widget se abre dentro de un WebView.

Funcionalidades clave:

El SDK expone varios callbacks que permiten al comercio reaccionar de forma dinámica ante eventos importantes dentro del flujo de pago, como:

• Cuando el usuario cierra el widget.
• Cuando se completa exitosamente el pago.
• Cuando falla un intento de pago.

Estas funcionalidades permiten al comercio personalizar la experiencia del usuario y adaptarla según las necesidades de cada transacción.

Además, el comercio puede monitorear las actualizaciones de estado de los pagos mediante nuestros webhooks, lo que facilita la automatización de procesos y la actualización en tiempo real.

Uso de URL (no recomendado): 

En el caso el comercio por alguna razón no pueda usar los SDKs (i.e. cuestiones de seguridad, compliance, etc;) la alternativa es que el comercio logre renderizar el widget dentro de un iFrame o en un tab completo como redirect. Para esto, el comercio debe seguir los siguientes pasos:

1. El comercio debe crear una orden con DEUNA: https://docs.deuna.com/reference/create-order

2. El comercio puede renderizar el widget:

   1. Sandbox: https://pay.sandbox.deuna.io/now/{{order_token}}
   2. Production: https://pay.deuna.io/now/{{order_token}}

3. Para escuchar los eventos del widget, el comercio debe hacer lo siguiente:

   1. Se debe usar la siguiente librería: https://github.com/krakenjs/zoid. Esta se usa para una mejor administración y seguridad de la comunicación vía postMessages.

   2. El comercio puede el siguiente snippet de ejemplo:

      1. HTML

         <!DOCTYPE html>
         <html lang="en">
           <head>
             <meta charset="UTF-8" />
             <meta name="viewport" content="width=device-width, initial-scale=1.0" />
             <title>Document</title>
             <script src="zoid.js"></script>
             <style>
               body {
                 text-align: center;
               }
             </style>
           </head>
           <body>
             <div id="payment-widget" style="margin: auto"></div>
         
             <script>
               function buildPaymentLink(orderToken, env) {
                 var baseUrl = "https://pay.deuna.com";
         
                 switch (env) {
                   case "production":
                     baseUrl = "https://pay.deuna.com";
                     break;
                   case "sandbox":
                     baseUrl = "https://pay.sandbox.deuna.com";
                     break;
                 }
         
                 return baseUrl + "/now/" + orderToken;
               }
         
               const PaymentWidgetComponent = zoid.create({
                 tag: "d-una-checkout",
                 url: buildPaymentLink(
                   "e7bdb89c-b277-44f6-8df4-b0bea4ad6aca",
                   "sandbox"
                 ),
                 dimensions: {
                   width: "450px",
                   height: "100dvh",
                 },
               });
         
               PaymentWidgetComponent({
                 timeout: 7000,
                 onRendered: () => {},
                 onEventDispatch: (event) => {
                   const type = event.type;
                   const data = event.data;
         
                   const mapper = {
                     purchaseError: () => {
                       console.log("purchase failed");
                     },
                     purchase: () => {
                       console.log("purchase successful");
                     },
                     onBinDetected: () => {
                       if (data.metadata) {
                         console.log("cardBin", data.metadata.cardBin);
                       }
                     },
                     onInstallmentSelected: () => {
                       if (data.metadata) {
                         console.log("onInstallment", data.metadata);
                       }
                     },
                   };
         
                   mapper[type]?.(); // Call the handler based on event type
                 },
               })
                 .render("#payment-widget")
                 .catch((error) => {});
             </script>
           </body>
         </html>
         

         
         

Diagrama de integración

Información adicional para la implementación de algunos APMs

Los proveedores de métodos de pago alternativos (APMs) han definido requisitos específicos para obtener una implementación certificada. A continuación, proporcionamos los datos esenciales que deben reflejarse en tu comprobante de pago al utilizar uno de estos APMs:

Datos adicionales para hacer las pruebas

Daviplata