SCAの実装
SCA-compliantの予約を以下で生成しますRapid API
Rapid APIを正式な販売業者としてご利用になる場合でも、旅行者が到着時に支払いを済ませる方式を採用する場合でも、RapidのAPIソリューションを導入することで、SCA規制に準拠した予約を作成することができます。当社のAPIは、予約フローにおいて3D-Secure（3DS）2.0を採用することで、SCAへの準拠をサポートしています。3DS 2.0では、risk-based認証に対応しており、銀行が旅行者に対 して安全な認証を求めるタイミングを裁量で決定できるようになるため、旅行者の利便性が向上します。
3DS 2.0の解決策は、以下の3つの明確なステップで構成されています：
check-outページにiframeを追加し、そこで旅行者向けの発行銀行による認証プロセスをホストします。統合に関するドキュメントでは、これは「3DS iframe」と呼ばれています。
>> iframeについて詳しくはこちらまた、check-outページに、新しいclient-side JavaScriptラ イブラリを追加してください。このライブラリは、ブラウザデータの収集、iframeとの通信、およびiframe内でのSCA体験の表示に使用されます。統合に関するドキュメントでは、これは「3DSコネクタライブラリ」と呼ばれています。
Rapid API銀行の支払者情報を受け付け、安全な認証が完了した後、予約を確定いたします。
JavaScriptとRapid APIを併用する場合、SCAを使用した予約フローでは、Booking APIが呼び出される前後に、いくつかの追加手順が追加されるようになりました。下の図に、この新しい予約フローを示します。
改訂された 予約フローの各ステップでは、1 つのステップの出力に、次のステップの入力として使われるデータが含まれます。データは、ブラウザ上の JavaScript と Rapid の間で受け渡す必要があります。
統合コンポーネントの詳細
SCAの実装は、check-outのブラウザ環境から開始され、その後、Rapid APIのフローへと引き継がれます。
ブラウザ
check-outのエクスペリエンス内に配置されたiframeは、ユーザーに表示される認証エクスペリエンスをホストし、traveler-suppliedの情報をユーザーの銀行に直接転送します。コンテンツは、旅行者のcard-issuingの銀行が所有するURLから提供されます。iframeは当初非表示にしておくべきですが、予約の試行後に認証の要求があった場合には、ページの上に重ねて表示できるようにする必要があります。
JavaScriptライブラリ
このライブラリは「check-out」ページに追加されており、認証プロセスをサポートするために予約時に 呼び出されます。このライブラリのAPIは、以下に説明する機能をサポートしています。
トラベラーのデバイス情報
予約を試みる前に、認証のための予約準備を行うため、旅行者の端末に関する情報を収集する必要があります。その情報は、リスクを評価し、その取引に3DS 2.0認証が必要かどうかを判断し、正しく表示されるようにするため、旅行者の銀行に送信されます。3DS 2.0仕様に基づき、利用者のブラウザから以下のデータが収集されます：言語、色深度、画面の高さ、画面の幅、タイムゾーン、ユーザーエージェント、およびJavaが有効かどうか。
認証画面
予約の試行後、ライブラリを使用してiframeオーバーレイを表示し、そこに銀行のコンテンツを読み込みます。認証プロセス中、銀行側のシステムは、リスク評価を行うために、旅行者の端末に関する追加情報を収集する場合があります。この手続きは、ご予約を完了するために必要です。
Rapid API
Rapid API client-side # ライブラリと連携して動作するAPIが含まれています。JavaScript これらの API は、以下で解説する機能をサポートしています。
旅行者およびお支払いに関する詳細
予約手続きを行う前に、Rapid APIでは、本人確認の準備として、販売拠点や支払い方法など、旅行者に関する追加情報を収集する必要があります。このデータはその後、旅行者の銀行に送信され、リスクを評価し、その取引に安全な認証が必要かどうかを判断するために利用されます。Rapid Booking APIの一部である「Register Payment API」をご確認いただき、詳細をご確認ください。
お支払いとご予約の確認
予約を試みた後、ブラウザでSCAプロセスが完了したら、Rapid APIをもう一度呼び出す必要があります。バックエンドでは、認証が成功したことを確認し、ご予約を確定いたします。詳細については、Rapid Booking APIの「Complete Payments」セクションをご確認ください。
予約フロー
以下は、旅行者による予約の開始後に必要なAPI呼び出しの順序を示す図です。このシーケンスでは、JavaScriptライブラリへの呼び出しと、Rapid API.
予約が認証の準備段階にある場合、必ずしも認証が必要とは限りません。認証の必要性は、お支払いに使用されたクレジットカードの発行銀行によって決定されます。この判定はトランザクション中に実行され、Create Booking APIのレスポンスに示されます。
Rapid Lodging APIには、予約の保留および再開機能も備わっています。その機能に必要なAPI呼び出しの順序は以下の通りです。
>>「Lodging API」の「保留」と「再開」について詳しくはこちら
3DS 2.0の技術要件に関する詳細については、EMVCoの「3D Secureプロトコルおよびコア機能仕様書」をご参照ください。
3DS 2.0統合ガイド
SCAをサポートするには、Rapid APIを、3DSコネクタと呼ばれる新しいJavaScriptライブラリと統合する必要があります。この2つを組み合わせて使用することで、「check-out」ページで3DS 2.0を表示し、予約を確定することができます。このソリューションは、Expedia Collect (事前決済) および「後払い」というビジネスモデルの両方をサポートしています。
注：改訂された予約フローを利用するには、個々のパートナープロファイルについて、Rapid Partner Supportにより「 3DS 2.0」が有効化されている必要があります。
手順1：Availability APIを呼び出します
規制により認証の免除が認められる場合、APIリクエスト内の「sales_channel」フィールドの値は正確でなければなりません。この数値は、その他の多くの要素とともに、カード発行銀行によって審査され、予約時の判断材料となります。SCAの適用除外となるのは、エージェントツールのみです。これを指定するには、 sales_channel の値を agent_tool に設定します。
JavaScriptライブラリは、予約プロセスの残りの手順に向けた準備段階となります。JavaScript APIを使用して決済セッションを初期化し、その後、Rapid API.
>> JavaScriptライブラリの初期化方法について学びましょう
ステップ2：Price CheckまたはDetails APIを呼び出します
Lodging APIについては、SCAに関するPrice Check APIの応答に、Register Payments APIへのリンクが含まれます。
Lodging APIに対する3DS 2.0レスポンスの例
{
"status": "matched",
"occupancies": {
//...(example omitted for length)
},
"links": {
"payment_session": {
"method": "POST",
"href": "/v3/payment-sessions?token=QldfCGlcUAVgBDRwdWXBBL"
}
}
}SCAフローにおけるCarおよびActivities APIのDetailsエンドポイントのレスポンスは、non-SCAフローのそれと同じです。
ステップ3：Register Payments APIを呼び出します
Lodging APIをご利用になる場合は、この呼び出しを特に実行する必要があります。Car APIおよびActivities APIでは、この呼び出しがDetails APIまたはCreate Booking APIに組み込まれています。このリクエストには、non-SCAの予約フローの一部である支払い詳細に加え、認証の成功をサポートする新しいフィールドが含まれます。これらのフィールドのうち、「encoded_browser_metadata」と「version」の2つは、JavaScript APIのsetupメソッドから返されます。
レスポンスには payment_session_id と encoded_init_config が含まれます。これらは、JavaScript ライブラリーの initSession メソッドへの入力として指定します。レスポンスに含まれる予約リンクは、initSession メソッドの実行後にご利用ください。
宿泊APIのリクエスト例
{
"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"
}
]
}宿泊APIの応答例
{
"payment_session_id": "76d6aaea-c1d5-11e8-a355-529269fb1459",
"encoded_init_config": "QSBiYXNlNjQgZW5jb2RlZCBvYmplY3Qgd2hpY2ggY29udGFpbnMgY29uZmlndXJhdGlvbiBuZWVkZWQgdG8gcGVyZm9ybSBkZXZpY2UgZmluZ2VycHJpbnRpbmcgYW5kL29yIDNEUyBNZXRob2Qu",
"links": {
"book": {
"method": "POST",
"href": "/v3/itineraries?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
}
}
}Car APIまたはActivities APIのリクエスト例
{
"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
}
}
}
}Car APIまたはActivities APIの応答例
{
"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..."
}ステップ4：予約作成APIを呼び出す
このリクエストには、SCA用の新しいフィールドは一切含まれません。必要な情報はすべて、予約リンクのトークン内に含まれています。Lodging APIの場合、これはRegister Payment APIのレスポンス内に含まれており、Car APIまたはActivities APIの場合、Detailsエンドポイント内に含まれています。成功した場合、レスポンスには常に itinerary_id が含まれます。ただし、これだけでは予約が確定したとは限りません。3DS 2.0による認証が必要となる場合があるためです。
必要に応じて、応答には.も含まれますencoded_challenge_config。Register Payment APIから返される「encoded_challenge_config」および「payment_session_id」は、JavaScriptのチャレンジメソッドのパラメータとして渡す必要があります。
また、この返信には、complete_payment_session（宿泊施設またはアクティビティ）またはresume_after_payment_challenge（車）への新しいリンクも含まれます。このリンクは、JavaScriptライブラリのchallengeメソッドの後に使用してください。
3DS 2.0認証が必要ない場合、予約は確定され、応答にはretrieve、cancel、および（Lodging APIリクエストの場合）resume へのリンクが含まれます。
宿泊APIの応答例
{
"itinerary_id": "8999989898988",
"links": {
"complete_payment_session": {
"method": "PUT",
"href": "/v3/itineraries/8999989898988/payment-sessions?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
}
},
"encoded_challenge_config": "ABElifsiejfacies2@033asfe="
}APIリクエストの例
{
"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"
}
}チャレンジを含む「Example Activities」APIのレスポンス
{
"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>"
}
}
}ステップ5：予約を完了する
予約フローのこの部分は、JavaScriptチャレンジ手法の後に実行されます。支払いを完了し、Rapid APIに対して、セキュアな認証が試行されたこと（成功したか否かを問わず）を通知するには、「Complete Payment Session API（宿泊・アクティビティ）」または「Resume After Payment Challenge API（自動車）」のレスポンスが必要です。
このリクエストには、SCA用の新しいフィールドは含まれません。
このリクエストが成功した場合、レスポンスには、itinerary_id や、retrieve、cancel、および（Lodging APIリクエストの場合）へのリンクなど、予約の確認情報が含まれますresume。
宿泊APIの応答例
{
"itinerary_id": "8999989898988",
"links": {
"retrieve": {
"method": "GET",
"href": "/v3/itineraries/8999989898988?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
}
}
}アクティビティAPIの応答例
{
"itinerary_id": "9045006342737",
"links": {
"retrieve": {
"method": "GET",
"href": "/v2/itineraries/9045006342737/activity"
}
}
}IframeおよびJavaScriptライブラリの実装
SCA予約ワークフローをご利用の際は、check-outページに、新しいiframeおよびJavaScriptライブラリを含める必要があります。「3DS iframe」と呼ばれるこのiframeでは、3D-Secure 2.0を使用した認証画面が表示されます。「3DS Connector Library」と呼ばれるJavaScriptライブラリは、発行銀行への情報転送をサポートし、銀行のコンテンツをiframeに読み込みます。
iframeの追加
3DS iframe はコンテナー内にラップし、コンテナーを当初は非表示にして、支払いの処理でチャレンジ認証を求められたら表示できるようにします。
コンテナーのデザインは、ホスティングページにあわせてカスタマイズできます。ご参考までに、ブートストラップ モーダルを使った実装例を以下に示します。
<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>iframe の src には、次の 2 つの値のいずれかを設定する必要があります。
| URL タイプ | URL | 備考 |
|---|---|---|
| 本番環境 | https://static.pay.expedia.com/3ds/threeDsIframe.html | 生産認証に対応しています |
| テスト用サンドボックス | https://static.pay.expedia.com/3ds/sandboxThreeDsIframe.html | 認証のテストに対応しています |
このテスト用URLでは、テストを行うことができます。このコマンドを使用すると、テスト中にiframeのコンテンツをサンドボックス内に制限することができます：
sandbox = 'allow-scripts allow-forms allow-same-origin';JavaScriptライブラリの追加
3DS connector ライブラリーは 3DS iframe と通信し、iframe コンテンツを提供するカード発行銀行にデータを送信します。以下のサンプルに、ライブラリーをお支払いページに追加する方法の例を示します。
<head>
<script src="<<3DS connector script URL>>" integrity="<<actual integrity value>>"></script>
</head>script要素の「source」および「integrity」の値は、以下の値に設定する必要があります。
| ライブラリーのバージョン | 属性 | 値 |
|---|---|---|
| 1.3.39 | src | https://static.pay.expedia.com/3ds/1.3.39/pay-3ds-js-libs-connector.min.js |
| integrity | sha384-par0I4Q5cfljwzqw2mAggM4dKdYzGyj4uZiL4cMviGjI3qVzEgWGuZ2075mYutbT | |
| 1.3.65 | src | https://static.pay.expedia.com/3ds/1.3.65/pay-3ds-js-libs-connector.min.js |
| integrity | sha384-gYopPw6xE5DZwnZXGavkwnvs3NkDOobnHqjroUnSHpGXvs/J9xjHX/8aGzKtSgWI | |
| 2.0.1 | src | https://static.pay.expedia.com/3ds/2.0.1/pay-3ds-js-libs-connector.min.js |
| integrity | sha384-1ntftSOl8ZSqJ/m7qqxXTNGOx3JLbF7Uw5YX8i/ageTjgmTnUMZ3ROpxxMiUkYma |
注： 今後のバージョンが利用可能になるにつれて、ソースURLおよび整合性値は変更されます 。バージョン更新は、既存の統合に支障が生じないように行われる予定です。古いバージョンのスクリプトには、引き続きアクセスできます。
SCAでの3DSおよびJavaScriptの利用
3DSコネクタライブラリでは、JavaScriptプロミスを使用する必要があります。以下のサンプルは、JavaScriptメソッドとRapidの間でデータがどのようにやり取りされるかを示しています。この例はあくまで参考としてご活用ください。
// 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 => {
...
});注：RapidIntegration クラスに関する記述は、3DSコネクタライブラリの一部ではありません。これらの参照は、API への情報転送をサポートするラッパーを例示するためのものです。また、このサンプルでは、referenceId のように、実行時に決定されるべきパラメータに対して静的な値が使用されています。
Check-outページデザインのガイドライン
3DS認証に対応しているカードブランドによっては、そのガイドラインに従ってロゴやブランド名を表示することが求められる場合が あります。
| カードブランド | 認証ブランディング | ブランディングサイト |
|---|---|---|
| Mastercard | Mastercard Identity Check | マスターカードのブランドガイドライン |
| Visa | Visa Secure | Visaのブランドガイドライン |
注： のロゴおよびその他のカードブランドのガイドラインについては、入手可能になり次第、掲載いたします。