Implementación de SCA

Consigue reservas en « SCA-compliant » con Rapid API

Tanto si utilizas Rapid API como Merchant oficial como si permites que los viajeros paguen al llegar, puedes adoptar la solución API de Rapid para generar reservas que cumplan con la normativa SCA. Nuestras API garantizan el cumplimiento de la normativa SCA mediante el uso de 3D-Secure (3DS) 2.0 en el proceso de reserva. Con 3DS 2.0 admitimos la autenticación « risk-based », que facilita las cosas a los viajeros al dar a los bancos libertad para decidir cuándo solicitarles que se autentiquen de forma segura.

La solución para 3DS 2.0 consta de tres pasos distintos:

1. Vas a añadir un iframe a la página check-out, que se utiliza para alojar el proceso de autenticación del banco emisor para el viajero. En la documentación de integración, a esto se le llama «iframe 3DS».
   >> Más información sobre los iframes

2. También incluirás una nueva biblioteca de client-side JavaScript en la página check-out, que se utiliza para recopilar datos del navegador, comunicarse con el iframe y mostrar la experiencia SCA dentro del iframe. En la documentación de integración, esto se conoce como la biblioteca 3DS Connector.

3. Rapid API aceptará los datos del pagador del banco y completará la reserva una vez que se haya realizado la autenticación segura.

Si usas JavaScript y Rapid API a la vez, el proceso de reserva con SCA ahora incluirá algunos pasos adicionales antes y después de llamar a la API de reservas. A continuación, se muestra un diagrama en el que se representa este flujo de reserva actualizado.

El resultado de cada paso en este flujo de reserva revisado contiene datos que se deben introducir en el paso siguiente. Deben transmitirse los datos entre JavaScript en el navegador y Rapid.

Detalles de los componentes de la integración

La implementación de SCA empieza en la experiencia del navegador check-out y luego se integra en el flujo de Rapid API.

Navegador

El iframe, integrado en la experiencia check-out, alberga el proceso de autenticación que se muestra al usuario y transfiere cualquier información traveler-supplied directamente a su banco; el contenido se sirve desde una URL propiedad del banco del viajero card-issuing. El iframe debería estar oculto al principio, pero con la opción de mostrarlo superpuesto sobre la página cuando se requiera una verificación de identidad tras intentar hacer una reserva.

# Biblioteca «JavaScript »

Esta biblioteca se añade a la página check-out y se invoca en el momento de la reserva para facilitar el proceso de autenticación. Las API de la biblioteca admiten las funciones que se describen a continuación.

Información sobre el dispositivo del viajero

Antes de intentar hacer una reserva, hay que recopilar información sobre el dispositivo del viajero para preparar la reserva y poder autenticarla. Esa información se envía al banco del viajero para evaluar el riesgo, decidir si se requiere la autenticación 3DS 2.0 para la transacción y asegurarse de que se muestre correctamente. De acuerdo con las especificaciones de 3DS 2.0, se recopilarán los siguientes datos del navegador del viajero: idioma, profundidad de color, altura de la pantalla, anchura de la pantalla, zona horaria, agente de usuario y si Java está activado.

Pantalla de autenticación

Tras intentar realizar una reserva, se utiliza la biblioteca para mostrar la ventana superpuesta (iframe) y cargar en ella el contenido del banco. Durante el proceso de autenticación, el contenido del banco puede recopilar información adicional sobre el dispositivo del viajero para respaldar su evaluación de riesgos. Este proceso es necesario para completar una reserva.

Rapid API

Rapid API Incluye API que funcionan junto con la biblioteca client-side JavaScript. Actualmente, las API ofrecen las funciones que se indican a continuación.

Datos del viajero y del pago

Antes de intentar hacer una reserva, Rapid API tendrá que recopilar información adicional sobre el viajero para preparar la autenticación, incluyendo datos como el punto de venta y la forma de pago. Estos datos se envían después al banco del viajero para evaluar el riesgo y decidir si se necesita una autenticación segura para la transacción. Para saber más, echa un vistazo a la API «Register Payment», que forma parte de la API «Rapid Booking».

Pago y confirmación de la reserva

Después de intentar hacer una reserva, cuando se complete el proceso de SCA en el navegador, hay que volver a llamar a Rapid API. En segundo plano, comprobaremos que la autenticación se ha realizado correctamente para que se pueda confirmar la reserva. Para más información, echa un vistazo a la sección «Pagos completos» de la API de Rapid Booking.

Flujo de reserva

A continuación te muestro un diagrama con la secuencia de llamadas a la API que hay que seguir una vez que un viajero ha iniciado una reserva. La secuencia incluye tanto llamadas a la biblioteca JavaScript como a Rapid API.

Cuando se prepara una reserva para su autenticación, puede que no siempre sea necesario. La necesidad de autenticación la decide el banco emisor de la tarjeta de crédito que se usa para el pago. Esta determinación se lleva a cabo durante la transacción y se indica en la respuesta de la API de «Crear reserva».

La API de Rapid Lodging también ofrece una función para pausar y reanudar. Esta es la secuencia de llamadas a la API que requiere esa función.

>> Más información sobre la función «Retener y reanudar» de la API de alojamiento

Si quieres más información sobre los requisitos técnicos para la experiencia 3DS 2.0, echa un vistazo al protocolo 3D Secure de EMVCo y a la especificación de funciones básicas.

>> Más información sobre 3DS 2.0

Guía de integración de 3DS 2.0

Para que SCA funcione, habrá que integrar Rapid API con una nueva biblioteca JavaScript, conocida como «3DS Connector». Ambos se usan juntos para mostrar 3DS 2.0 en la página check-out y confirmar una reserva. Esta solución es compatible tanto con el modelo de negocio « Expedia » (paga al recibir el pedido) como con el de «paga más tarde».

Nota: El servicio « » 3DS 2.0 debe estar habilitado por Rapid Partner Support en los perfiles individuales de los socios para que se pueda utilizar el proceso de reserva actualizado.

Paso 1: Llama a la API de disponibilidad

El valor del campo « sales_channel » en la solicitud de la API debe ser correcto para obtener una exención de autenticación cuando la normativa lo permita. El banco emisor de la tarjeta tiene en cuenta este valor, junto con muchos otros factores, para tomar una decisión en el momento de la reserva. Solo las herramientas para agentes están exentas de la SCA. Para especificarlo, establece el valor de sales_channel en agent_tool.

La biblioteca «JavaScript » es el primer paso del proceso de reserva. Inicializarás una sesión de pago con la API JavaScript y, a continuación, realizarás la reserva a través de la Rapid API.

>> Descubre cómo inicializar la biblioteca JavaScript

Paso 2: Llama a la API de comprobación de precios o de detalles

En el caso de la API de alojamiento, la respuesta de la API de consulta de precios para SCA incluirá un enlace a la API de registro de pagos.

Ejemplo de respuesta 3DS 2.0 para la API de alojamiento

{
    "status": "matched",
    "occupancies": {
        //...(example omitted for length)
    },
    "links": {
        "payment_session": {
            "method": "POST",
            "href": "/v3/payment-sessions?token=QldfCGlcUAVgBDRwdWXBBL"
        }
    }
}

La respuesta del punto final «Details» de las API de «Car» y «Activities» para el flujo SCA es la misma que la del flujo « non-SCA ».

Paso 3: Llama a la API «Register Payments»

Para la API de alojamiento, tendrás que hacer esta llamada específicamente. Las API de «Coche» y «Actividades» incluyen esta llamada en las API de «Detalles» o «Crear reserva». La solicitud incluirá los datos de pago que forman parte del proceso de reserva de non-SCA, además de nuevos campos que permiten que la autenticación se realice correctamente. Dos de estos campos, « encoded_browser_metadata » y « version », son los que devuelve el método «setup» de la API JavaScript.

La respuesta incluirá un payment_session_id y encoded_init_config. Estos valores se especifican como entradas en el método initSession de la biblioteca de JavaScript. El enlace de reserva que aparece en la respuesta debes usarlo después del método « initSession ».

Ejemplo de solicitud a la API de alojamiento

{
    "version": "1",
    "browser_accept_header": "*/*",
    "encoded_browser_metadata": "ZW5jb2RlZF9icm93c2VyX21ldGFkYXRh",
    "preferred_challenge_window_size": "medium",
    "merchant_url": "https://server.adomainname.net",
    "customer_account_details": {
        "authentication_method": "guest",
        "authentication_timestamp": "2027-02-12T11:59:00.000Z",
        "create_date": "2027-09-15",
        "change_date": "2027-09-17",
        "password_change_date": "2027-09-17",
        "add_card_attempts": 1,
        "account_purchases": 1
    },
    "payments": [
        {
            "type": "customer_card",
            "card_type": "VI",
            "number": "4111111111111111",
            "security_code": "123",
            "expiration_month": "08",
            "expiration_year": "2027",
            "billing_contact": {
                "given_name": "John",
                "family_name": "Smith",
                "email": "smith@example.com",
                "phone": "4875550077",
                "address": {
                    "line_1": "555 1st St",
                    "line_2": "10th Floor",
                    "line_3": "Unit 12",
                    "city": "Seattle",
                    "state_province_code": "WA",
                    "postal_code": "98121",
                    "country_code": "US"
                }
            },
            "enrollment_date": "2027-09-15"
        }
    ]
}

Ejemplo de respuesta de la API de alojamiento

{
    "payment_session_id": "76d6aaea-c1d5-11e8-a355-529269fb1459",
    "encoded_init_config": "QSBiYXNlNjQgZW5jb2RlZCBvYmplY3Qgd2hpY2ggY29udGFpbnMgY29uZmlndXJhdGlvbiBuZWVkZWQgdG8gcGVyZm9ybSBkZXZpY2UgZmluZ2VycHJpbnRpbmcgYW5kL29yIDNEUyBNZXRob2Qu",
    "links": {
        "book": {
            "method": "POST",
            "href": "/v3/itineraries?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    }
}

Ejemplo de solicitud a la API de «Car» o «Activities»

{
  "type": "customer_card",
  "number": "4111111111111111",
  "security_code": "123",
  "expiration_month": "08",
  "expiration_year": "2028",
  "billing_contact": {
    "given_name": "John",
    "family_name": "Smith",
    "email": "smith@example.com",
    "phone": {
      "country_code": "1",
      "area_code": "487",
      "number": "5550077"
    },
    "address": {
      "line_1": "555 1st St",
      "city": "Seattle",
      "state_province_code": "WA",
      "postal_code": "98121",
      "country_code": "US"
    }
  },
  "strong_customer_authentication": {
    "rapid": {
      "version": "2.0.1",
      "browser_accept_header": "*/*",
      "encoded_browser_metadata": "ZW5jb2RlZF9icm93c2VyX21ldGFkYXRh",
      "preferred_challenge_window_size": "medium",
      "merchant_url": "https://server.adomainname.net",
      "enrollment_date": "2024-05-08",
      "customer_account_details": {
        "authentication_method": "guest",
        "authentication_timestamp": "2026-02-12T11:59:00.000Z",
        "create_date": "2025-09-15",
        "change_date": "2025-09-17",
        "password_change_date": "2025-09-17",
        "add_card_attempts": 1,
        "account_purchases": 1
      }
    }
  }
}

Ejemplo de respuesta de la API de «Car» o «Activities»

{
  "payment_token": "K~IjM455rG_zUnz9LlKCw8bbLfxqk2Kb...",
  "expires": "2026-01-30T16:32:10.557287774Z",
  "payment_session_id": "ern:pay:pa:sec::5bcca93d-cdae-00b7-2cd4-d72d84cb2665",
  "encoded_init_config": "W3sicHJvdmlkZXJJZCI6IjEiLCJwYXlt..."
}

Paso 4: Llama a la API «Create Booking»

Esta solicitud no incluirá ningún campo nuevo para SCA: toda la información necesaria está incluida en el token del enlace de la reserva. En el caso de la API de alojamiento, esto aparecerá en la respuesta de la API de registro de pagos, y en el de la API de coches o actividades, en el punto final «Detalles». Si es correcta, la respuesta siempre incluirá un itinerary_id. Sin embargo, esto por sí solo no significa que la reserva esté confirmada, ya que puede que se requiera la autenticación 3DS 2.0.

Si es necesario, la respuesta también incluirá un encoded_challenge_config. El « encoded_challenge_config » y el « payment_session_id » que devuelve la API de pago de Register tendrán que pasarse como parámetros al método de desafío JavaScript.

La respuesta también incluirá un nuevo enlace a complete_payment_session (Alojamiento o Actividades) o a resume_after_payment_challenge (Coche). Este enlace se debe usar después del método «challenge» de la biblioteca JavaScript.

Si no se requiere la autenticación 3DS 2.0, la reserva queda confirmada y la respuesta incluirá enlaces a retrieve, cancel y (para las solicitudes de la API de alojamiento)resume.

Ejemplo de respuesta de la API de alojamiento

{
    "itinerary_id": "8999989898988",
    "links": {
        "complete_payment_session": {
            "method": "PUT",
            "href": "/v3/itineraries/8999989898988/payment-sessions?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    },
    "encoded_challenge_config": "ABElifsiejfacies2@033asfe="
}

Ejemplo de solicitud a la API de actividades

{
   "email": "traveler@example.com",
   "payment_token": "K~xxxxxxxxxxxxxxxxxxxx",
   "affiliate_reference_id": "AFF-REF-12345",
   "primary_traveler": {
     "name": {
       "given_name": "Jane",
       "family_name": "Doe"
     },
     "phone": {
       "country_code": "1",
       "number": "5551234567"
     },
     "ticket_id": "182552"
   }
 }

Ejemplo de respuesta de la API de actividades con desafío

{
   "itinerary_id": "9045006342737",
   "encoded_challenge_config": "<opaque challenge config from issuing bank>",
   "links": {
     "complete_payment_session": {
       "method": "PUT",
       "href": "/v2/itineraries/9045006342737/activity/payment-sessions?token=<token>"
     }
   }
 }

Paso 5: Finaliza la reserva

Esta parte del proceso de reserva tiene lugar después del método de validación JavaScript. Es necesario recibir la respuesta de la API «Complete Payment Session» (Alojamiento y actividades) o de la API «Resume After Payment Challenge» (Coche) para completar el pago e informar a Rapid API de que se ha intentado una autenticación segura, tanto si ha tenido éxito como si no.

La solicitud no incluirá ningún campo nuevo para SCA.

Si la respuesta es correcta, incluirá la información de confirmación de la reserva, como un « itinerary_id » y enlaces a retrieve, cancel y (para las solicitudes de la API de alojamiento)resume.

Ejemplo de respuesta de la API de alojamiento

{
    "itinerary_id": "8999989898988",
    "links": {
        "retrieve": {
            "method": "GET",
            "href": "/v3/itineraries/8999989898988?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    }
}

Ejemplo de respuesta de la API de actividades

{
   "itinerary_id": "9045006342737",
   "links": {
     "retrieve": {
       "method": "GET",
       "href": "/v2/itineraries/9045006342737/activity"
     }
   }
 }

Implementación de iframe y la biblioteca JavaScript

Cuando utilices el flujo de trabajo de reservas de SCA, la página check-out debe incluir un nuevo iframe y la biblioteca JavaScript. El iframe, conocido como «iframe 3DS», mostrará el proceso de autenticación mediante 3D-Secure 2.0. La biblioteca JavaScript, conocida como «biblioteca 3DS Connector», se encargará de enviar la información a los bancos emisores y de cargar el contenido de estos en el iframe.

>> Más información sobre 3DS 2.0

Añadir el iframe

El iframe 3DS debe introducirse en un contenedor que inicialmente esté oculto, pero que pueda mostrarse cuando se requiera un desafío de autenticación para procesar un pago.

El diseño del contenedor se puede personalizar para adaptarlo a la página de alojamiento. A continuación, verás un ejemplo de implementación de referencia en el que se muestra el uso de un modal de arranque.

<div id="threeDsIframeModal" class="modal" role="dialog">
    <div class="modal-dialog" role="document">
        <div class="modal-content">
            <div class="modal-body iframe-container">
                <div class="embed-responsive embed-responsive-16by9">
                    <iframe id="threeDsIframe" src="<<3DS iframe URL>>"> </iframe>
                </div>
            </div>
        </div>
    </div>
</div>

La fuente del iframe debe establecerse en uno de estos dos valores:

La URL de prueba permite realizar pruebas. Puedes limitar el contenido del iframe al entorno de pruebas durante las pruebas con este comando:

sandbox = 'allow-scripts allow-forms allow-same-origin';

Añadir la biblioteca JavaScript

La biblioteca 3DS Connector se comunica con el iframe 3DS y envía datos al banco emisor, que proporciona contenido al iframe. En el ejemplo a continuación se muestra cómo se puede añadir la biblioteca a la página de pago.

<head>
    <script src="<<3DS connector script URL>>" integrity="<<actual integrity value>>"></script>
</head>

Los valores de «source» e «integrity» del elemento «script» deben establecerse en los valores que se indican a continuación.

Nota: La URL de origen y los valores de integridad cambiarán a medida que se publiquen nuevas versiones. Las versiones más recientes no deberían entrar en conflicto con la integración actual. Se podrá seguir accediendo a las versiones anteriores del script.

Uso de 3DS y JavaScript para SCA

La biblioteca de conectores 3DS requiere el uso de promesas JavaScript. El ejemplo siguiente muestra cómo se intercambian los datos entre los métodos JavaScript y Rapid. Este ejemplo solo sirve como orientación.

// Initialize the library
let connector = new PayThreeDSConnector.ThreeDSConnector("threedsiframe", "https://static.pay.expedia.com");
RapidIntegration.priceCheck(priceCheckLink)
  .then(priceCheckResponse => {
    paymentSessionLink = priceCheckResponse.links.payment_session.href;
    // Setup an authentication session with the library
    return connector.setup({ referenceId: '1000' })
  }).then(setupResponse => {
    console.log("Setup Response: ", setupResponse);

    // Send information from setup to Rapid's Register Payments API
    return RapidIntegration.registerPayment(paymentSessionLink,
           setupResponse);
  }).then(paymentSessionResponse => {
    console.log("Register Payments Response: ", paymentSessionResponse);
    paymentSessionId = paymentSessionResponse.paymentSessionId;
    bookLink = paymentSessionResponse.links.book.href;
    if (paymentSessionResponse.encoded_init_config) {
      // If the payment session response contains an encoded_init_config
      // field, initialize an authentication session with the library
      // using information returned from Rapid's Register Payments API
      connector.initSession({
        paymentSessionId: paymentSessionId,
        encodedInitConfig: paymentSessionResponse.encodedInitConfig
      }).then(initSessionResponse => {
        console.log("Init Session Response: ", initSessionResponse);
        // Then create a booking with Rapid's Book API
        return RapidIntegration.createBooking(bookLink,
               paymentSessionId);
      })
    } else {
      // Otherwise, create a booking with Rapid's Book API directly
      return RapidIntegration.createBooking(bookLink, paymentSessionId);
    }
  }).then(createBookingResponse => {
    console.log("Create Booking Response: ", createBookingResponse);
    itineraryId = createBookingResponse.itinerary_id;
    if (createBookingResponse.encoded_challenge_config) {
      // If the Create Booking API contains an encoded_challenge_config field,
      // display the authentication challenge window
      $('#threeDsIframeModal').modal('show');
      completePaymentSessionLink = createBookingResponse.links.complete_payment_session.href;
      // Perform the challenge using the information returned from Rapid's Register Payments API
      // and Create Booking API
      connector.challenge({
        paymentSessionId: paymentSessionId,
        encodedChallengeConfig: createBookingResponse.encodedChallengeConfig
      }).then(challengeResponse => {
        console.log("Challenge Response: ", challengeResponse);
        // Complete a booking with Rapid's Complete Payment Session API
        return RapidIntegration.completePaymentSession(completePaymentSessionLink, itineraryId);
      }).then(completePaymentSessionResponse => {
        console.log("Complete Payment Session Response: ", completePaymentSessionResponse);
        return completePaymentSessionResponse;
      }).finally(() => {
        // Close the authentication challenge window
        $('#threeDsIframeModal').modal('hide');
      });
    } else {
      return createBookingResponse;
    }
  }).then(bookingResponse => {
    ...
  });

Nota: Las referencias a la clase RapidIntegration no forman parte de la biblioteca del conector 3DS. El objetivo es mostrar un contenedor que admite la transferencia de información a las API. El ejemplo también usa valores fijos para parámetros que deberían determinarse en tiempo de ejecución, como referenceId.

Check-out directrices de diseño de páginas

Las marcas de tarjetas que admiten la autenticación 3DS pueden exigir que sus logotipos y su imagen de marca se muestren siguiendo sus directrices.

Nota: Se irán incluyendo los logotipos y las instrucciones de otras marcas de tarjetas a medida que estén disponibles.

Documentación de la biblioteca de JavaScript 3DS Connector

>> Más información sobre SCA

>> Descubre cómo probar tu implementación de SCA