/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).

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:- En la ruta: agrega un grupo de condiciones por cada conexión que coincida con una clave de metadata. Por ejemplo,
3ds_connection = standardpara una conexión y un valor distinto para la otra. Cada valor dirige el tráfico a la conexión que quieras. - En las solicitudes: agrega una entrada
metadataque 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.
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 unthree_d_secure_setup_id, el cual luego se referencia en el pago.
- 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 alcollect_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
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.
- 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.
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).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, concheckout.sdk_action_required: truey unredirect_url(se resuelve más tarde; consulta Notificación por webhook). - Autenticación fallida o rechazada →
status: DECLINED.
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
Objetothree_d_secure (dentro del detalle de la tarjeta):
Ver la respuesta completa del pago
Ver la respuesta completa del pago
- Se envía la solicitud de autenticación al ACS.
- El ACS autentica mediante análisis de riesgo, sin interacción del usuario.
- Devuelve los datos completos (criptograma, ECI, dsTransID, versión) con
pares_status = Y; el pago esSUCCEEDED/THREE_D_SECURE_VERIFIED. - El resultado está disponible en la respuesta del pago. Traslado de responsabilidad = sí.
Data Only
Objetothree_d_secure (dentro del detalle de la tarjeta):
Ver la respuesta completa del pago
Ver la respuesta completa del pago
- 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.
- El flujo continúa como frictionless y devuelve un resultado (
SUCCEEDED/THREE_D_SECURE_VERIFIED,pares_status = I). - Traslado de responsabilidad = NO: el comercio conserva la responsabilidad por fraude. Normalmente ECI 04.
Challenge
El pago regresa comoPENDING 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):
Ver la respuesta completa del pago
Ver la respuesta completa del pago
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.- La respuesta del pago regresa como
PENDING/WAITING_ADDITIONAL_STEP(response_code: CHALLENGE_REQUIRED), concheckout.sdk_action_required: truey unredirect_url. - 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 alredirect_urldevuelto en la respuesta del pago para que pueda completar el challenge.
- El titular de la tarjeta completa el challenge (OTP, biometría, Out-of-Band, Decoupled, Passkeys/FIDO-SPC). Es asíncrono.
- 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 conGET /v1/payments/{id}. - Si es exitoso (
pares_status = Y), el pago esSUCCEEDED/THREE_D_SECURE_VERIFIEDy el traslado de responsabilidad = sí. Si el challenge falla, el pago esDECLINED. Hasta que llegue el resultado, el comercio ve el pago comoPENDING.
Fallida o rechazada
- El ACS devuelve un resultado no autenticado (
pares_status N/R) o la autenticación es rechazada. - El pago se resuelve en
DECLINED; la transacción lleva un código de respuesta de fallo comoAUTHENTICATION_FAILED_THREE_D_SECUREoREJECTED_THREE_D_SECURE_REQUIRED. - Sin traslado de responsabilidad: no hay una autenticación exitosa.
Recepción del resultado
Para frictionless y data-only, el resultado dethree_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ónpayment 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.Ver el payload del webhook
Ver el payload del webhook
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)
TitularTEST CUSTOMER, vencimiento 12/26, CVV 123:
Cybersource
TitularJohn 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.