Saltar al contenido principal
3DS Standalone ejecuta únicamente el paso de autenticación 3D Secure: no interviene ningún proveedor de pago y no se realiza ninguna autorización. La respuesta devuelve el resultado de la autenticación (criptograma ECI + CAVV y datos relacionados). El comercio usa este resultado para decidir qué hacer a continuación, por ejemplo, reenviarlo a su adquirente. El flujo usa el endpoint estándar /payments. Lo que se ejecuta depende de cómo esté configurada la ruta. Para standalone, la ruta debe resolverse únicamente a la conexión de Yuno 3DS, sin ningún proveedor de pago asociado, de modo que solo se ejecute la autenticación.

Configuración en el Dashboard

Paso 1: Crear la conexión de Yuno 3DS

Ve a Dashboard → Connections → Add Connection y selecciona Yuno 3DS. Marca la casilla “Yuno 3DS Standalone”, completa los datos del adquirente y haz clic en Next. Los datos del adquirente son los datos de registro de 3DS que te proporciona tu adquirente. Para el proveedor predeterminado (Netcetera), los campos son:
  • Acquirer BIN: el Número de Identificación Bancaria que se usa para compensar y liquidar la transacción, junto con el país donde tiene licencia.
  • Acquirer Merchant ID: el número de afiliación que proporciona el adquirente.
  • Merchant Category Code (MCC): el código que representa la categoría de tu comercio, proporcionado por el adquirente.
  • Merchant Name: el nombre comercial oficial que realiza la transacción.
  • Merchant URL: el sitio web o la plataforma en línea del comercio.
  • Merchant Country Code: el país donde se procesa el pago (ISO 3166-1).
Formulario Edit Yuno 3DS connection que muestra los campos de Set up credentials: Name, Integration type, Challenge Indicator, Experience for the challenge, Transactions expire time, Allow authentication attempt y 3DS authentication preferred version

Paso 2: Configurar la ruta

Ve a Dashboard → Routing y crea una ruta CARD que dirija todas las transacciones a la conexión de Yuno 3DS. La rama que gestiona el tráfico standalone debe resolverse únicamente a la conexión de Yuno 3DS: sin ningún proveedor de pago.
Es posible que ya tengas una ruta CARD que apunta a un proveedor de pago y quieras que la autenticación standalone coexista con ella. Puedes aislar el tráfico standalone con un grupo de condiciones sobre metadata (por ejemplo 3ds_connection = standard) que apunte únicamente a la conexión de Yuno 3DS.

Selección de una conexión específica (más de una conexión 3DS Standalone)

Es posible que tengas más de una conexión 3DS Standalone configurada, por ejemplo, una configurada en Data Only y otra sin preferencia (estándar). En ese caso, el enrutador no puede decidir por sí solo cuál usar, así que controla la selección de forma explícita con metadata. El mecanismo tiene dos partes que siempre deben funcionar en conjunto:
  1. En la ruta: agrega un grupo de condiciones por cada conexión que coincida con una clave de metadata. Por ejemplo, 3ds_connection = standard para una conexión y un valor distinto para la otra. Cada valor dirige el tráfico a la conexión que quieras.
  2. En las solicitudes: agrega una entrada metadata que lleve la misma clave y el mismo valor. Debe enviarse tanto en la solicitud de 3DS Setup como en la solicitud a /payments, y debe ser idéntica en ambas.
El 3DS Setup y el pago se enrutan de forma independiente. Si el metadata enviado en el 3DS Setup no coincide con el metadata enviado en /payments, cada llamada puede resolverse a una conexión distinta. El Setup y el pago se ejecutarían entonces en conexiones diferentes y la autenticación no se completaría. Envía siempre el mismo metadata en ambas llamadas para que seleccionen la misma conexión de la ruta.
metadata es un arreglo JSON de entradas { "key", "value" }. Envía la misma entrada en el Setup y en el pago:
Esto aplica cuando tienes una sola conexión 3DS Standalone. Si la ruta no tiene otros grupos de condiciones además de ella (ni otras conexiones ni condicionales), esta selección mediante metadata no es necesaria. La ruta se resuelve a esa conexión automáticamente.La ruta también puede combinar la conexión 3DS Standalone con otros condicionales, por ejemplo una segunda conexión standalone. En ese caso, usa el mecanismo de metadata descrito arriba para aislarla y seleccionarla.

Flujo standalone (con 3DS Setup)

El flujo standalone se ejecuta mediante un 3DS Setup que produce un three_d_secure_setup_id, el cual luego se referencia en el pago.

  1. Generar un 3DS Setup

El 3DS Setup tiene dos valores posibles en el campo type. La diferencia es quién recopila los datos del navegador y del dispositivo que se usan para la autenticación:
Si tienes más de una conexión 3DS Standalone, incluye el metadata en esta solicitud (como se muestra a continuación). Esto enruta el Setup a la conexión prevista. Recuerda enviar el mismo metadata más adelante en la solicitud a /payments.

Type STANDARD

Yuno realiza la recopilación de datos del dispositivo. El comercio debe completarla accediendo al collect_url devuelto en la respuesta y usando el token que también se entrega allí. STANDARD es el valor predeterminado, por lo que el campo type puede omitirse. Solicitud
Completar la recopilación de datos del dispositivo Después de recibir el collect_url y el token, completa la recopilación de datos del dispositivo (el 3DS Method) antes de crear el pago.
Implementación sugerida (solo como referencia, no es un contrato fijo). El nombre exacto del campo y la mecánica pueden variar según el proveedor de 3DS. Valida con el proveedor que uses. La idea general: renderiza un iframe oculto y envía automáticamente un formulario que hace POST del token al collect_url. Espera el período indicado por timeout_value y luego continúa con la creación del pago.
Si el proveedor devuelve un collect_url y un token vacíos (por ejemplo CHECKOUT_COM_3DS arriba), no hay paso de recopilación. Omítelo y pasa directamente a crear el pago.

Type MERCHANT_PROVIDED

El comercio envía por su cuenta todos los datos requeridos (browser_info y device_fingerprints), por lo que no se realiza ningún paso de recopilación de datos del dispositivo.
Usa device_fingerprints solo cuando un proveedor de 3DS que recopila estos datos por su cuenta (es decir, que no usa el collect_url) te entrega el id del fingerprint. Reenvía ese id aquí. El provider_id debe coincidir con el proveedor de 3DS configurado en la conexión.
Solicitud
Respuesta

  1. Crear el pago

Crea el pago usando el three_d_secure_setup_id generado en el paso anterior. Como la ruta se resuelve únicamente a la conexión de Yuno 3DS (sin proveedor de pago), solo se ejecuta la autenticación y se devuelve el resultado de 3DS. No se realiza ninguna autorización.
Método de pago: como este es un flujo de autenticación 3DS standalone, la tarjeta debe estar disponible para él. Envía el card_data en la solicitud o referencia un método de pago que haya sido inscrito (guardado en vault) previamente. No envíes vault_on_success: true: este flujo no lo admite.
Si usaste metadata en el 3DS Setup para seleccionar una conexión específica, debes enviar el mismo metadata aquí. De lo contrario, el pago podría enrutarse a una conexión 3DS Standalone distinta de la del Setup.
Solicitud
Workflow: una autenticación frictionless o data-only se resuelve en línea (los ejemplos se ejecutaron con workflow: DIRECT) y el resultado llega en la respuesta del pago. Un challenge requiere que el titular de la tarjeta realice una acción, por lo que el pago devuelve PENDING con un redirect_url y checkout.sdk_action_required: true. Gestiónalo con un workflow que admita redirección (REDIRECT) o con el Yuno SDK (consulta Resultados de la autenticación → Challenge).
El status / sub_status de nivel superior del pago te indican el resultado, y el resultado de 3DS está en payment_method.payment_method_detail.card.three_d_secure:
  • Frictionless / Data Only → status: SUCCEEDED, sub_status: THREE_D_SECURE_VERIFIED.
  • Challenge → status: PENDING, sub_status: WAITING_ADDITIONAL_STEP, con checkout.sdk_action_required: true y un redirect_url (se resuelve más tarde; consulta Notificación por webhook).
  • Autenticación fallida o rechazada → status: DECLINED.
Un pago standalone se resuelve finalmente en SUCCEEDED / THREE_D_SECURE_VERIFIED (autenticación completada) o en DECLINED (autenticación fallida o rechazada). El estado a nivel de transacción y los códigos de respuesta de 3DS siguen la referencia estándar de Yuno: Estados de transacción y códigos de respuesta. Algunos códigos de ejemplo son SUCCEEDED_THREE_D_SECURE, CHALLENGE_REQUIRED, AUTHENTICATION_FAILED_THREE_D_SECURE y REJECTED_THREE_D_SECURE_REQUIRED.

Resultados de la autenticación

Frictionless

Objeto three_d_secure (dentro del detalle de la tarjeta):
Resumen del flujo:
  1. Se envía la solicitud de autenticación al ACS.
  2. El ACS autentica mediante análisis de riesgo, sin interacción del usuario.
  3. Devuelve los datos completos (criptograma, ECI, dsTransID, versión) con pares_status = Y; el pago es SUCCEEDED / THREE_D_SECURE_VERIFIED.
  4. El resultado está disponible en la respuesta del pago. Traslado de responsabilidad = sí.

Data Only

Objeto three_d_secure (dentro del detalle de la tarjeta):
Resumen del flujo:
  1. Solo se comparten los datos del navegador y del dispositivo con el emisor para alimentar sus modelos de riesgo: no ocurre una autenticación real.
  2. El flujo continúa como frictionless y devuelve un resultado (SUCCEEDED / THREE_D_SECURE_VERIFIED, pares_status = I).
  3. Traslado de responsabilidad = NO: el comercio conserva la responsabilidad por fraude. Normalmente ECI 04.

Challenge

El pago regresa como PENDING con un redirect_url y checkout.sdk_action_required: true. En este punto, el objeto three_d_secure contiene los datos del challenge (pares_status: C, ECI vacío y un cryptogram que contiene la solicitud de challenge codificada):
Una vez que el titular de la tarjeta completa el challenge, el resultado final se entrega mediante el webhook del pago (consulta Notificación por webhook más abajo). Si es exitoso, el pago muestra status: SUCCEEDED / THREE_D_SECURE_VERIFIED, con un electronic_commerce_indicator y un cryptogram / CAVV completos, pares_status: Y y has_challenge: true. Si el challenge falla, el pago muestra status: DECLINED.
Resumen del flujo:
  1. La respuesta del pago regresa como PENDING / WAITING_ADDITIONAL_STEP (response_code: CHALLENGE_REQUIRED), con checkout.sdk_action_required: true y un redirect_url.
  2. El titular de la tarjeta debe completar el challenge del emisor:
    • Con el Yuno SDK: el SDK renderiza el challenge automáticamente.
    • Con un workflow que admita redirección (REDIRECT): redirige al titular de la tarjeta al redirect_url devuelto en la respuesta del pago para que pueda completar el challenge.
  3. El titular de la tarjeta completa el challenge (OTP, biometría, Out-of-Band, Decoupled, Passkeys/FIDO-SPC). Es asíncrono.
  4. Al terminar, el titular de la tarjeta regresa a tu callback_url. El resultado final de la autenticación se entrega mediante el webhook del pago (payment.purchase), o léelo con GET /v1/payments/{id}.
  5. Si es exitoso (pares_status = Y), el pago es SUCCEEDED / THREE_D_SECURE_VERIFIED y el traslado de responsabilidad = sí. Si el challenge falla, el pago es DECLINED. Hasta que llegue el resultado, el comercio ve el pago como PENDING.

Fallida o rechazada

  1. El ACS devuelve un resultado no autenticado (pares_status N / R) o la autenticación es rechazada.
  2. El pago se resuelve en DECLINED; la transacción lleva un código de respuesta de fallo como AUTHENTICATION_FAILED_THREE_D_SECURE o REJECTED_THREE_D_SECURE_REQUIRED.
  3. Sin traslado de responsabilidad: no hay una autenticación exitosa.

Recepción del resultado

Para frictionless y data-only, el resultado de three_d_secure está disponible de inmediato en la respuesta del pago (status: SUCCEEDED). Para un challenge, el resultado se entrega de forma asíncrona cuando el titular de la tarjeta termina (consulta Notificación por webhook). Como alternativa, consulta periódicamente GET /v1/payments/{id} para leer el resultado final de three_d_secure.

Notificación por webhook

El resultado de la autenticación se entrega mediante la notificación de pago estándar de Yuno: el mismo webhook que ya usas para las actualizaciones de estado del pago. No existe un webhook específico de 3DS. El evento es una notificación payment con type_event: "payment.purchase". El pago está en data.payment y el resultado de 3DS está en data.payment.transactions.payment_method.payment_method_detail.card.three_d_secure.
Para una autenticación rechazada se entrega el mismo webhook (payment.purchase); solo cambia el estado. El pago es DECLINED y la transacción lleva un código de respuesta de fallo como AUTHENTICATION_FAILED_THREE_D_SECURE o REJECTED_THREE_D_SECURE_REQUIRED.
Ejemplo: autenticación exitosa (después de un challenge completado)

Campos de la respuesta

Pruebas (sandbox)

El sandbox de 3DS usa tarjetas de prueba específicas para forzar cada resultado, y las tarjetas dependen del proveedor de 3DS configurado en la conexión.

Netcetera (predeterminado)

Titular TEST CUSTOMER, vencimiento 12/26, CVV 123:

Cybersource

Titular John Doe, vencimiento 01/26, CVV 123:

Checkout.com

Para un challenge en el sandbox, complétalo con la contraseña Checkout1!. Consulta la documentación de tarjetas de prueba 3DS de Checkout.com para ver el vencimiento, el CVV y más tarjetas.