Autenticación 3D Secure

Integra 3D Secure en tu flujo de pago para reducir el fraude y cumplir con requisitos regulatorios.

¿Qué es 3D Secure?

3D Secure (3DS) es un protocolo de autenticación que añade una capa adicional de seguridad a las transacciones con tarjeta. Cuando está activo, el banco emisor puede solicitar al titular de la tarjeta que se autentique durante el proceso de pago.

Beneficios:

• ✅ Reducción de fraude
• ✅ Cumplimiento regulatorio
• ✅ Confianza del cliente

---

Flujo de Autenticación

No todas las transacciones requieren 3DS

El sistema evalúa automáticamente cada transacción. Solo cuando es necesario, recibirás el estado AUTHENTICATION_REQUIRED.

---

Implementación

Paso 1: Primera petición

Siempre envía authenticationId: null en tu primera petición de pago o suscripción.

Pagos

{
    "customer": {
        "id": "customer112",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "order": {
        "id": "EPAY001",
        "amount": 15.9,
        "description": "seguro",
        "name": "auto"
    },
    "cardId": "69167196381d34f25eb22e9d",
    "authenticationId": null,
    "locationCode": "N1C0CD001"
}

Suscripciones

{
    "planId": 1544,
    "customer": {
        "id": "Customer001",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "paymentMethod": {
        "id": "689f93049b36afba505e7bc8"
    },
    "backupPaymentMethod": {
        "id": "689f69319b36afba505e7bc0"
    },
    "authenticationId": null,
    "locationCode": "N1C0CD001"
}

Paso 2: Manejar respuesta

Si recibes el estado AUTHENTICATION_REQUIRED, debes mostrar el iframe de autenticación:

Pagos

{
    "status": "AUTHENTICATION_REQUIRED",
    "message": "El pago requiere autenticación 3DS",
    "error": null,
    "authentication": {
        "url": "https://front-3ds.h4b.dev/authentication/b574cee2-1ce7-4aa7-b176-8a6390e91081",
        "id": "b574cee2-1ce7-4aa7-b176-8a6390e91081"
    },
    "order": null,
    "createdAt": "2023-09-28T18:53:51.1070240Z"
}

Suscripciones

{
    "status": "AUTHENTICATION_REQUIRED",
    "message": "El pago requiere autenticación 3DS",
    "error": null,
    "authentication": {
        "url": "https://front-3ds.h4b.dev/authentication/9b77e558-7d5d-4fdd-b84c-f295225ba2e1",
        "id": "9b77e558-7d5d-4fdd-b84c-f295225ba2e1"
    },
    "subscription": null,
    "payment": {
        "chargeId": null,
        "authorizationCode": null
    }
}

Paso 3: Renderizar iframe

Crea un iframe para mostrar la interfaz de autenticación:

const iframe = document.createElement('iframe');
iframe.src = authentication.url;
iframe.width = 600;
iframe.height = 400;

document.getElementById('authentication-container').appendChild(iframe);

Ejemplos de implementación:

• 🔗 Vanilla JavaScript en CodeSandbox →
• ⚛️ React en CodeSandbox →

Paso 4: Escuchar PostMessage

El iframe enviará un mensaje cuando la autenticación se complete:

window.addEventListener('message', function(event) {
  // Validar origen del mensaje
  if (event.origin !== 'https://front-3ds.n1co.com') {
    return;
  }

  const data = event.data;
  
  // Manejar diferentes estados
  handleAuthenticationResult(data);
});

function handleAuthenticationResult(data) {
  const { MessageType, Status, AuthenticationId } = data;
  
  if (MessageType === 'authentication.complete' && Status === 'SUCCESS') {
    // Proceder con segunda petición
    completePayment(AuthenticationId);
  } else if (MessageType === 'authentication.failed' || Status === 'FAILED') {
    // Mostrar error al usuario
    showError('La autenticación falló. Por favor intenta con otro método de pago.');
  } else if (Status === 'EXPIRED') {
    // Autenticación expiró
    showError('La autenticación ha expirado. Por favor intenta nuevamente.');
  }
}

Estructura del PostMessage

Campo	Tipo	Descripción
MessageType	String	authentication.complete | authentication.failed
Status	String	PENDING | SUCCESS | FAILED | ERROR | EXPIRED
AuthenticationId	String	ID único de autenticación para la segunda petición
OrderId	String	ID de la orden
OrderAmount	Number	Monto de la orden

Estados posibles:

Status	Descripción	Acción
SUCCESS	✅ Autenticación exitosa	Proceder con segunda petición
FAILED	❌ No se logró autenticar con el banco	Solicitar otro método de pago
ERROR	❌ Error interno del procesador	Reintentar o contactar soporte
EXPIRED	⏱️ La sesión de autenticación expiró	Reiniciar el proceso
PENDING	⏳ Aún procesando	Continuar esperando

Paso 5: Segunda petición

Una vez recibido el mensaje con MessageType = "authentication.complete" y Status = "SUCCESS", realiza una nueva petición incluyendo el authenticationId:

Respuesta Exitosa

La respuesta de esta segunda petición será con el estado SUCCEEDED si la autenticación fue completada correctamente.

---

Mejores Prácticas

✅ Hacer

• Siempre envía authenticationId: null en la primera petición
• Valida el origen de los mensajes PostMessage para seguridad
• Maneja todos los estados posibles (SUCCESS, FAILED, ERROR, EXPIRED, PENDING)
• Proporciona mensajes claros al usuario durante el proceso
• Registra los eventos: Para debugging y análisis
• Diseña UI responsive: El iframe debe adaptarse a diferentes dispositivos

❌ Evitar

• ❌ No reutilices authenticationId de transacciones anteriores
• ❌ No envíes authenticationId si no recibiste AUTHENTICATION_REQUIRED

---

Diagrama Completo del Flujo

---

Recursos Adicionales

• 📘 Aceptar Pagos
• 📘 Crear Suscripciones