Implementação do SCA

Gere reservas SCA-compliant com Rapid API

Quer você utilize Rapid API como o Merchant de registro ou permita que os viajantes paguem na chegada, você pode adotar a solução de API da Rapid para gerar reservas que estejam em conformidade com as regulamentações da SCA. Nossas APIs oferecem suporte à conformidade com a SCA (Autenticação Forte do Cliente) por meio do uso do 3D-Secure (3DS) 2.0 no fluxo de reservas. Com o 3DS 2.0, oferecemos suporte à autenticação risk-based, que reduz o atrito com os viajantes, concedendo aos bancos a discricionariedade de decidir quando solicitar a autenticação segura dos viajantes.

A solução para o 3DS 2.0 é composta por três etapas distintas:

1. Você adicionará um iframe à página check-out, que é usada para hospedar a experiência de autenticação do banco emissor para o viajante. Na documentação de integração, isso é referido como iframe 3DS.
   >> Saiba mais sobre iframes

2. Você também incluirá uma nova biblioteca client-side na página check-out, que é usada para coletar dados do navegador, comunicar-se com o iframe e exibir a experiência SCA dentro do iframe. Na documentação de integração, isso é referido como a Biblioteca de Conectores 3DS.

3. Rapid API aceitará as informações do pagador junto ao banco e concluirá a reserva após a autenticação segura ser concluída.

Ao usar JavaScript e Rapid API em conjunto, o fluxo de reservas com SCA agora incluirá algumas etapas adicionais antes e depois da chamada da API de reservas. O diagrama abaixo descreve esse fluxo de reservas atualizado.

Durante cada etapa do fluxo de reservas revisado, o resultado de uma etapa contém dados que vão ser inseridos na próxima etapa. Os dados precisam ser passados entre o JavaScript no navegador e a Rapid.

Detalhes do componente de integração

A implementação do SCA começa na experiência do navegador check-out e é então integrada ao fluxo Rapid API.

Navegador

O iframe, inserido na experiência check-out, hospeda a experiência de autenticação que é exibida ao usuário e transfere qualquer informação traveler-supplied diretamente para o seu banco; o conteúdo é servido a partir de um URL pertencente ao banco card-issuing do viajante. O iframe deve estar inicialmente oculto, com a possibilidade de ser sobreposto à página quando for necessária uma autenticação após uma tentativa de reserva.

Biblioteca JavaScript

Esta biblioteca é adicionada à página check-out e é invocada no momento da reserva para dar suporte ao processo de autenticação. As APIs da biblioteca suportam as funcionalidades descritas abaixo.

Informações sobre dispositivos de viagem

Antes de uma tentativa de reserva, é necessário coletar informações sobre o dispositivo do viajante para preparar a reserva para autenticação. Essas informações são enviadas ao banco do viajante para avaliar o risco, decidir se a autenticação 3DS 2.0 é necessária para a transação e garantir que ela seja exibida corretamente. De acordo com as especificações do 3DS 2.0, os seguintes dados serão coletados do navegador do viajante: idioma, profundidade de cor, altura da tela, largura da tela, fuso horário, agente do usuário e se o Java está habilitado.

Exibição de autenticação

Após uma tentativa de reserva, a biblioteca é usada para exibir a sobreposição do iframe e carregar o conteúdo do banco nela. Durante o processo de autenticação, o sistema do banco pode coletar informações adicionais sobre o dispositivo do viajante para auxiliar na avaliação de risco. Este processo é necessário para concluir uma reserva.

Rapid API

Rapid API inclui APIs que funcionam em conjunto com a biblioteca client-side JavaScript. As APIs agora são compatíveis com os recursos descritos abaixo.

Detalhes do viajante e do pagamento

Antes de tentar efetuar uma reserva, o sistema Rapid API precisará coletar informações adicionais sobre o viajante para se preparar para a autenticação, incluindo informações como o ponto de venda e o método de pagamento. Esses dados são posteriormente enviados ao banco do viajante para avaliação de risco e para que seja decidido se a autenticação segura é necessária para a transação. Saiba mais consultando a API de Pagamento de Cadastro, que faz parte da API de Reserva Rápida.

Pagamento e confirmação da reserva

Após uma tentativa de reserva, quando o processo SCA for concluído no navegador, Rapid API deverá ser invocado mais uma vez. Nos bastidores, confirmaremos se a autenticação foi bem-sucedida para que a reserva possa ser confirmada. Saiba mais consultando a seção Concluir Pagamentos na API de Reservas Rápidas.

Fluxo de reserva

A seguir, encontra-se um diagrama da sequência de chamadas à API necessária após uma reserva ser iniciada por um viajante. A sequência envolve chamadas tanto para a biblioteca JavaScript quanto para a biblioteca #Rapid API.

Ao preparar uma reserva para autenticação, nem sempre será necessário apresentá-la. A necessidade de autenticação é determinada pelo banco emissor do cartão de crédito utilizado para o pagamento. Essa determinação ocorre durante a transação e é indicada na resposta da API de Criação de Reserva.

A API Rapid Lodging também oferece uma funcionalidade de reserva e retomada. Aqui está a sequência de chamadas da API que esse recurso requer.

>> Saiba mais sobre a API de hospedagem, retenção e retomada

Para obter mais informações sobre os requisitos técnicos da experiência 3DS 2.0, consulte a especificação do protocolo 3D Secure e das funções principais da EMVCo.

>> Leia mais sobre o 3DS 2.0

Guia de integração do 3DS 2.0

Para dar suporte ao SCA, será necessário integrar Rapid API com uma nova biblioteca JavaScript, chamada de Conector 3DS. Os dois são usados ​​em conjunto para apresentar o 3DS 2.0 na página check-out e confirmar uma reserva. Esta solução é compatível com os modelos de negócio de coleta e pagamento posterior da Expedia.

Nota: O 3DS 2.0 deve ser ativado pelo Suporte Rápido a Parceiros para perfis de parceiros individuais para permitir o fluxo de reserva revisado.

Passo 1: Chame a API de Disponibilidade

O valor do campo sales_channel na solicitação da API deve ser preciso para obter uma isenção de autenticação quando permitido pelos regulamentos. Esse valor, juntamente com muitos outros fatores, é analisado pelo banco emissor do cartão para que ele tome sua decisão durante a reserva. Somente as ferramentas de agente estão isentas da SCA. Para especificar isso, defina o valor de sales_channel como agent_tool.

A biblioteca JavaScript é um precursor das demais etapas do processo de reserva. Você irá inicializar uma sessão de pagamento com a API JavaScript e, em seguida, reservar através da API Rapid API.

>> Aprenda como inicializar a biblioteca JavaScript

Etapa 2: Chame a API de Verificação de Preços ou Detalhes.

Para a API de Hospedagem, a resposta da API de Verificação de Preços para SCA incluirá um link para a API de Pagamentos de Registro.

Exemplo de resposta 3DS 2.0 para a API de Hospedagem

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

A resposta do endpoint Details das APIs Car e Activities para o fluxo SCA é a mesma que a do fluxo non-SCA.

Etapa 3: Chame a API de Pagamentos Registrados

Para a API de Hospedagem, você precisará fazer essa chamada especificamente. As APIs de Carros e Atividades incorporam essa chamada nas APIs de Detalhes ou Criação de Reserva. A solicitação incluirá detalhes de pagamento que fazem parte do fluxo de reserva do non-SCA e novos campos que permitem uma autenticação bem-sucedida. Dois desses campos, encoded_browser_metadata e version, são retornados pelo método setup da API JavaScript.

A resposta vai incluir a payment_session_id e a encoded_init_config. Elas são inseridas no método initSession da biblioteca JavaScript. O link de reserva incluído na resposta deve ser usado após o método initSession.

Exemplo de solicitação à API de hospedagem

{
    "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"
        }
    ]
}

Exemplo de resposta da API de hospedagem

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

Exemplo de solicitação de API para Carros ou Atividades

{
  "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
      }
    }
  }
}

Exemplo de resposta da API de Carros ou Atividades

{
  "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..."
}

Etapa 4: Chame a API de Criação de Reservas

Esta solicitação não incluirá nenhum campo novo para SCA — todas as informações necessárias estão contidas no token do link de reserva. Para a API de Hospedagem, essa informação estará na resposta da API de Pagamento de Registro, e para a API de Carros ou Atividades, no endpoint Detalhes. A resposta, se bem-sucedida, sempre vai conter um itinerary_id. No entanto, isso por si só não indica que uma reserva está confirmada, pois a autenticação 3DS 2.0 pode ser necessária.

Se necessário, a resposta também incluirá um encoded_challenge_config. Os valores encoded_challenge_config e payment_session_id retornados pela API Register Payment precisarão ser passados ​​como parâmetros para o método de desafio JavaScript.

A resposta também incluirá um novo link para complete_payment_session (Alojamento ou Atividades) ou resume_after_payment_challenge (Carro). Este link deve ser usado após o método de desafio da biblioteca JavaScript.

Se a autenticação 3DS 2.0 não for necessária, a reserva será confirmada e a resposta incluirá links para retrieve, cancel e (para solicitações da API de hospedagem)resume.

Exemplo de resposta da API de hospedagem

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

Exemplo de solicitação da API de atividades

{
   "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"
   }
 }

Exemplo de resposta da API de atividades com desafio

{
   "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>"
     }
   }
 }

Etapa 5: Conclua a reserva

Esta parte do fluxo de reserva ocorre após o método de desafio JavaScript. A resposta da API Complete Payment Session (Hospedagem e Atividades) ou da API Resume After Payment Challenge (Carro) é necessária para concluir o pagamento e informar ao Rapid API que uma tentativa de autenticação segura foi realizada, com sucesso ou não.

A solicitação não incluirá nenhum campo novo para SCA.

A resposta, se bem-sucedida, conterá informações de confirmação da reserva, incluindo um itinerary_id e links para retrieve, cancel e (para solicitações da API de hospedagem)resume.

Exemplo de resposta da API de hospedagem

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

Exemplo de resposta da API de atividades

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

Implementação de iframe e da biblioteca JavaScript

Ao usar o fluxo de trabalho de reserva SCA, a página check-out deve incluir um novo iframe e a biblioteca JavaScript. O iframe, denominado iframe 3DS, exibirá a experiência de autenticação usando o 3D-Secure 2.0. A biblioteca JavaScript, denominada Biblioteca Conectora 3DS, dará suporte à transferência de informações para os bancos emissores e carregará o conteúdo dos bancos no iframe.

>> Saiba mais sobre o 3DS 2.0

Adicionando o iframe

O iframe 3DS deve ser encapsulado em um contêiner a princípio oculto, mas que pode ser exibido quando uma autenticação for necessária para processar um pagamento.

O design do contêiner pode ser personalizado para se adequar à página de hospedagem. Abaixo vemos um exemplo de implementação destinado apenas para fins de orientação usando um modal de bootstrap.

<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>

A origem do iframe deve ser definida para um dos dois valores:

O URL de teste suporta testes. Você pode restringir o conteúdo do iframe ao ambiente de teste (sandbox) com este comando:

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

Adicionando a biblioteca JavaScript

A biblioteca de conectores 3DS se comunica com o iframe 3DS e envia dados ao banco emissor, que fornece o conteúdo do iframe. Abaixo vemos um exemplo de como adicionar a biblioteca à página de pagamento.

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

Os valores de origem e integridade do elemento de script devem ser definidos com os valores abaixo.

Nota: O URL de origem e os valores de integridade serão alterados conforme as versões futuras forem disponibilizadas para adoção. Versões mais recentes não devem interromper a integração existente. Versões mais antigas do script ainda vão estar acessíveis.

Usando 3DS e JavaScript para SCA

A biblioteca de conectores 3DS requer o uso de promessas JavaScript. O exemplo abaixo demonstra como os dados são trocados entre os métodos JavaScript e o Rapid. Este exemplo serve apenas como orientação.

// 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: As referências à classe RapidIntegration não fazem parte da biblioteca de conectores 3DS. Elas servem para demonstrar um wrapper que permite a transferência de informações para as APIs. O exemplo também usa valores estáticos para parâmetros que devem ser determinados em tempo de execução, como referenceId.

Diretrizes de design da página Check-out

As bandeiras de cartões que suportam autenticação 3DS podem exigir que seus logotipos e marcas sejam exibidos de acordo com suas diretrizes.

Nota: Logotipos e orientações para outras marcas de cartões serão incluídos assim que estiverem disponíveis.

Documentação da biblioteca JavaScript de conectores 3DS

>> Saiba mais sobre a SCA

>> Saiba mais sobre como testar sua implementação de SCA