🚧

Importante:

Disponible solo para comercios con certificación PCI DSS vigente y habilitación explícita de Conekta.

En esta sección se describe cómo enviar a Conekta el resultado de una autenticación 3D Secure que tú ya obtuviste por fuera, para que la transacción se autorice como autenticada sin que Conekta ejecute un challenge propio.

Es el flujo indicado si eres un orquestador o partner PCI que ya corre su propio 3D Secure y necesita que Conekta respete esa autenticación en lugar de iniciar una nueva.

Aplica a cargos con tarjeta real (FPAN), ya sea bajo tu alcance PCI o con token_id.

📘

Esto no es para wallets

Si lo que necesitas es enviar un payload de Apple Pay o Google Pay ya desencriptado, ese es otro flujo: consulta Apple Pay con payload desencriptado o Google Pay con payload desencriptado. En aquellos la autenticación viaja dentro del criptograma de la wallet; aquí se envía por separado.

Cómo integrar un cargo con 3DS externo

1. Obtén la autenticación por tu cuenta

Ejecuta el flujo de 3D Secure con tu proveedor. Al terminar tendrás el criptograma de autenticación (CAVV/AAV), el ECI, la versión de 3DS utilizada, el identificador de transacción del Directory Server y el estado de la autenticación.

2. Envía el resultado en el cargo

Incluye el bloque two_factor_authentication dentro del cargo, con source en external:

curl -H "Accept: application/vnd.conekta-v2.3.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
    "currency": "MXN",
    "line_items": [{
      "name": "Nombre del Producto o Servicio",
      "unit_price": 2000,
      "quantity": 1
    }],
    "customer_info": {
      "customer_id": "cus_xxxxxxxxxxxx"
    },
    "charges": [{
      "payment_method": {
        "type": "card",
        "payment_source_id": "src_xxxxxxxxxxxx"
      },
      "two_factor_authentication": {
        "source": "external",
        "cavv": "AAABCZIhcQAAAABZlyFxAAAAAAA=",
        "eci": "05",
        "version": "2.2.0",
        "status": "Y",
        "directory_server_transaction_id": "f38e6948-5388-41a6-bca4-b49723c19437"
      }
    }]
}' https://api.conekta.io/orders

El cargo se autoriza marcado como autenticado con 3DS.

La orden regresa pagada de inmediato, sin next_action: no hay redirección porque el challenge ya ocurrió de tu lado. El cargo trae three_ds_source: "external", que es lo que distingue a este flujo, y three_ds_flow_status refleja el ECI que enviaste.

{
    "livemode": false,
    "amount": 2000,
    "currency": "MXN",
    "payment_status": "paid",
    "object": "order",
    "id": "ord_xxxxxxxxxxxx",
    "charges": {
        "object": "list",
        "total": 1,
        "data": [
            {
                "id": "68a5e90679fcdd001abab501",
                "currency": "MXN",
                "payment_method": {
                    "auth_code": "681417",
                    "object": "card_payment",
                    "type": "credit",
                    "last4": "4242",
                    "brand": "visa",
                    "country": "MX",
                    "three_ds_flow_required": false,
                    "three_ds_flow_status": "approved",
                    "three_ds_source": "external"
                },
                "object": "charge",
                "status": "paid",
                "amount": 2000,
                "paid_at": 1762153200,
                "order_id": "ord_xxxxxxxxxxxx"
            }
        ]
    }
}

Valores aceptados

ECI y estado

El ECI y el status deben ser consistentes entre sí. Una combinación cruzada — por ejemplo status: "Y" con eci: "06" — se rechaza.

🚧

Los intentos de autenticación se habilitan aparte

Una autenticación puede terminar de dos formas. En la completa el emisor verificó al tarjetahabiente (status: "Y", ECI 05 o 02). En el intento el emisor no participó pero la red deja constancia de que lo intentaste (status: "A", ECI 06 o 01); el traslado de responsabilidad es más débil.

Conekta acepta los dos, pero los de intento requieren que tu cuenta esté habilitada para ellos, aparte de la habilitación general de 3DS externo. Si no lo está y envías un ECI de intento, el cargo se rechaza con eci.eci_attempt_not_allowed. Mientras tanto, envía únicamente autenticaciones completas.

Versión de 3DS

La versión determina cuál de los dos identificadores de transacción debes enviar:

• 3DS 2.x → envía directory_server_transaction_id en formato UUID. No envíes xid.
• 3DS 1.x → envía xid. No envíes directory_server_transaction_id.

Enviar el identificador que no corresponde a la versión declarada se rechaza.

Errores

Si faltan datos de la autenticación o son inconsistentes, la petición se rechaza. Conekta no procesa el cargo como no autenticado de forma silenciosa.

Consideraciones

• Protección ante contracargos. Una transacción autenticada por esta vía cuenta como protegida frente a contracargos por motivo de fraude, igual que una autenticada por Conekta.
• Conekta no inicia challenge. No envíes three_ds_mode ni return_url junto con este bloque: la autenticación ya ocurrió de tu lado.
• Limitaciones del adquirente. Según la red y el adquirente, algunos campos pueden no viajar completos hasta el emisor. Esto no afecta la autorización.

👍

Ver también

• Activar 3DS - Direct API — las modalidades en las que Conekta ejecuta la autenticación.
• Apple Pay con payload desencriptado · Google Pay con payload desencriptado — el flujo equivalente para wallets.