Fuentes de Pago Seguras con 3D Secure (Sandbox)

Introducción

En esta guía, aprenderás cómo crear y utilizar fuentes de pago seguras con 3D Secure en el entorno Sandbox de Wompi. 3D Secure es un protocolo de seguridad que añade una capa adicional de autenticación para las transacciones en línea, ayudando a prevenir fraudes y proteger tanto a los comerciantes como a los compradores.

Recomendaciones de seguridad

Proteger tu negocio y tu dinero es una de nuestras prioridades. Consulta nuestras recomendaciones de seguridad para fortalecer tu integración.

---

Activación del protocolo 3D Secure para fuentes de pago

Activación requerida

Para habilitar 3D Secure para fuentes de pago en tu integración, debes solicitarlo a través de nuestro canal de soporte:

Pasos para solicitar la activación:

1. Accede al Centro de Soporte Wompi
2. Dirígete al módulo "Contáctanos"
3. Completa el formulario con los siguientes datos:
   • Tipo de solicitud: Integración
   • Asunto: Copia y pega uno de estos textos según tu necesidad:
     • Para sandbox: Activación de 3D Secure en fuentes de pago - sandbox
     • Para producción: Activación de 3D Secure en fuentes de pago - producción
   • Descripción: Indica cualquier detalle adicional relevante para tu solicitud

Importante

Si necesitas 3D Secure para fuentes de pago en ambos ambientes (sandbox y producción), debes enviar dos solicitudes separadas, una por cada ambiente.

---

¿Cómo funciona 3D Secure en una fuente de pago?

El flujo de una fuente de pago con 3D Secure sigue estos pasos. Usaremos como ejemplo la suscripción a un servicio:

1. Inicio del pago — Tu cliente selecciona productos/servicios y procede al checkout en tu plataforma.

2. Redirección a autenticación — Después de ingresar los datos de la tarjeta, el cliente es redirigido automáticamente a la página de autenticación del banco emisor.

3. Autenticación del titular — El banco solicita al cliente que ingrese una contraseña, código OTP, huella digital u otro método de verificación.

4. Autorización de la fuente de pago — Una vez autenticado correctamente, el banco genera un mensaje de autenticación exitosa y lo envía al adquirente.

5. Disponibilización de la fuente de pago — El adquirente recibe el mensaje de autenticación exitosa y procede a autorizar la fuente de pago. Si la autenticación es exitosa, la fuente de pago se considera segura y se puede utilizar para completar la transacción.

6. Procesamiento de la transacción — Se verifica que haya fondos suficientes y que la transacción cumpla con las reglas antifraude.

7. Confirmación — Se muestra al cliente una confirmación indicando que la transacción se completó exitosamente.

8. Cobro recurrente — Si la fuente de pago es para una suscripción, el sistema realizará cargos automáticos en los intervalos definidos usando la fuente de pago segura creada.

Diagrama de flujo de implementación

El siguiente diagrama muestra el flujo técnico completo para implementar fuentes de pago con 3D Secure desde el frontend:

Este diagrama ilustra:

• El proceso completo desde obtener el token de aceptación hasta la creación de la fuente de pago
• La tokenización de la tarjeta antes de crear la fuente de pago
• La estrategia de polling para consultar el estado de la fuente de pago
• El manejo del challenge cuando es requerido por el banco emisor
• Los diferentes estados finales posibles: AVAILABLE (exitosa), DECLINED o ERROR

---

Consideraciones importantes

Información clave sobre 3D Secure

1. Protección 3RI: Al crear una fuente de pago segura con 3DS y utilizar el ID de la fuente de pago en transacciones automáticas, estas estarán protegidas bajo el protocolo 3RI.

2. Franquicias soportadas para 3DS: El protocolo está disponible para Mastercard y Visa.

3. Franquicias soportadas para 3RI: El protocolo 3RI para transacciones automáticas está disponible en Mastercard.
   → Más información: Transacciones automáticas con 3RI

4. Disponibilidad: La disponibilidad del protocolo 3DS por franquicia puede variar según el modelo de tu comercio comercio (Gateway o Agregador). Te recomendamos comunicarte con nuestros canales de atención para resolver tus dudas.

5. Fuentes de pago sin 3DS: Si necesitas crear fuentes de pago sin este protocolo, consulta: Fuentes de pago & Tokenización

6. 3DS para transacciones no recurrentes: Si necesitas implementar 3DS en transacciones individuales (no recurrentes), visita: Transacciones con 3D Secure (Sandbox) v2

Recursos adicionales

• Guía de 3D Secure para comercios (PDF)
• Guía de 3D Secure para pagadores (PDF)

---

Implementación con API

A continuación te explicamos cómo implementar 3D Secure en tu plataforma paso a paso.

Requisitos previos

Antes de comenzar, asegúrate de tener:

1. Llaves de autenticación

• Necesitarás tu llave pública para incluirla como Bearer token en los headers de las peticiones.
• Consulta cómo obtenerlas: Llaves de autenticación

2. Tarjetas de prueba

Usa estas tarjetas según el escenario que quieras simular:

Escenario	Número de tarjeta	Datos adicionales
Autenticación con Challenge	2303 7799 5100 0446	Cualquier fecha futura, CVV y nombre
Error en autenticación	2303 7799 5100 0354	Cualquier fecha futura, CVV y nombre
Error en supported version	2303 7799 5100 0347	Cualquier fecha futura, CVV y nombre

3. URLs de ambiente

• Consulta las URLs del ambiente Sandbox

---

Flujo de implementación

Paso 1: Obtener un token de aceptación

Obtén un token de aceptación prefirmado para poder crear la fuente de pago.

---

Paso 2: Tokenizar la tarjeta

Tokeniza el medio de pago (tarjeta de crédito o débito) antes de crear la fuente de pago.

---

Paso 3: Crear la fuente de pago con 3D Secure

Realiza una solicitud POST al siguiente endpoint:

POST https://sandbox.wompi.co/v1/payment_sources

Headers requeridos

Authorization: Bearer pub_test_tu_llave_publica
Content-Type: application/json

Parámetros del body

Parámetro	Tipo	Descripción	Requerido
type	String	Tipo de fuente de pago. Usa CARD para tarjetas.	✅ Sí
token	String	Token de la tarjeta obtenido en el Paso 2.	✅ Sí
customer_email	String	Correo electrónico del cliente.	✅ Sí
acceptance_token	String	Token de aceptación del Paso 1.	✅ Sí

Ejemplo de solicitud

{
  "type": "CARD",
  "token": "tok_test_1234567890abcdef",
  "customer_email": "pepe@example.com",
  "acceptance_token": "acceptance_test_1234567890abcdef"
}

---

Paso 4: Interpretar la respuesta inicial

Como la tarjeta requiere autenticación 3D Secure, el estado inicial será PENDING hasta que se complete el proceso.

Ejemplo de respuesta

{
  "data": {
    "id": 123456,
    "public_data": {
      "bin": "230377",
      "last_four": "0446",
      "exp_month": "08",
      "exp_year": "30",
      "card_holder": "Pepe Perez",
      "validity_ends_at": "2031-08-29T14:35:02.547+00:00",
      "type": "CARD"
    },
    "token": "tok_test_1234567890abcdef",
    "type": "CARD",
    "status": "PENDING",
    "customer_email": "pepe@example.com"
  },
  "meta": {}
}

Estado PENDING

El estado PENDING indica que el proceso de autenticación 3D Secure está en curso. Debes proceder al siguiente paso para completarlo.

---

Paso 5: Consultar el estado de autenticación (Polling)

Realiza consultas periódicas al endpoint de consulta de fuente de pago para obtener los datos de autenticación:

GET https://sandbox.wompi.co/v1/payment_sources/{payment_source_id}

Reemplaza {payment_source_id} con el ID obtenido en el Paso 4.

Headers requeridos

Authorization: Bearer pub_test_tu_llave_publica

Respuesta con datos de autenticación

Cuando el proceso de 3DS se active, encontrarás un objeto three_ds_auth dentro del campo extra:

{
  "data": {
    "id": 123456,
    "status": "PENDING",
    "extra": {
      "three_ds_auth": {
        "current_step": "CHALLENGE",
        "current_step_status": "PENDING",
        "three_ds_method_data": "<!DOCTYPE html><html>...</html>"
      }
    }
  }
}

Campos de three_ds_auth

Campo	Descripción	Posibles valores
current_step	Paso actual del flujo 3DS	CHALLENGE, BROWSER_INFO, etc.
current_step_status	Estado del paso actual	PENDING, COMPLETED, ERROR
three_ds_method_data	Formulario HTML para el challenge (solo si aplica)	String con HTML

---

Paso 6: Renderizar el challenge (si es requerido)

Si el campo three_ds_method_data está presente, debes:

1. Extraer el HTML contenido en este campo
2. Renderizarlo dentro de un iframe en tu página
3. Permitir que el usuario complete el desafío de autenticación

Ejemplo visual del challenge

Ejemplo de challenge renderizado en iframe

Nota sobre el challenge en Sandbox

En el ambiente Sandbox, el challenge es una simulación. El usuario puede elegir entre tres opciones: APPROVED, DECLINED o ERROR. La opción seleccionada determinará el estado final de la fuente de pago.

En producción, el contenido del challenge lo define el banco emisor y variará según la institución financiera.

---

Paso 7: Verificar el estado final

Continúa realizando consultas periódicas hasta que el estado cambie de PENDING a uno de estos estados finales:

Estado	Significado
AVAILABLE	✅ Autenticación exitosa. La fuente de pago está lista para usarse.
DECLINED	❌ Autenticación fallida. La fuente de pago no puede usarse.
ERROR	⚠️ Ocurrió un error durante el proceso de autenticación. La fuente de pago no puede usarse.

Ejemplo de respuesta exitosa

{
  "data": {
    "id": 123456,
    "public_data": {
      "bin": "230377",
      "last_four": "0446",
      "exp_month": "08",
      "exp_year": "30",
      "card_holder": "Pepe Perez",
      "validity_ends_at": "2031-08-29T14:35:02.547+00:00",
      "type": "CARD"
    },
    "token": "tok_test_1234567890abcdef",
    "type": "CARD",
    "status": "AVAILABLE",
    "customer_email": "pepe@example.com",
    "extra": {
      "three_ds_auth": {
        "current_step": "CHALLENGE",
        "current_step_status": "COMPLETED"
      }
    }
  },
  "meta": {}
}

---

Escenarios comunes y cómo manejarlos

Durante la implementación de 3D Secure, pueden presentarse algunas situaciones que debes conocer para brindar la mejor experiencia a tus usuarios.

Escenario 1: El usuario abandona el flujo de autenticación

Es común que durante el paso de CHALLENGE algunos usuarios cierren la ventana o naveguen a otra página sin completar la autenticación.

¿Qué sucede?
Wompi tiene un tiempo límite para completar el flujo de autenticación 3DS. Si este tiempo se agota, la fuente de pago quedará en estado DECLINED o ERROR.

Cómo manejarlo:

• Muestra un mensaje amigable indicando que el proceso de verificación quedó incompleto
• Ofrece la opción de reintentar creando una nueva fuente de pago
• Considera implementar recordatorios visuales durante el proceso para reducir el abandono

---

Escenario 2: Tarjeta no compatible con 3DS

Algunas tarjetas pueden no ser compatibles con el protocolo 3DS. Esta validación se realiza automáticamente antes del paso de Browser Info.

¿Qué sucede?
La fuente de pago quedará inmediatamente en estado DECLINED y el flujo finalizará.

Cómo manejarlo:

• Informa al usuario de forma clara que su tarjeta no soporta esta modalidad de pago
• Ofrece alternativas como el flujo de fuentes de pago sin 3DS
• Sugiere usar otro medio de pago si está disponible en tu plataforma

tip

Cuando crees una fuente de pago segura con 3DS y uses su ID en transacciones automáticas, estas estarán protegidas bajo el protocolo 3RI. Consulta las consideraciones en: Transacciones automáticas con 3RI

---

Próximos pasos

Una vez que hayas completado la implementación en Sandbox y verificado que todo funciona correctamente:

1. Solicita la activación en producción siguiendo los pasos de la sección "Activación del protocolo 3D Secure"
2. Actualiza tus credenciales para usar las llaves de producción
3. Realiza pruebas exhaustivas en producción antes del lanzamiento final

¿Tienes dudas? Contáctanos a través de nuestro Centro de Soporte.