Saltar al contenido principal
  • Colombia
  • Español

    • Transacciones con 3D Secure (Sandbox) v2

    Introducción​

    En esta guía, aprenderás cómo realizar una transacción utilizando el protocolo 3D Secure. 3D Secure es un sistema de autenticación que agrega una capa adicional de seguridad a las transacciones en línea. A través de este protocolo, los emisores de tarjetas y los adquirentes pueden autenticar al titular de la tarjeta antes de procesar la transacción.

    Ayudarte con la protección de tu negocio y tu dinero es una de nuestras prioridades, para esto queremos entregarte unas recomendaciones de seguridad aquí.

    Importante!

    Si tu comercio realiza autenticaciones de 3DS a través de un proveedor externo o diferente a Wompi entonces puedes hacer uso de la siguiente guía para integrar 3DS con Wompi

    ¿Cómo funciona el protocolo de 3DS?​

    El proceso de una transacción con 3D Secure con Wompi generalmente sigue los siguientes pasos:

    1. Inicio de la transacción: Tu cliente selecciona los productos o servicios y procede al proceso de pago en tu plataforma.
    2. Redirección a la página de autenticación: Después de ingresar los detalles de la tarjeta, tu cliente será redirigido automáticamente a la página de autenticación del emisor de la tarjeta.
    3. Autenticación del titular de la tarjeta: El emisor de la tarjeta solicitará al titular de la tarjeta que ingrese una contraseña o un código de verificación único. Esto puede ser una contraseña, un código OTP (One-Time Password) o una huella digital, dependiendo del método de autenticación implementado.
    4. Autorización de la transacción: Una vez que el titular de la tarjeta haya sido autenticado correctamente, el emisor de la tarjeta generará un mensaje de autenticación exitosa y lo enviará al adquirente.
    5. Procesamiento de la transacción: El adquirente recibe el mensaje de autenticación exitosa y procede a autorizar la transacción. Se verifica si hay suficientes fondos en la cuenta del titular de la tarjeta y si la transacción cumple con los límites de la tarjeta y las reglas de fraude.
    6. Confirmación de la transacción: Una vez que la transacción ha sido procesada y autorizada con éxito, se mostrará una confirmación a tu cliente indicando que la transacción se ha completado.
    info
    • El protocolo de 3DS está disponible para las transacciones con las franquicias Mastercard y Visa.
    • Dependiendo el modelo (Gateway o Agregador) de tu comercio la disponibilidad del protocolo 3DS por franquicia puede variar, te recomendamos comunicarte con nuestros canales de atención para resolver tus dudas.

    Generalidad de 3D Secure para tu comercio aquí y para tu cliente aquí.

    Flujo de autenticación con 3DSecure

    Diagrama de Flujo de Integración Frontend​

    A continuación, te presentamos un diagrama detallado del flujo de integración de 3D Secure en tu frontend, que ilustra todos los pasos críticos desde la recolección de datos del navegador hasta el resultado final de la transacción:

    Diagrama de flujo 3DS Frontend
    Diagrama de flujo completo de integración 3D Secure en el frontend
    Puntos Clave del Flujo
    • Long Polling: Realizar consultas periódicas cada 2-3 segundos para verificar el estado de la transacción
    • Logo Mastercard: Mostrar obligatoriamente cuando se recibe three_ds_auth en la respuesta y cuando current_step es AUTHENTICATION
    • Decodificación del iframe: Convertir entidades HTML (&lt; → <) antes de renderizar el iframe del challenge
    • Estados críticos: CHALLENGE y AUTHENTICATION requieren manejo especial - CHALLENGE requiere renderizar el iframe y AUTHENTICATION indica que el proceso finalizó

    ¿Cómo puedo usar 3D Secure si mi comercio está integrado vía API?​

    A continuación, te indicamos el proceso para la implementación de 3D Secure en tu plataforma.

    Sección #1 - Implementación de 3D Secure en tu plataforma​

    Requisitos previos​

    Antes de comenzar con la implementación, asegúrate de contar con los siguientes requisitos:

    • Llaves de autenticación: En esta seccion haremos uso solo de la llave publica, la cual enviaremos Bearer token en los headers de las peticiones.
    • Datos de prueba: Para mayor facilidad, recomendamos usar la tarjeta 4242 4242 4242 4242, ya que admite múltiples tipos de autenticación 3DS y responde de forma flexible en pruebas vía API. Esto ayuda a evitar errores comunes que pueden surgir cuando se combinan tarjetas con escenarios incompatibles (por ejemplo, enviar un challenge con una tarjeta que no lo requiere). Puedes usar otras tarjetas listadas en la sección de checkout, pero asegúrate de que el tipo de autenticación sea coherente con el comportamiento esperado de cada tarjeta.
      • Nota: Esta tarjeta la puedes usar en el checkout posteriormente a implementar 3DS en tus transacciones.
    • URLs de los ambientes de ejecución (Sandbox).

    Paso 1. Obtener un token de aceptacion prefirmado.​

    Paso 2. Tokenizamos el medio de pago (Tarjeta).​

    Paso 3. Crear la transacción:​

    Para activar el flujo de 3DSecure, se debe enviar el campo is_three_ds en true y el campo three_ds_auth_type con alguno de los siguientes valores:

    1. no_challenge_success: Indica que se llevará a cabo la autenticación con 3D Secure, pero no será necesario renderizar ningún elemento para el usuario final y la autenticación será existosa. En este caso, la transacción se marcará automáticamente como APROBADA.
    2. challenge_denied: Indica que se llevará a cabo la autenticación con 3D Secure, pero no será necesario renderizar ningún elemento para el usuario final y la autenticación será declinada. En este caso, la transacción se marcará como DECLINADA.
    3. challenge_v2: Indica que se llevará a cabo la autenticación con 3D Secure y será necesario renderizar un IFRAME para que el usuario final complete el desafío de autenticación. En este caso, la transacción se marcará como PENDING hasta que el usuario final complete el desafío o exceda el tiempo límite.
    4. supported_version_error: Indica que la tarjeta no es compatible con el protocolo 3D Secure. En este caso, la transacción se marcará como ERROR.
    5. authentication_error: Indica que hubo un error al intentar autenticar la tarjeta. En este caso, la transacción se marcará como ERROR.

    Adicionalmente, se debe enviar el campo browser_info dentro del campo customer_data con la siguiente información del navegador del usuario pagador:

    1. browser_color_depth: Profundidad de color del navegador.
    2. browser_screen_height: Altura de la pantalla del navegador.
    3. browser_screen_width: Ancho de la pantalla del navegador.
    4. browser_language: Idioma del navegador.
    5. browser_user_agent: Agente de usuario del navegador.
    6. browser_tz: Zona horaria del navegador.

    Para obtener esta información, puedes usar el siguiente código JavaScript:

    {
       browser_color_depth: window.screen.colorDepth.toString(), // "24"
       browser_screen_height: window.screen.height.toString(), // "1050"
       browser_screen_width: window.screen.width.toString(), // "1680"
       browser_language: window.navigator.language.toString(), // "en-US"
       browser_user_agent: window.navigator.userAgent.toString(), // "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N)...."
       browser_tz: new Date().getTimezoneOffset().toString() // "300"
    }
    Importante!

    Recuerda que, para que 3DS funcione de manera adecuada, debes enviar la información del navegador. Si no se incluye, se generarán errores debido a la ausencia de estos datos.

    Considerando lo anterior, para crear la transacción será necesario realizar una solicitud POST /transactions con el siguiente cuerpo JSON:

    {
      "acceptance_token": "acceptance_token", // Generado en el 1 paso
      "amount_in_cents": 1000000,
      "currency": "COP",
      "customer_email": "pepito_perez@example.com",
      "reference": "AHJDFDSFK184", // Valor unico para identificar la transaccion
      "signature": "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5",
      "payment_method": {
        "type": "CARD",
        "token": "token_val_12345...", // Generado en el 2 paso
        "installments": 1 // Numero de cuotas
      },
      //Campos necesarios para 3DSecure
      "is_three_ds": true,
      "three_ds_auth_type": "no_challenge_success", // no_challenge_success
      "customer_data": {
        "full_name": "Pepito Perez",
        "phone_number": "3109876543",
        // otra información del cliente pagador...
        "browser_info": {
          "browser_color_depth": "24",
          "browser_screen_height": "1050",
          "browser_screen_width": "1680",
          "browser_language": "en-US",
          "browser_user_agent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N)...",
          "browser_tz": "-300"
        }
      }
    }
    Importante!
    • Los campos three_ds_auth_type, is_three_ds y browser_info son obligatorios para activar el flujo de 3D Secure, si no se envía, la transacción se procesará sin este proceso de autenticación.
    • El campo three_ds_auth_type solo se debe mandar para transacciones que se crean en el ambiente de pruebas (sandbox). En producción este campo NO se debería enviar en el cuerpo JSON de las transacciones, sin embargo, los campos is_three_ds y browser_info SI deben enviarse tanto en producción como en pruebas.

    Después de haber hecho la petición POST, obtendremos de vuelta un JSON parecido al siguiente:

    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "finalized_at": null,
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "customer_email": "pepito_perez@example.com",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "bin": "400000",
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "exp_year": "29",
            "exp_month": "06",
            "last_four": "0002",
            "card_holder": "Pedro Pérez",
            "is_three_ds": true,
            "three_ds_auth_type": "no_challenge_success" // El tipo de autenticación que se ha solicitado
          },
          "installments": 1
        },
        "status": "PENDING",
        "status_message": null,
        "billing_data": null,
        "shipping_address": null,
        "redirect_url": null,
        "payment_source_id": null,
        "payment_link_id": null,
        "customer_data": null,
        "bill_id": null,
        "taxes": []
      }
    }

    Paso 4. Realizar consultas periódicas de la transacción para verificar el estado y asegurarnos de su correcta ejecución.​

    tip

    Estas consultas se deben realizar reiterativamente debido a que dentro de la integración puede que sea necesario renderizar el IFRAME del CHALLENGE, que es detallado en los siguientes paso.

    A continuación, te brindamos ejemplos de cómo implementar la lógica de long polling en tu plataforma:

    Cargando ejemplos...

    Ten en cuenta

    Después de recibir el objeto three_ds_auth en la respuesta de la transacción, es obligatorio mostrar el siguiente logo de Mastercard en tu plataforma para informar a los pagadores que su transacción está siendo autenticada a través de 3D Secure por políticas de Mastercard. A continuación te mostramos el flujo de como lo hacemos en Wompi para que lo tomes como referencia:

    Primero necesitarás el siguiente logo de Mastercard para los siguientes pasos. Para descargar el logo, haz click en la siguiente imagen o abrela en una nueva pestaña:

    Mastercard ID Check Logo

    Flujo de implementación del logo de 3D Secure de Mastercard​

    1. Creamos la transacción y realizamos consultas periódicas (long polling) para verificar el estado de la transacción.
    2. Cuando recibimos el objeto three_ds_auth en la respuesta de la transacción, mostramos el logo de 3D Secure de Mastercard en nuestra plataforma para informar al pagador que su transacción está siendo autenticada a través de 3D Secure.
    modal-with-mastercard-logo
    Logo de 3D Secure de Mastercard
    Importante!

    Mostrar este logo es obligatorio por políticas de Mastercard, así que asegúrate de implementarlo correctamente en tu plataforma. No tiene que ser obligatoriamente un modal como el del ejemplo, pero debe ser visible para el pagador.

    1. Dependiendo del escenario de autenticación, procederemos a renderizar el IFRAME del desafío o CHALLENGE (este paso es OPCIONAL y depende del tipo de autenticación solicitada).
    challenge-rendered
    Challenge renderizado
    1. En caso de haber completado el desafío o que el nuevo estado de la autenticación sea AUTHENTICATION, procedemos a mostrar de nuevo el logo de 3D Secure de Mastercard para informar al pagador que su transacción ha sido autenticada a través de 3D Secure.
    modal-with-mastercard-logo
    Logo de 3D Secure de Mastercard
    1. Esperamos el estado final de la transacción para mostrar el resultado al pagador.
    2. Finalizamos el proceso mostrando el resultado de la transacción al pagador.
    info

    Teniendo claro lo anterior, la siguiente información te muestra los diferentes escenarios que pueden ocurrir dependiendo del tipo de autenticación que se haya solicitado

    Escenario 1: Autenticación EXITOSA sin requerir un CHALLENGE (no_challenge_success)​

    En este escenario, la transacción se completará exitosamente sin necesidad de un desafío adicional. La respuesta de la transacción incluirá el campo three_ds_auth con los siguientes valores:

    • current_step: AUTHENTICATION .
    • current_step_status: COMPLETED .
    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "no_challenge_success", // El tipo de autenticación que se ha solicitado
            "three_ds_auth": {
              "current_step": "AUTHENTICATION", // Indica que la autenticación se ha completado
              "current_step_status": "COMPLETED" // Indica que la autenticación fue exitosa
            }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "APPROVED", // El estado final de la transacción es APPROVED
        "status_message": null
        // Otros campos...
      }
    }

    Escenario 2: Autenticación DECLINADA sin requerir un CHALLENGE (challenge_denied)​

    En este escenario, la transacción quedará en estado DECLINADO sin necesidad de un desafío adicional. La respuesta de la transacción incluirá el campo three_ds_auth con los siguientes valores:

    • current_step: AUTHENTICATION .
    • current_step_status: Non-Authenticated .
    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "challenge_denied", // El tipo de autenticación que se ha solicitado
            "three_ds_auth": {
              "current_step": "AUTHENTICATION", // Indica que la autenticación se ha completado
              "current_step_status": "Non-Authenticated" // Indica que la autenticación fué declinada
            }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "DECLINED", // El estado final de la transacción es DECLINED
        "status_message": null
        // Otros campos...
      }
    }

    Escenario 3: Autenticación APROBADA, DECLINADA o en ERROR con CHALLENGE requerido (challenge_v2)​

    En este escenario, se requiere que el usuario final complete un desafío (CHALLENGE) para autenticar la transacción. Este CHALLENGE es un IFRAME que se renderiza en tu plataforma y contiene el desafío de autenticación emitido por el emisor de la tarjeta.

    ¿Cómo obtener y renderizar el iframe del CHALLENGE?​

    El iframe se obtiene a través del campo three_ds_method_data en la respuesta de la transacción. Este campo contiene HTML escapado (con entidades HTML como &lt; en lugar de <), por lo que necesitas decodificarlo antes de renderizarlo.

    ¿Qué significa "decodificar" el contenido?

    El contenido viene en formato escapado para ser transmitido de forma segura:

    • &lt; debe convertirse en <
    • &gt; debe convertirse en >
    • &quot; debe convertirse en "
    • &amp; debe convertirse en &

    Por ejemplo:

    // Contenido RECIBIDO (escapado):
    "&lt;iframe src='https://example.com'&gt;&lt;/iframe&gt;"

    // Contenido DECODIFICADO (listo para usar):
    "<iframe src='https://example.com'></iframe>"
    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "challenge_v2", // El tipo de autenticación que se ha solicitado
             "three_ds_auth": {
               "current_step": "CHALLENGE", // Indica que la autenticación requiere un desafío
               "current_step_status": "PENDING" // Indica que el desafío está pendiente de resolución
               "three_ds_method_data": "&lt;!DOCTYPE..." // Contiene iFrame que deberás decodificar y renderizar en tu plataforma
             }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "PENDING", // El estado de la transacción es PENDING
        "status_message": null
        // Otros campos...
      }
    }

    Ejemplos de código para decodificar el HTML del iframe​

    A continuación, te mostramos diferentes formas de decodificar el contenido HTML escapado:

    Cargando ejemplos...

    Recomendación

    El método con DOMParser es el más recomendado ya que es más seguro y está soportado en todos los navegadores modernos.

    Importante
    • NO uses el atributo src del iframe, debes usar srcDoc con el HTML decodificado
    • Asegúrate de que el iframe tenga suficiente espacio (recomendamos al menos 400-500px de alto)
    • El iframe debe ser visible y no estar oculto con CSS

    Implementación completa con React​

    Para proyectos que usan React, te proporcionamos una implementación modular y completa que maneja todo el flujo de 3DS:

    Cargando ejemplos...

    Características del componente React:

    • Long Polling automático: Consulta el estado de la transacción cada 2-3 segundos utilizando el endpoint de Wompi
    • Muestra el logo de Mastercard: Cumple con los requisitos obligatorios de políticas mostrándolo cuando se recibe three_ds_auth
    • Maneja el CHALLENGE: Renderiza el iframe cuando current_step es CHALLENGE y current_step_status es PENDING
    • Decodificación automática: Convierte el HTML escapado correctamente usando DOMParser
    • Estados visuales claros: Loading, Challenge visible, y estados finales (APPROVED, DECLINED, ERROR)
    • Limpieza de recursos: Cleanup automático de intervalos y listeners en el useEffect
    • TypeScript ready: Tipos completos para mejor desarrollo
    Nota sobre el componente

    El componente maneja automáticamente:

    • La consulta periódica (long polling) hasta obtener el estado final
    • La decodificación del HTML del iframe cuando sea necesario
    • La visualización del logo de Mastercard según las políticas requeridas
    • El renderizado del iframe del challenge cuando current_step es CHALLENGE

    Solo necesitas reemplazar YOUR_PUBLIC_KEY con tu llave pública de Wompi en la función fetchTransactionStatus.

    Una vez renderizado el IFRAME, el usuario final tendrá 3 opciones para completar el desafío: APPROVED, DECLINED o ERROR. La opción seleccionada por el usuario final determinará el estado final de la transacción.

    De la siguiente manera se verá el IFRAME renderizado en tu plataforma:

    challenge-sandbox-3ds
    Ejemplo de challenge renderizado (iFrame)

    Importante!

    El IFRAME del CHALLENGE en modo sandbox es una simulación de lo que sería el flujo real de autenticación, ten en cuenta que el emisor de la tarjeta puede solicitar diferentes tipos de autenticación y desafíos dependiendo de la configuración del emisor y del tipo de tarjeta.

    Estado final de la transacción después de completar el CHALLENGE:

    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "challenge_v2", // El tipo de autenticación que se ha solicitado
            "three_ds_auth": {
              "current_step": "AUTHENTICATION", // Indica que la autenticación requiere un desafío
              "current_step_status": "COMPLETED" // Non-Authenticated, COMPLETED o ERROR dependiendo de la opción seleccionada por el usuario final
            }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "APPROVED", // DECLINED, APPROVED o ERROR dependiendo de la opción seleccionada por el usuario final
        "status_message": null
        // Otros campos...
      }
    }

    Nota: El campo current_step_status representa el estado de la autenticación de la tarjeta, no el estado final de la transacción, ya que en ambientes bajos los procesadores NO admiten estos números de tarjeta para realizar transacciones de prueba.

    Escenario 4: Error en el paso Supported Version (supported_version_error)​

    En este escenario, la transacción quedará en estado ERROR sin necesidad de un desafío adicional. La respuesta de la transacción incluirá el campo three_ds_auth con los siguientes valores:

    • current_step: SUPPPORTED_VERSION.
    • current_step_status: ERROR.
    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "supported_version_error", // El tipo de autenticación que se ha solicitado
            "three_ds_auth": {
              "current_step": "SUPPORTED_VERSION", // Indica que la autenticación no se pudo realizar debido a que la tarjeta no es compatible con el protocolo 3D Secure
              "current_step_status": "ERROR" // Estado de la autenticación es ERROR
            }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "ERROR", // Estado final de la transacción es ERROR
        "status_message": null
        // Otros campos...
      }
    }

    Escenario 5: Error en la autenticación (authentication_error)​

    En este escenario, la transacción quedará en estado ERROR sin necesidad de un desafío adicional. La respuesta de la transacción incluirá el campo three_ds_auth con los siguientes valores:

    • current_step: AUTHENTICATION.
    • current_step_status: ERROR.
    {
      "data": {
        "id": "11854-1728506262-27959",
        "created_at": "2024-10-09T20:37:43.075Z",
        "amount_in_cents": 1000000,
        "reference": "AHJDFDSFK184",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
          "type": "CARD",
          "extra": {
            "name": "MASTERCARD-0002",
            "brand": "MASTERCARD",
            "card_type": "DEBIT",
            "last_four": "0002",
            "is_three_ds": true,
            "three_ds_auth_type": "authentication_error", // El tipo de autenticación que se ha solicitado
            "three_ds_auth": {
              "current_step": "AUTHENTICATION", // Indica que hubo un error al intentar autenticar la tarjeta (error de comunicación, error de autenticación, etc.)
              "current_step_status": "ERROR" // Estado de la autenticación es ERROR
            }
          },
          "installments": 1
        },
        "redirect_url": null,
        "status": "ERROR", // Estado final de la transacción es ERROR
        "status_message": null
        // Otros campos...
      }
    }

    Problemas Comunes y Soluciones​

    1. El iframe no se renderiza correctamente​

    Problema: El iframe aparece en blanco o no muestra el challenge.

    Soluciones:

    • Verifica que estés usando srcDoc en lugar de src en el elemento iframe
    • Asegúrate de haber decodificado el HTML correctamente (convertir &lt; a <)
    • Revisa que el contenido de three_ds_method_data no esté vacío
    • Comprueba que el iframe tenga dimensiones adecuadas (mínimo 400px de alto)
    // ❌ INCORRECTO
    iframe.src = escapedHtml;

    //  CORRECTO
    iframe.srcDoc = decodeIframeHtml(escapedHtml);

    2. No se recibe el objeto three_ds_auth​

    Problema: La transacción no devuelve información de 3DS en las consultas.

    Soluciones:

    • Confirma que enviaste is_three_ds: true al crear la transacción
    • Verifica que incluiste el objeto browser_info con todos los campos requeridos
    • Asegúrate de estar consultando la transacción correcta usando el ID devuelto
    • Espera al menos 1-2 segundos antes de la primera consulta (procesamiento asíncrono)

    3. Long polling infinito o no se detiene​

    Problema: Las consultas continúan indefinidamente sin llegar a un estado final.

    Soluciones:

    • Implementa un timeout máximo (recomendado: 5 minutos)
    • Detén el polling cuando el estado sea diferente de PENDING
    • Limpia los intervalos en el cleanup del useEffect (React) o al desmontar componentes
    • Maneja errores de red con reintentos limitados
    // Ejemplo con timeout
    const MAX_ATTEMPTS = 150; // 5 minutos con intervalos de 2s
    let attempts = 0;

    const intervalId = setInterval(() => {
      if (attempts >= MAX_ATTEMPTS) {
        clearInterval(intervalId);
        onError(new Error("Timeout: La transacción tardó demasiado"));
        return;
      }

      pollTransaction();
      attempts++;
    }, 2000);

    Performance y UX​

    1. Optimiza el polling

      • Usa intervalos de 2-3 segundos (no menos de 1 segundo)
      • Implementa exponential backoff si hay errores
      • Detén inmediatamente al recibir estado final

    2. Feedback visual

      • Muestra spinners durante el procesamiento
      • Indica claramente cuando se está autenticando
      • Proporciona mensajes de error descriptivos al usuario

    3. Responsive design

      • El challenge debe ser completamente visible en mobile
      • Ajusta las dimensiones del iframe según el dispositivo
      • Asegura que el logo de Mastercard sea legible en todas las pantallas

    Testing​

    1. Prueba todos los escenarios

      • Challenge aprobado
      • Challenge rechazado
      • Autenticación frictionless exitosa
      • Errores de autenticación
      • Errores de versión no soportada
      • Timeouts y errores de red

    2. Testing en diferentes navegadores

      • Chrome, Firefox, Safari, Edge
      • Versiones mobile (iOS Safari, Chrome Mobile)
      • Modo privado/incógnito

    Sección #2 - 3D Secure a través de tu checkout (Sandbox)​

    A través de tu checkout en modo sandbox (o pruebas) podrás experimentar escenarios simulados de autenticación 3D Secure. Para ello, deberás seguir los siguientes pasos:

    Nota: Las tarjetas proporcionadas en esta sección son exclusivamente para pruebas a través del CHECKOUT, para realizar pruebas a través de la API, debes seguir el proceso de implementación detallado anteriormente.

    Paso 1. Ingresar a tu dashboard como comercio​

    Paso 2. Ingresa a la barra lateral izquierda y selecciona la opción "Desarrollo".​

    Paso 3. Selecciona la opción "Programadores".​

    Paso 4. Dirigite a la parte superior derecha y localiza la sección "Modo de pruebas" y da click en el botón "Activar modo de pruebas".​

    Nota: Una vez seleccionada esta opción, debería aparecer un mensaje en rojo en la parte superior indicando que se encuentra en modo Sandbox. Recuerde regresar a esta sección para restablecer el modo productivo una vez finalizadas las pruebas.

    Checkout en modo Sandbox

    Paso 8. Completa los campos solicitados y selecciona el método de pago "Tarjeta de crédito o débito".​

    Paso 9. Completa el campo de número de tarjeta con alguna de las siguientes tarjetas:​

    • Para requerir challenge: 2303779951000446, requiere autenticación 3D Secure.
    • Para una autenticación "frictionless": 2303779951000297, se autenticará la tarjeta existosamente pero no requiere challenge.
    • Para una autenticación denegada: 2303779951000453, la autenticación será denegada.
    • Para una autenticación con error: 2303779951000354, la autenticación terminará en estado error.
    • Para simular error en el protocolo: 2303779951000347, indica que la tarjeta no es soportada por el protocolo.

    Paso 10. Completa la fecha de expiración y el CVC con datos genéricos (Ej: 03/27 y 123).​

    Paso 11. Si la tarjeta requiere autenticación 3D Secure, se te solicitará seleccionar una de las siguientes opciones:​

    Nota: Si seleccionas la opción Approved entonces la transacción se aprobará, si seleccionas Declined la transacción será rechazada y si seleccionas Error entonces la transacción quedará en estado error.

    Install

    Paso 12. Una vez seleccionada la opción, se mostrará un mensaje con el resultado de la transacción según la opción que hayas elegido​

    Nota: Ten en cuenta que para transacciones REALES la solicitud o no del "challenge" o desafío en el proceso de compra la toma el emisor.

    Inicio rápido.Widget & Checkout Web

    Copyright © 2023 Wompi