Sandbox para transacciones con 3D Secure (v1) - deprecada

IMPORTANTE: Esta versión se encuentra deprecada recomendamos migrar a la nueva version de transacciones con 3D Secure.

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í.

¿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.

Nota:

1. El protocolo de 3DS está disponible para las transacciones con las franquicias Mastercard y Visa.
2. 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í.

¿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.

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).

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. challenge: Indica que se deberá renderizar un IFRAME y seleccionar la opción en la que queremos que quede el estado final de la transacción (APROBADA, DECLINADA o ERROR).
2. no_challenge: Indica que se realizará la autenticación con 3D Secure pero no habrá que renderizarle nada al usuario final, la transacción quedará en estado APROBADA.
3. error: Indica que la autenticación terminará en estado ERROR y de igual manera la transacción.

Con esto en mente, para crear la transacción tendremos que hacer una peticion 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
  "payment_method": {
    "type": "CARD",
    "token": "token_val_12345..." // Generado en el 2 paso
  },
  //Campos necesarios para 3DSecure
  "is_three_ds": true,
  "three_ds_auth_type": "challenge" //challenge | no_challenge | error
}

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

Obtendremos de vuelta el siguiente JSON:

{
  "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
      },
      "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.

Nota: esta consultas se deben realizar reiterativamente debido a que dentro de la integración es necesario renderizar el IFRAME por cada proceso (BROWSER_INFO, FINGERPRINT, CHALLENGE), que es detallado en el siguiente paso.

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. 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. A continuación, se muestra cómo aparecen estos elementos en la respuesta de la transacción:

{
  "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",
        "three_ds_auth": {
          "current_step": "BROWSER_INFO", // Hace referencia al proceso que se está ejecutando: (BROWSER_INFO - FINGERPRINT - 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": "CC",
      "email": "pepito@prueba.com",
      "legal_id": "1036000000"
    },
    "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": "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": {
          "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": "CC",
      "email": "prueba@test.com",
      "legal_id": "1036000000"
    },
    "taxes": []
  }
}

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:

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 aparecerte un mensaje en rojo en la parte superior indicando que estas en modo Sandbox, recuerda volver a esta misma sección para reestablecer el modo productivo una vez decidas terminar las pruebas.

Paso 5. Dirigite a la sección de Recibir pagos y selecciona Link pago genérico.

Paso 6. Da click el botón "Copiar al portapapeles" (o da click en link para abrirlo una nueva pestaña) y pegalo en una nueva ventana.

Paso 7. Una vez abierto el link de pago, confirma que en la parte superior se visualize el mensaje Modo de pruebas, si es así continua con los siguientes pasos, sino vuelve a realizar el proceso de activar el modo de pruebas en tu comercio.

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: 2303779951000420, requiere autenticación 3D Secure.
• Para una autenticación "frictionless": 2303779951000453, se autenticará la tarjeta existosamente pero no requiere challenge.
• Para una autenticación con error: 2303779951000347, la autenticación terminará en estado error.

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.

Paso 12. Una vez seleccionada la opción, se te 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.