La configuración de 3DS se realiza a través del nodo config.online.transaction_security al crear la order. Para crear una order con 3DS, envía un POST al endpoint /v1/ordersAPI incluyendo tu Access Token de pruebaClave privada de pruebas de la aplicación creada en Mercado Pago y que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba.. La solicitud debe contener los parámetros obligatorios listados a continuación.

curl --request POST \
  --url https://api.mercadopago.com/v1/orders \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
  --data '{
  "type": "online",
  "external_reference": "3ds_test",
  "processing_mode": "automatic",
  "capture_mode": "automatic_async",
  "total_amount": "150.00",
  "config": {
    "online": {
      "transaction_security": {
        "validation": "on_fraud_risk",
        "liability_shift": "required"
      }
    }
  },
  "payer": {
    "email": "test@testuser.com"
  },
  "transactions": {
    "payments": [
      {
        "amount": "150.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "{{CARD_TOKEN}}",
          "installments": 1
        }
      }
    ]
  }
}'

Después de crear la order, la respuesta indicará si el Challenge es necesario. Si no es exigido, el campo status traerá el valor processed, permitiendo que sigas normalmente con el flujo de la aplicación. Si el Challenge es necesario, la order será retornada con status: action_required, status_detail: pending_challenge, y la URL del Challenge estará disponible en el campo payment_method.transaction_security.url, como se muestra en el ejemplo a continuación:

{
  "id": "ORDTST01KBD0NXX289XWW91Q9NNJ26V3",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_3ds",
  "total_amount": "150.00",
  "total_paid_amount": "150.00",
  "country_code": "ARG",
  "user_id": "791690672",
  "status": "action_required",
  "status_detail": "pending_challenge",
  "capture_mode": "automatic_async",
  "currency": "ARS",
  "created_date": "2025-12-01T13:12:23.202Z",
  "last_updated_date": "2025-12-01T13:12:24.943Z",
  "integration_data": {
    "application_id": "8275829243271683"
  },
  "config": {
    "online": {
      "transaction_security": {
        "validation": "on_fraud_risk",
        "liability_shift": "required"
      }
    }
  }
  "transactions": {
    "payments": [
      {
        "id": "PAY01KBD0NXX289XWW91Q9P1BF71Q",
        "amount": "150.00",
        "paid_amount": "150.00",
        "reference_id": "0007aoefzk",
        "status": "action_required",
        "status_detail": "pending_challenge",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "adac6b95f1d22c51890499d1707f0f0a",
          "installments": 1,
          "transaction_security": {
            "url": "https://www.mercadopago.com.ar/auth/card/validation/pages/remedies/019ada0a-fe1f-7a82-ba1a-1ccb4e0232e7?display_mode=self_hosted&guest_token=0661345a-e0e1-4c09-aff9-b7929ca9a24a",
            "validation": "on_fraud_risk",
            "liability_shift": "required"
          }
        }
      }
    ]
  }
}

Para mostrar el Challenge, crea un iframe utilizando la URL retornada en transactions.payments[i].payment_method.transaction_security.url. Este iframe debe incorporarse en la página de checkout, permitiendo que el comprador realice la autenticación sin salir del flujo.

Cuando el Challenge se inicia, en el momento en que se crea la URL, el comprador tiene 40 minutos para completarlo. Si no se completa en este período, el banco rechazará la transacción y Mercado Pago considerará el pago expirado. Si se necesita menos tiempo, es posible realizar la cancelación de la transacción antes del plazo predeterminado.

La actualización del estado no es inmediata y puede tardar algunos instantes. Consulta el próximo paso para obtener más detalles sobre cómo verificar el estado de cada transacción.

Una transacción con 3DS puede presentar diferentes estados según el tipo de autenticación realizada, con o sin Challenge. Para pagos sin Challenge, el estado de la transacción será directamente processed o failed. En pagos con Challenge, la transacción retorna action_required y status_detail: pending_challenge, iniciando el proceso de autenticación con el banco. El estado final solo se mostrará después de la conclusión del Challenge.

Para verificar el resultado de la transacción después del Challenge, puedes configurar notificaciones Webhooks para recibir alertas automáticas y redireccionar al comprador a una pantalla de confirmación. Otra opción, que recomendamos, es tratar un evento iframe implementando un listener JavaScript para detectar cuándo el Challenge fue concluido y consultar el estado de la order.

Para tratar el evento iframe, sigue los pasos a continuación.

1. Implementa el listener para detectar cuando el comprador completó el Challenge:

window.addEventListener("message", (e) => {
  if (e.data.status === "COMPLETE") {
    // Challenge concluido. Redirige a la página de confirmación
    window.location.href = "confirmation.html";
  }
});

2. Utiliza el código a continuación para consultar el estado actualizado de la order y mostrarlo en la página de confirmación:

document.addEventListener("DOMContentLoaded", async function (e) {
  await checkOrderStatus();
});

async function checkOrderStatus() {
  const orderId = localStorage.getItem("orderId");

  try {
    const response = await fetch("/get_order/" + orderId, {
      method: "GET",
    });
    const result = await response.json();

    if (result.status !== 200) {
      throw new Error("Error al consultar order");
    }

    // Mostrar resultado
    document.getElementById("order-status").innerHTML =
      `Order ${result.data.id} - Status: ${result.data.status}`;

  } catch (error) {
    alert("Error inesperado: " + JSON.stringify(error));
  }
}

Consulta a continuación los principales status posibles y sus respectivas descripciones:

Además del status y status_detail de la transacción, también puedes consultar el estado específico de la autenticación 3DS en el campo transactions.payments[i].payment_method.transaction_security.status retornado en el endpoint GET /v1/orders/{id}API, donde están disponibles los valores posibles y sus descripciones.

Para validar la integración con 3DS, crea una order de prueba enviando un POST al endpoint /v1/ordersAPI incluyendo tu Access Token de pruebaClave privada de pruebas de la aplicación creada en Mercado Pago y que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. y los parámetros obligatorios, entre ellos el nodo transaction_security con validation: on_fraud_risk.

curl --request POST \
  --url https://api.mercadopago.com/v1/orders \
  --header 'Authorization: Bearer {{YOUR_TEST_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
  --data '{
  "type": "online",
  "external_reference": "3ds_test",
  "processing_mode": "automatic",
  "total_amount": "150.00",
  "config": {
    "online": {
      "transaction_security": {
        "validation": "on_fraud_risk",
        "liability_shift": "required"
      }
    }
  },
  "payer": {
    "email": "test@testuser.com"
  },
  "transactions": {
    "payments": [
      {
        "amount": "150.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "{{CARD_TOKEN}}",
          "installments": 1
        }
      }
    ]
  }
}'

Para probar el pago creado, utiliza una tarjeta de prueba, informando uno de los valores a continuación en el campo cardholder_name para simular diferentes flujos del Challenge:

En los flujos de prueba con APRO-CHOK y OTHE-CHNO, el Challenge se mostrará dentro del iframe:

El código de verificación mostrado es ilustrativo. Para concluir la prueba, haz clic en Confirmar y, a continuación, consulta los posibles status en la etapa Verificar estado de la transacción para conferir el resultado.

Después de concluir la integración con 3DS y finalizar las pruebas, tu aplicación estará lista para producción. Antes de continuar, consulta los requisitos en la documentación Ir a producción para garantizar que la integración esté apta para recibir transacciones reales.