Transacciones con 3DSecure

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.

Flujo de trabajo

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

Inicio de la transacción: El cliente selecciona los productos o servicios y procede al proceso de pago en tu plataforma.
Redirección a la página de autenticación: Después de ingresar los detalles de la tarjeta, el cliente será redirigido automáticamente a la página de autenticación del emisor de la tarjeta.
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.
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.
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.
Confirmación de la transacción: Una vez que la transacción ha sido procesada y autorizada con éxito, se mostrará una confirmación al cliente indicando que la transacción se ha completado.

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.
URLs de los ambientes de ejecución (Sandbox).

Flujo de las transacciones con 3DSecure

Paso 1. Obtener un token de aceptacion prefirmado.

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

Paso 3. Crear la transacción:

Para crear una transacción debemos hacer una peticion POST /transactions, con el siguiente cuerpo JSON:

{
  "acceptance_token": "acceptance_token", // Generado en el 1 paso
  "amount_in_cents": 100,
  "currency": "USD",
  "customer_email": "pepito_perez@example.com",
  "reference": "AHJDFDSFK184", // Valor unico para identificar la transaccion
  "payment_method": {
    "type": "CARD",
    "token": "token" // Generado en el 2 paso
  }
}

Nota: Para utilizar servidores de authenticación externos, Wompi recibe los datos de authorización en el campo three_ds_auth_external_provider como se muestra a continuación:

{
  "acceptance_token": "acceptance_token", // Generado en el 1 paso
  "amount_in_cents": 100,
  "currency": "USD",
  "customer_email": "pepito_perez@example.com",
  "reference": "AHJDFDSFK184", // Valor unico para identificar la transaccion
  "payment_method": {
    "type": "CARD",
    "token": "token", // Generado en el 2 paso
    "extra_three_ds_aut_external_provider": {
      "message_version": "{{VERSION}}",
      "trans_status": "{{VALID_VALUE_STATUS}}",
      "authentication_value": "{{AUTH_VALUE}}",
      "three_ds_server_trans_id": "{{SERVER_DIRECTORY_ID}}"
    }
  }
}

Importante, para poder usar servidores de autorización de terceros, se debera solicitar autorización previa

Obtendremos de vuelta el siguiente JSON:

{
  "data": {
    "id": "1196-1688604884-42949",
    "created_at": "2023-07-06T00:54:50.207Z",
    "finalized_at": null,
    "amount_in_cents": 100,
    "reference": "AHJDFDSFK184",
    "customer_email": "pepito_perez@example.com",
    "currency": "USD",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "bin": "497011",
        "name": "VISA-1029",
        "brand": "VISA",
        "exp_year": "29",
        "exp_month": "06",
        "last_four": "1029",
        "card_holder": "Pedro Pérez",
        "is_three_ds": false
      },
      "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:

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

Creamos la transacción y realizamos consultas periódicas (long polling) para verificar el estado de la transacción.
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.

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.

Dependiendo del escenario de autenticación, procederemos a renderizar el IFRAME del desafío o CHALLENGE
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.

Logo de 3D Secure de Mastercard

Esperamos el estado final de la transacción para mostrar el resultado al pagador.
Finalizamos el proceso mostrando el resultado de la transacción al pagador.

Paso 5. Renderizar el `IFRAME` para continuar con el proceso de autenticación:

Observaremos que en la transacción, la clave payment_method contiene información adicional relevante. Específicamente, nos centraremos en la clave three_ds_method_data, que incluye un fragmento de código HTML. Este es un bloque IFRAME que debe ser integrado y mostrado en la página para llevar a cabo de manera segura el proceso de autenticación de la tarjeta. Este campo contiene HTML escapado (con entidades HTML como < en lugar de <), por lo que necesitas decodificarlo antes de renderizarlo. Además, también encontraremos la clave current_step, que indica el estado actual de la autenticación y puede hacer referencia al tipo específico de autenticación necesario para verificar la identidad del titular de la tarjeta.

¿Qué significa "decodificar" el contenido?

El contenido viene en formato escapado (con entidades HTML) para ser transmitido de forma segura. Estas son las entidades más comunes que encontrarás:

< → <
> → >
" → "
& → &

Nota

No necesitas reemplazar cada entidad manualmente. Los ejemplos de código que se muestran a continuación decodifican todo el contenido de una sola vez, convirtiendo automáticamente todas las entidades HTML a sus caracteres correspondientes.

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>"

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

A continuación, se muestra cómo aparecen estos elementos en la respuesta de la transacción:

{
  "data": {
    "id": "1196-1688604884-42949",
    "created_at": "2023-07-06T00:54:50.207Z",
    "amount_in_cents": 100,
    "reference": "JSAGDF7329",
    "currency": "USD",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "name": "VISA-0031",
        "brand": "VISA",
        "last_four": "0031",
        "three_ds_auth": {
          "current_step": "BROWSER_INFO", // Hace referencia al tipo de autenticación: (BROWSER_INFO - CHALLENGE)
          "current_step_status": "PENDING",
          "three_ds_method_data": "<iframe>...</iframe><form>...</form>" // HTML que debe ser renderizado para autenticar la tarjeta
        }
      },
      "installments": 1
    },
    "redirect_url": null,
    "status": "PENDING",
    "status_message": null,
    "merchant": {
      "name": "Pruebas SandBox",
      "legal_name": "Pruebas SandBox",
      "contact_name": "Pepito Perez",
      "phone_number": "+50732345634",
      "logo_url": null,
      "legal_id_type": "RUC",
      "email": "pepito@prueba.com",
      "legal_id": "2452345-5"
    },
    "taxes": []
  }
}

Paso 6. No te olvides de realizar consultas periódicas de la transacción, hasta que esta alcance un estado final.

Así luce una transacción aprobada:

{
  "data": {
    "id": "1196-1687956860-36807",
    "created_at": "2023-06-28T12:54:23.740Z",
    "amount_in_cents": 100,
    "reference": "devtest_VPOS_jTYzjz_1687956812524_6y6kix6d52b",
    "currency": "USD",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "name": "VISA-0031",
        "brand": "VISA",
        "last_four": "0031",
        "is_three_ds": true,
        "three_ds_auth": {
          "three_ds_auth": {
            "current_step": "AUTHENTICATION",
            "current_step_status": "COMPLETED"
          }
        },
        "external_identifier": "aaydSncOcB",
        "processor_response_code": "00"
      },
      "installments": 1
    },
    "redirect_url": null,
    "status": "APPROVED",
    "status_message": null,
    "merchant": {
      "name": "Pruebas SandBox",
      "legal_name": "Pruebas SandBox",
      "contact_name": "Pepito Perez",
      "phone_number": "+50732345634",
      "logo_url": null,
      "legal_id_type": "RUC",
      "email": "prueba@test.com",
      "legal_id": "2452345-5"
    },
    "taxes": []
  }
}

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.

Introducción​

Flujo de trabajo​

Implementación de 3D Secure en tu plataforma​

Requisitos previos​

Paso 1. Obtener un token de aceptacion prefirmado.​

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

Paso 3. Crear la transacción:​

Importante, para poder usar servidores de autorización de terceros, se debera solicitar autorización previa​

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

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

Paso 5. Renderizar el IFRAME para continuar con el proceso de autenticación:​

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

Paso 6. No te olvides de realizar consultas periódicas de la transacción, hasta que esta alcance un estado final.​

Implementación completa con React​

Introducción

Flujo de trabajo

Implementación de 3D Secure en tu plataforma

Requisitos previos

Paso 1. Obtener un token de aceptacion prefirmado.

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

Paso 3. Crear la transacción:

Importante, para poder usar servidores de autorización de terceros, se debera solicitar autorización previa

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

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

Paso 5. Renderizar el `IFRAME` para continuar con el proceso de autenticación:

Ejemplos de código para decodificar el HTML del iframe

Paso 6. No te olvides de realizar consultas periódicas de la transacción, hasta que esta alcance un estado final.

Implementación completa con React