Integración de Transacciones con 3D Secure externo

Introducción

En esta guía, aprenderás a integrar transacciones con 3D Secure externo utilizando la API de Wompi. A través de esta integración, podrás ofrecer a tus clientes una capa adicional de seguridad durante el proceso de pago, utilizando un proveedor de 3D Secure externo.

Importante!

Esta guía es solo para comercios que ya cuentan con una solución de 3D Secure externa y desean integrarla con Wompi. Si tu comercio aún no está integrado con 3D secure y quieres hacerlo a través de Wompi, puedes hacer uso de la siguiente guía para integrar 3DS con Wompi

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

---

Paso 1. Obtener un token de aceptacion prefirmado.

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

Paso 3. Ten a la mano la información de la autenticación 3D Secure proporcionada por tu proveedor externo de 3D Secure.

La estructura de esta información debe de cumplir con el siguiente contrato:

Nombre campo	Tipo de dato	Obligatorio?
trans_status	string	✅ SI
three_ds_server_trans_id	string	✅ SI
message_version	string	✅ SI
authentication_value	string	✅ SI
eci	string	✅ SI

O visto en formato JSON:

{
  "trans_status": "Y",
  "three_ds_server_trans_id": "d873-abc123-ghr678...",
  "message_version": "2.0",
  "authentication_value": "BwABApFSYsssd4l2eQQFJjAAAAAAA=",
  "eci": "02"
}

Paso 4. Crear la transacción:

Para crear la transacción será necesario realizar una solicitud POST /transactions con el siguiente cuerpo JSON incluyendo la información de 3D Secure obtenida en el paso anterior dentro del campo extra_three_ds_aut_external_provider que a su vez va dentro del objeto payment_method:

{
  "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
    "installments": 1, // Numero de cuotas
    "extra_three_ds_aut_external_provider": { // Información de 3DS proporcionada por el proveedor externo
      "eci": "001",
      "trans_status": "Y",
      "message_version": "v1",
      "authentication_value": "g5f4d3s2a1",
      "three_ds_server_trans_id": "A1S2D3FG4H5"
    }
  },
  "is_three_ds": true // Indicamos que se esta usando 3D Secure
  // otros campos...
}

Después de haber hecho la petición POST, obtendremos de vuelta un JSON parecido al siguiente:

{
  "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 5. Realizar consultas periódicas de la transacción para verificar el estado y asegurarnos de su correcta ejecución.

Puedes realizar consultas periódicas a la transacción utilizando el endpoint GET /transactions/{transaction_id} para verificar su estado.