En este documento se describe cómo realizar la integración para utilizar 3D Secure 2 a través de Direct API. Es aconsejable que previamente se haya leído y/o implementado la guía para crear un cargo único.

Si estás recibiendo pagos con Conekta a través de otro método de integración, esta funcionalidad es configurable directamente desde tu Panel.

📘

¿Qué es 3DS2?

3D Secure 2 (también conocido como 3DS2) es un protocolo de autenticación diseñado para mejorar la seguridad de las transacciones en línea con tarjetas. Para conocer todos los detalles, ingresa en nuestro Resumen.

Recuerda que la utilización de esta funcionalidad (en su modalidad strict/Total) trae costos asociados y debes firmar un acuerdo con precios y condiciones del servicio.

Diagrama de secuencia

🚧

Importante:

Esta funcionalidad se encuentra vigente a partir de la versión 2.1.0 de Direct API (considerarlo en los headers de los requests).

No es requisito hacer el prendido de esta funcionalidad en Panel para integraciones vía Direct API o Component. El encendido vía Panel funciona para otros métodos de integración.

Modalidades de 3DS2 disponibles

La tecnología creada por Conekta permite a los negocios utilizar 3DS2 en dos modalidades.

Al crear una orden, es posible especificar la modalidad de 3DS2 deseada eligiendo entre las siguientes opciones:

❗️

Atención:

1- En caso de no agregar este atributo, el cargo cursará el flujo normal sin 3DS2.

2- Es posible que la implementación de la modalidad strict pueda llevar a reducciones en los índices de conversión en tu proceso de pago. Esto se debe a que todas las transacciones se verían obligadas a pasar por la autenticación de 3DS, y aunque cada vez más emisores están adoptando esta tecnología, no todos los titulares de tarjetas tienen configurada la recepción del token de autenticación al momento de efectuar el pago.

Cómo integrar una orden con 3DS2

Para integrar una orden con 3DS2 es necesario realizar los siguientes pasos:

1. Crear orden con modalidad 3DS2.
2. Presentar el flujo 3DS2.
3. Consultar estado de la orden.

1 - Crear orden con modalidad 3DS2

Para autenticar tus pagos con 3DS2 en alguna de sus modalidades descriptas más arriba, deberás incluir dos nuevos atributos al payload de la creación de una orden: three_ds_mode y return_url, donde:

{
    "currency": "MXN",
    "three_ds_mode": "smart", 
    "return_url": "https://my-website.com",	
    "customer_info": {
        "customer_id": "cus_2tx81xbH2yEHxvmhD"
    },
    "line_items": [
        {
            "name": "Blusa",
            "unit_price": 2000,
            "quantity": 1
        }
    ],
    "charges": [
        {
            "payment_method": {
                "type": "default"
            }
        }
    ]
}

{
    "livemode": true,
    "amount": 2000,
    "currency": "MXN",
    "payment_status": "pending_payment",
    "amount_refunded": 0,
    "split_payment": false,
    "customer_info": {
        "email": "[email protected]",
        "phone": "+5215555555555",
        "name": "Test",
        "corporate": false,
        "customer_id": "cus_2u2fzGiwU9XQHAhk1k",
        "object": "customer_info",
        "customer_custom_reference": null
    },
    "fiscal_entity": null,
    "next_action": {
        "redirect_to_url": {
            "url": "https://3ds-pay.conekta.com/88f347d6-a767-495f-a5ef-b44bfd888dd2",
            "return_url": "https://www.my-website.com"
        },
        "type": "redirect_to_url"
    },
    "object": "order",
    "id": "ord_2u2gCyvhfyytrUrhv",
    "metadata": {},
    "is_refundable": false,
    "created_at": 1686579964,
    "updated_at": 1686579964,
    "line_items": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "name": "Blusa",
                "description": null,
                "unit_price": 2000,
                "quantity": 1,
                "sku": null,
                "tags": null,
                "brand": null,
                "type": null,
                "object": "line_item",
                "id": "line_item_2u2gCyvhfyytrUrhs",
                "parent_id": "ord_2u2gCyvhfyytrUrhv",
                "metadata": {},
                "antifraud_info": {}
            }
        ]
    },
    "shipping_lines": null,
    "tax_lines": null,
    "discount_lines": null,
    "charges": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "id": "64872afc5f8aa7001b14625a",
                "livemode": true,
                "created_at": 1686579964,
                "currency": "MXN",
                "failure_code": null,
                "failure_message": null,
                "monthly_installments": null,
                "device_fingerprint": null,
                "channel": {
                    "segment": "Checkout",
                    "checkout_request_id": "88f347d6-a767-495f-a5ef-b44bfd888ce2",
                    "checkout_request_type": "HostedPayment",
                    "id": "channel_2u2gCyvhfyytrUri8"
                },
                "payment_method": {
                    "name": "Test User",
                    "exp_month": "12",
                    "exp_year": "28",
                    "auth_code": null,
                    "object": "card_payment",
                    "type": "credit",
                    "normalized_device_fingerprint": null,
                    "last4": "9999",
                    "brand": "mastercard",
                    "issuer": "test_card",
                    "account_type": "STANDARD",
                    "country": "MY",
                    "fraud_score": null,
                    "fraud_indicators": [],
                    "token_id": "tok_2u2fw6tvpWMsZvSzq"
                },
                "object": "charge",
                "description": "Payment from order",
                "is_refundable": false,
                "reference_id": null,
                "status": "pending_payment",
                "amount": 2000,
                "paid_at": null,
                "customer_id": "cus_2u2fzGiwU9XQHAhkk",
                "order_id": "ord_2u2gCyvhfyytrUrhv",
                "customer_custom_reference": null,
                "refunds": null
            }
        ]
    }
}

2 - Presentar el flujo 3DS2

La respuesta de las creaciones de ordenes con 3DS2 incorporan el objeto next_action, que a contiene los siguientes atributos que guiarán para continuar el flujo:

En caso de utilizar la modalidad smart y Conekta no considere que el cargo represente un riesgo para el comercio, el pago continuará su curso habitual y no existirá el atributo next_action.

2.1 - Tipos de Integración

Una vez obtenida la respuesta de la creación de la orden, obtendrás la URL de nuestro componente de 3DS2 en el atributo next_action.redirecto_to_url.url, el cual podrás integrarlo de 2 formas:

2.1.1 - Integración Embebida [Recomendada]

En este tipo de integración deberás renderizar la url de redirección de manera embebida utilizando un iFrame, agregando el query-param source como se visualiza en el siguiente ejemplo:

<iframe id="iframe" src={`${url}?source=embbeded`}></iframe>

🚧

Importante:

Es aconsejable que la url de redirección se muestre en un modal con al menos 500px de ancho y 600px de alto.

• NOTA: Es altamente aconsejable que la URL utilizada para la redirección sea absoluta.

Cuando el flujo de autenticación finalice nuestro componente de 3DS2 emitirá un evento el cual podrás utilizar para validar si el flujo finalizó correctamente. Este evento lo puedes capturar de la siguiente forma:

const ENV_URL = '<https://3ds-pay.conekta.io'>;

window.addEventListener('message', (event) => {  
  if (event.origin === ENV_URL) {  
    const { checkout_id, order_id, payment_status } = event.data;  
    console.log('data', event.data);  
  }  
});

Nota: Es necesario que valides el origen del mensaje para identificar la respuesta.

2.1.2 - Integración Redireccionada

En este tipo de integración deberás renderizar la url de redirección en una nueva ventana/pestaña del navegador.

Cuando el flujo de autenticación finalice Conekta hará una redirección a la URL indicada en el atributo return_url de la creación del cargo incorporando el query-param payment_status con el resultado: aprobado o rechazado, devolviendo el control del flujo de pago al comercio.

3 - Consultar estado de la orden

En ambos tipos de integración (redireccionada o embebida) recomendamos que se realice una consulta al estado de la orden o se valide el mismo por notificación vÍa webhook.

🚧

Importante:

No te olvides de consultar al estado de la cargo o validar la notificación vÍa webhook.

Tipos de autenticación

La autenticación 3DS2 ofrece dos tipos: Frictionless y Challenge, dependerá del banco emisor y la marca de la tarjeta cual estas opciones aplicará en cada pago (el tipo de flujo es decisión del emisor de la tarjeta.), donde:

• Frictionless: la autenticación se realiza sin requerir intervención del cliente.
• Challenge: esta opción requiere intervención del cliente, al cual se enviará un código de autenticación a través de los canales proporcionados por su banco emisor, como por ejemplo SMS, email, notificaciones en su app, entre otros, que el cliente deberá completar para continuar con el pago.

Compartimos un ejemplo visual del Challenge en el ambiente de pruebas.

🚧

Atención:

La adopción de 3DS2 está en aumento en México. Sin embargo, es posible que muchos clientes no tengan configurado su método de comunicación para recibir el token de autenticación. Por este motivo, es importante que indiquemos a nuestros clientes que se pongan en contacto con su banco emisor para recibir ayuda y así poder completar el proceso de autenticación de manera adecuada.

Tarjetas de Prueba

Utiliza la siguiente información para realizar todas las pruebas necesarias con respecto a tu integración con el servicio de 3DS2 y algunos comportamientos relacionados, como por ejemplo, autenticaciones aprobadas o rechazadas por los distintos flujos de 3DS2.