Flujo de Autenticación 3D Secure (3DS) en Milio

Diagrama de Arquitectura

Arquitectura y Flujo de Procesamiento 3D Secure (3DS) en Milio

Este documento describe cómo la arquitectura de Milio procesa pagos integrando el protocolo de seguridad 3D Secure (3DS).

📘

Objetivo del Flujo

Añadir una capa extra de validación de identidad (como un código SMS u OTP, o biometría) de forma dinámica, solicitándola al cliente únicamente cuando las reglas de negocio detectan un riesgo potencial. Si no se cumple ninguna regla de riesgo, la transacción se procesa directamente por el flujo normal de cobro sin interrumpir al usuario.

---

Explicación del Flujo Paso a Paso

1. Inicio de Transacción

El flujo comienza cuando el cliente ingresa los datos de su tarjeta en el Frontend (Milio SDK / App). Estos datos sensibles (cumpliendo con la normativa PCI) se empaquetan junto con los detalles del pago y se envían de forma segura al Backend de Milio.

2. Motor de Evaluación de Reglas

Antes de procesar el cobro, el Backend evalúa la transacción a través de un Motor de Evaluación de Reglas interno. Las reglas disponibles que evalúa el sistema son:

Nombre	Descripción
Validación por Monto Mínimo	Aplica 3DS solo si la transacción supera un monto definido en los parámetros.
Validación en Enrolamiento	Aplica 3DS obligatoriamente cuando se registra o tokeniza una tarjeta nueva.
Siempre Activo	Fuerza la validación 3DS para todas las transacciones de esta compañía, sin condiciones.
Tarjeta por Primera Vez	Aplica 3DS cuando una tarjeta se ingresa por primera vez (no tokenizada) en una transacción.
Primera transacción	Primera transacción del tercero requiere 3DS.
Múltiples transacciones al receptor	Múltiples transacciones al mismo receptor requieren 3DS.
BIN internacional	BIN internacional requiere 3DS.
Monto alto	Monto alto, requiere autenticación reforzada.
Score de riesgo	Score de riesgo requiere 3DS.

Decisiones del Motor:

• Si la transacción cumple con al menos una de estas reglas de riesgo, el motor decide que se requiere 3DS y desvía la transacción al flujo de autenticación (Paso 3).
• Si el motor no decide activar 3DS o no aplica ninguna regla de riesgo, el sistema omite el proceso de verificación 3DS e inicia de inmediato el flujo normal de procesamiento de pago enviando la solicitud directamente al Adquirente / Pasarela.

---

Flujo A: Cuando se requiere 3DS (Evaluación de Riesgo Positiva)

3. Solicitud de Autenticación al Banco

El Backend se comunica vía API con nuestro Proveedor 3DS, enviándole los datos de la tarjeta y la información del dispositivo del usuario. El proveedor actúa como un puente seguro y transmite esta solicitud al Banco Emisor (ACS) a través de las redes de tarjeta (Visa, Mastercard, etc.).

4. Lanzamiento del "Challenge" (Reto de Seguridad)

El Banco Emisor recibe la solicitud, evalúa el riesgo y determina que se requiere un Challenge:

1. El Backend de Milio recibe la instrucción para lanzar el SDK de 3DS en la aplicación móvil o web.
2. La app de Milio muestra una interfaz segura/SDK especial controlada por el banco.
3. El usuario interactúa con la pantalla para completar el reto (ingresando un código OTP recibido por SMS o aprobando con biometría/huella digital desde su app bancaria).

5. Resultado, Confirmación y Procesamiento Final

1. Una vez completada la interacción, el banco notifica la autenticación al Proveedor 3DS, el cual envía un Webhook o Callback con el token de autenticación 3DS al Backend de Milio.
2. El Backend de Milio envía la transacción final adjuntando el token 3DS a la Pasarela / Adquirente para su autorización.
3. Tras la aprobación, se confirma el resultado al Frontend y la app muestra la pantalla de éxito al cliente.

---

Flujo B: Cuando NO se requiere 3DS (Flujo Normal Directo)

Si en el Paso 2 el motor determina que no aplica ninguna regla de riesgo:

1. El Backend de Milio no invoca al Proveedor 3DS ni despliega el SDK.
2. Envía directamente la transacción al Adquirente / Pasarela para la autorización habitual de cobro.
3. La pasarela procesa el pago y el Backend de Milio confirma directamente al Frontend (Cliente) que la transacción fue aprobada.

---

Validación del Resultado 3DS en la API

Una vez que la transacción finaliza, todos los datos y la evidencia del proceso 3D Secure (o la indicación de que fue procesada sin 3DS) quedan registrados en el objeto de la transacción. Puedes consultar esta información para auditar el pago o revisar cuál regla disparó el Challenge.

Para ver estos datos, consulta el endpoint de detalle de transacción de la API.

🔗

Referencia de la API

Consultar Detalle de Transacción

Dentro de la respuesta de este endpoint, encontrarás el objeto threeDS con la siguiente estructura:

JSON

{"threeDS": {
      "status": "SUCCESS",
      "context": "TRANSACTION",
      "providerSessionId": "tds_visa_2f0c97db5e7a",
      "eci": "05",
      "xid": null,
      "hasAuthenticationValue": true,
      "cryptogram": "AZ5H-uDF795G9UVb9lASJ6fniGE=",
      "eciDescriptor": "fully-authenticated",
      "liabilityShift": true,
      "authenticationFlow": "challenge",
      "authenticationMethods": [
        "sms-otp"
      ],
      "failureReason": null,
      "acsTransactionId": "1ec7b59e-0cbc-4c5c-a228-4000cb8db31a",
      "dsTransactionId": "5670d683-3acc-446e-a11e-48906adfebc8",
      "threeDSServerTransactionId": "a77a34a9-5cad-4ee5-a13e-70000875b1f1",
      "network": "visa",
      "aresTransStatus": "C",
      "cresTransStatus": "Y",
      "rreqTransStatus": null,
      "amount": "36425.00",
      "currency": "COP",
      "rule": {
    	"rule": {
        "strategyCode": "MT145",
        "strategyName": "Monto alto (monitoreo)"
    }
      },
      "createdAt": "2026-10-07T15:04:35.204Z",
      "updatedAt": "2026-10-07T15:04:48.769Z"
   }