This is an auto-generated translation

遵守強客戶驗證法規

瞭解線上信用卡付款的認證規範。

簡介

監管機構與信用卡網絡正推出新規定,以強化線上支付的安全性,並保護消費者免受詐騙侵害。其中許多法規都包含了針對線上支付必須採用強客戶認證 (SCA) 的要求。

  • 歐洲:《修訂版支付服務指令》(PSD2) 要求線上支付交易必須採用增強型驗證(SCA),但特定豁免情況或 out-of-scope 案例適用時除外。
  • 日本: 日本的 SCA 強制規定要求線上信用卡交易必須採用 3D Secure (3DS) 驗證機制,但某些交易類型可獲豁免。

3D Secure 2 (3DS 2.0) 是由 EMVCo 與信用卡支付處理產業共同開發的技術方案,旨在確保合規性同時平衡安全性與流暢的結帳體驗。此技術為 Rapid API 所採用的解決方案,用以符合加強型客戶驗證 (SCA) 規範。

本頁面說明受支援的 Rapid API 支付類型受到的影響,以及您在為旅客提供服務時可採取哪些行動以符合規範。

合規要求

在需要加強客戶驗證 (SCA) 的國家啟用合規交易的步驟,將因實際收款商戶的身份及款項支付方式而有所不同。Rapid API.

當貴機構擔任記錄商戶時

Expedia Affiliate Collect

使用 Expedia Affiliate Collect 的預訂不受加強型驗證 (SCA) 法規影響。要達到合規要求,無需對 Rapid API 的付款流程或 API 整合進行任何變更。

然而,若您身為記錄在案的商家,並向旅客收取信用卡費用 (金融卡) 或其他屬於加強型驗證規範範圍內的付款方式,則可能受到相關法規影響。該規範很可能要求在支付流程中採用 3DS 2.0 作為「驗證客戶身份」(SCA-compliant)的解決方案。請聯繫您的支付處理商,以瞭解其協助商家達成加強型驗證合規性並避免交易失敗的能力。

公司名片

若貴公司為記錄商戶,並使用在實施 SCA 強制要求的國家發行的信用卡或金融卡支付給 Rapid API,則下列卡種可豁免 SCA 驗證要求:

  • 一次性虛擬卡
  • 公司卡是發給貴公司的,而非個人

若您不傾向使用所列的 SCA-exempt 信用卡,您的機構可直接向發卡銀行申請豁免。若獲准豁免,該卡交易將無需驗證,惟可能需透過 3DS 2.0 進行「one-time」線上驗證。此「one-time」要求可能因銀行而異。請注意,從申請到通過豁免可能需要很長時間;此外,若發生任何詐騙交易,銀行可能會要求貴公司負責。

當 Rapid API 為記錄商戶時

若貴公司透過將旅客卡片寄送至 Rapid API 作為記錄商戶,則可能受到相關法規影響。當旅客透過線上管道預訂行程 (非經由實體旅行社代理) 時,相關法規要求支付交易必須由旅客透過加強型驗證 (SCA) 進行身份驗證。此項要求的 SCA-compliant 流程是在付款過程中使用 3DS 2.0。若貴機構希望將 Rapid API 作為記錄商戶,處理任何在實施 SCA 強制要求的國家所發行的信用卡或簽帳卡,則需採用——我們為 SCA 所提供的解決方案

透過零售代理商或客服中心代理商登記的交易,可豁免適用加強型客戶驗證 (SCA) 要求。只要註明預訂是由專人協助辦理,交易就符合規定。如有需要,可在「供應情況 API」的 sales_channel 欄位加註。

當旅宿為記錄商戶時

若貴公司使用旅宿收集服務,則可能受到相關法規影響。在某些情況下,旅宿可能會嘗試在旅客不在場時扣款,例如收取「未現身」費用或押金。在扣款前未執行 3DS 2.0 驗證的交易,均不屬於 SCA-compliant (無卡交易)。若貴機構欲為使用任何由具 SCA 強制要求國家所發行之信用卡或簽帳卡的旅客採用旅宿收費方案,則需採用我們的 SCA 解決方案——

Rapid API 解決方案

運作方式

若您採用 Rapid API 作為登記商戶,或使用旅宿透過旅客卡進行收款,即可採用 Rapid 的 API 解決方案,生成符合 SCA 法規的預訂記錄。我們的 API 透過在預訂流程中採用 3DS 2.0 技術,支援 SCA 合規要求。透過 3DS 2.0,我們支援「risk-based」驗證機制,此機制賦予銀行自主判斷權,可靈活決定何時要求旅客進行安全驗證,從而降低旅客使用時的摩擦感。

3DS 2.0 的解決方案包含三個明確步驟:

  1. 您將在 check-out 頁面中加入一個iframe,該頁面用於託管發卡銀行為旅客提供的驗證體驗。在整合文件中,此元件稱為 3DS iframe。
  2. 您還需在 check-out 頁面中加入新的 client-side JavaScript 函式庫,該函式庫用於收集瀏覽器資料、與 iframe 進行通訊,並在 iframe 內顯示 SCA 驗證體驗。在整合文件中,此元件稱為 3DS 連接器函式庫。
  3. Rapid API 在完成安全驗證後,將接受付款人的銀行資訊並完成預訂。

當同時使用 JavaScript 與 Rapid API 時,採用 SCA 的預訂流程現在將在呼叫預訂 API 前後新增幾個步驟。下圖為更新後的預訂流程:

準備預訂的步驟為:先在 Rapid API 上登記付款,然後在 JavaScript API 收集資料。下一個步驟是在 Rapid API 進行預訂。最後,完整的預訂步驟始於在 JavaScript API 上顯示 SCA,然後在 Rapid API.

更新後的預訂流程中,上一步驟的輸出資料用做下一步驟的輸入資料。也就是資料會在瀏覽器的 JavaScript 和 Rapid 之間傳輸。

請注意:上圖為實際 API 流程的簡化版,做為初步說明之用。完整 API 流程請參閱整合相關文件。

整合所需元件詳細說明

瀏覽器 iframe

嵌入於 check-out 體驗中的 iframe 元素,承載著由旅客所屬的 card-issuing 銀行所擁有的網址。此網址將向使用者顯示驗證流程,並將任何 traveler-supplied 資訊直接傳輸至其銀行。該 iframe 應初始隱藏,並能在預訂嘗試後需要驗證挑戰時,將其疊加於頁面頂層。

瀏覽器 JavaScript Library

此函式庫已加入 check-out 頁面,並於預訂時調用以支援驗證流程。其 API 支援以下功能:

自動收集旅客裝置上的資料

在嘗試預訂前,必須收集旅客裝置的相關資訊,以準備預訂認證所需的資料。該資訊將傳送至旅客的 issuing-bank 進行審核,以便銀行評估風險、決定交易是否需要 3DS 2.0 驗證,並確保資訊顯示正確無誤。根據 3DS 2.0 規範,將從旅客瀏覽器收集以下資料:語言、色彩深度、螢幕高度、螢幕寬度、時區、使用者代理程式,以及 Java 是否啟用。

在瀏覽器 iframe 中顯示驗證體驗

進行預訂後,JavaScript Library 會用來顯示 iframe 置入的網頁,並將銀行網頁內容載入 iframe。在驗證過程中,銀行系統可能會收集旅客裝置的額外資訊,以支援風險評估作業。此為完成預訂的必要過程。

Rapid API

Rapid API 包含與 client-side JavaScript 函式庫協同運作的 API。這些 API 目前支援以下功能:

登記旅客及付款詳情

在嘗試預訂前,必須收集旅客的額外資訊以準備預訂供驗證使用。這些資料包括銷售點和付款等旅客帳戶詳情。此數據後續將傳送至旅客的 issuing-bank 進行審核,以便銀行評估風險並決定該交易是否需要安全驗證。欲了解更多資訊,請參閱「註冊付款 API」,此為快速預訂 API 的一部分:

完成付款並確認預訂

在瀏覽器上完成 Rapid API 的預約嘗試及 SCA 流程後,必須再次調用 Rapid。在幕後,我們將確認驗證確實成功,以便預訂得以確認。欲深入瞭解,請參閱《快速預訂 API 完整支付課程》:

預訂流程

若在「合作夥伴設定檔快速支援」中啟用 3DS 2.0,則「」價格查詢 API 將返回指向「」註冊付款 API 的連結,而非「建立預約」API。下圖所示為旅客下訂後的 API 所需呼叫順序,包括對 JavaScript Library 和對 Rapid 的呼叫。

先初始化 JavaScript Library,然後用 Rapid API「建立付款工作階段 (Create Payment Session)」。流程返回 JavaScript 來初始化「付款工作階段 (Payment Session)」,接著用 Rapid API 進行「預訂 (Book)」。若無需驗證,則預訂程序即告完成。若需驗證,請透過 JavaScript 連結以 iframe 顯示 3DS 2.0 頁面,並使用 Rapid API.

當預訂準備進行驗證時,可能並非總是需要驗證。驗證需求由支付所用信用卡的發卡銀行決定。此判定發生於交易過程中,並顯示於建立預訂 API 回應中。

下圖所示為使用「暫停與繼續處理 API」所需的呼叫順序:

先初始化 JavaScript Library,然後用 Rapid API 建立付款工作階段 (Create Payment Session)。接下來用 JavaScript API 初始化付款工作階段 (Payment Session),再用 Rapid API 進行預訂 (Book)。若無需驗證,請直接使用 Rapid API 繼續完成預訂。若需驗證,請透過 JavaScript API 以 iframe 顯示 3DS 2.0 頁面,使用 Rapid API, 完成付款流程,並透過 Rapid API 連結恢復預訂程序。

請注意:以上圖示皆為實際 API 流程的簡化版,做為初步說明之用。完整 API 流程請參閱整合相關文件。

如需進一步了解 3DS 2.0 體驗的技術要求,請參閱 EMVCo 的3D 安全協議與核心功能規範

Rapid API 以及 3DS 2.0 整合指南

要支援 SCA,需將 Rapid API 整合至名為 3DS Connector 的新 JavaScript 函式庫。兩者共同用於在 check-out 頁面呈現 3DS 2.0 並確認預訂。此解決方案支援 Expedia Collect 和入住時付款兩種商業模式。

以下概述支援 3DS 2.0 預訂所需的 API 呼叫序列,並於後續章節中詳述:

  1. JavaScript 設定方法
  2. Rapid 註冊付款 API
  3. JavaScript 初始化工作階段方法
  4. Rapid 預訂 API
  5. JavaScript Challenge 方法
  6. Rapid 完成付款 API

為啟用此序列,必須由快速合作夥伴支援服務為個別合作夥伴設定檔啟用 3DS 2.0。

Rapid API

若為合作夥伴檔案啟用驗證功能,API 回應將有所不同,以配合採用 3DS 2.0 的修訂版預訂流程。

可用性 API

在符合規範允許的情況下,API 請求中的sales_channel 欄位值必須準確無誤,方能取得驗證豁免權限。此數值連同其他諸多因素,將由發卡銀行在預訂時進行審核以作出決策。僅代理工具可豁免適用加強型客戶驗證 (SCA)。若需註明此項目,請把 sales_channel 的值設為 agent_tool

價格檢查 API

API 會回傳連結到「註冊付款 API」,而不是到「建立預訂 API」。

當啟用 3DS 2.0 時,範例回應如下:

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

註冊付款 API

此為 SCA 預訂流程的第二步,發生於 JavaScript setup方法之後。

該請求將包含支付詳細資訊 (此為 non-SCA 預訂流程的一部分) 以及支援成功驗證的新欄位。其中兩個欄位:encoded_browser_metadataversion 是從 JavaScript API 的 setup method 回傳。

回應中會包括 payment_session_idencoded_init_config,並成為 JavaScript Library initSession 方法的輸入資料。回應中包含的預訂連結應在執行initSession 方法後使用。

請求範例:

{
    "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": "2018-02-12T11:59:00.000Z",
        "create_date": "2018-09-15",
        "change_date": "2018-09-17",
        "password_change_date": "2018-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": "2025",
            "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": "2018-09-15"
        }
    ]
}

回應範例:

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

建立預訂 API

此為 SCA 預訂流程的第四個步驟,發生於 JavaScript initSession方法之後。此請求將不包含任何新的 SCA 欄位——所有必要資訊皆包含於支付註冊 API 回傳的預訂連結憑證中。若回應成功,一定會包含 itinerary_id。然而,這並不能單獨證明預訂已確認,因為可能需要進行 3DS 2.0 驗證。

如有需要,回覆亦將包含一個 encoded_challenge_config. 從「註冊付款」回傳的 encoded_challenge_configpayment_session_id 必須用為參數傳入 JavaScript challenge 方法。

回應還會包括用來 complete_payment_session 的新連結。此連結應於 JavaScript Library 的 challenge 方法之後使用。

若無需進行 3DS 2.0 驗證,則預訂確認成立,回應中將包含retrievecancel 連結,以及可選的resume 連結。

範例:若需 3DS 2.0 驗證,則建立預訂回應:

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

完成付款工作階段 API

此為 SCA 預訂流程的第六個步驟,發生於 JavaScript challenge方法之後。此 API 需完成付款流程,並通知 Rapid API 是否已成功執行安全驗證嘗試 (無論成功與否)。

該請求將不包含任何新的 SCA 欄位。

若回應成功,將包含預訂確認資訊,內含訂單編號 (itinerary_id) 及以下連結:- 訂單詳情頁面 (retrieve)- 訂單狀態頁面 (cancel)- 選用連結 (resume)

回應範例:

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

Iframe 與 JavaScript 函式庫實作

使用 SCA 預訂工作流程時,check-out 頁面必須包含新的 iframe 及 JavaScript 庫。該 iframe (稱為 3DS iframe) 將透過3D-Secure 2.0 顯示驗證流程。而 JavaScript Library (稱為 3DS Connector Library) 則負責傳送資料給發卡銀行,並把銀行的內容載入 iframe。

新增 iframe

3DS iframe 應包在開始時為隱藏的容器中,當付款程序判定為必須進行驗證時,則會再顯示。

容器設計可配合裝載頁面來自訂。以下為使用 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>

iframe 的源 (source) 必須設為以下兩個值之一:

URL 類型URL備註
正式環境https://static.pay.expedia.com/3ds/threeDsIframe.html支援生產驗證
測試沙箱https://static.pay.expedia.com/3ds/sandboxThreeDsIframe.html支援驗證測試

上列測試 URL 可支援測試,下文會再回到這個主題。為限制測試期間 iframe 的內容,可為 iframe 附加 sandbox 屬性,但必須允許以下項目:

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

新增 JavaScript 函式庫

3DS Connector Library 負責和 3DS iframe 溝通,並傳送資料給發卡銀行;銀行為 iframe 內容提供者。以下範例顯示如何將 3DS Connector Library 新增到付款頁面。

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

腳本元素的來源與完整性值應設定為以下數值:

Library 版本屬性
1.3.39srchttps://static.pay.expedia.com/3ds/1.3.39/pay-3ds-js-libs-connector.min.js
integritysha384-par0I4Q5cfljwzqw2mAggM4dKdYzGyj4uZiL4cMviGjI3qVzEgWGuZ2075mYutbT
1.3.65srchttps://static.pay.expedia.com/3ds/1.3.65/pay-3ds-js-libs-connector.min.js
integritysha384-gYopPw6xE5DZwnZXGavkwnvs3NkDOobnHqjroUnSHpGXvs/J9xjHX/8aGzKtSgWI

註: 隨著未來版本的推出,來源網址與完整性將會有所變動。新版不會破壞現有的整合。舊版的 script 元素仍可存取。

使用 3DS 和 JavaScript 進行 SCA

JavaScript Library 需使用 JavaScript Promise 物件。下圖為執行範例,顯示 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 Connector Library 內容,旨在示範可支援資料傳輸到 API 的封套資料。

範例中使用靜態變數為參數,執行時應另行決定,如 referenceId

Check-out 頁面設計指南

支援 3DS 驗證的信用卡品牌,可能要求其標誌與品牌識別須依照品牌規範進行展示。

支付卡類別認證品牌標識商標和使用方法
MasterCard (萬事達卡)萬事達卡 ID Check https://brand.mastercard.com/debit/mastercard-brand-mark/downloads.html
VisaVisa 驗證https://www.merchantsignage.visa.com/brand_guidelines

備註:待其他卡別的商標和使用辦法公布時會再納入此表。

3DS Connector JavaScript Library 相關文件

類別 (Class):ThreeDSConnector

建構函式: new ThreeDSConnector(threeDsIFrameId, threeDsIFrameOrigin)

參數:

名稱類型說明
threeDsIFrameId字串3DS iframe 的 ID。
threeDsIFrameOrigin字串3DS iframe 的原點 (Origin)。在與 3DS iframe 溝通使用以傳出視窗訊息並過濾接受訊息。

設定

透過收集後端 3DS 服務所需的瀏覽器基本資訊 (例如螢幕尺寸、色彩深度等),建立付款會話。

方法簽名: setup(setupRequest)

參數:

名稱類型
setupRequestSetupRequest

回傳: 承諾為 SetupResponse

初始化

初始化 3DS 驗證的會話。進行初始化可能需要從瀏覽器收集其他資料。若發卡機構提出要求,iframe 可載入 3DS URL 來啟動發卡機構的存取控制伺服器 (Access Control Server),直接從瀏覽器收集資料。用戶端不必等待回呼完成,於建立命令前即可調用。

方法簽名: initSession(initSessionRequest)

參數:

名稱類型
initSessionRequestInitSessionRequest

回傳: 承諾為一個 InitSessionResponse

挑戰 (Challenge)

若發卡機構要求,請載入 3DS 驗證流程。

方法簽名: challenge(challengeRequest)

參數:

名稱類型
challengeRequestChallengeRequest

回傳: 承諾為 ChallengeResponse

類別 (Class):SetupRequest

設定呼叫的需求架構。

性質:

名稱類型說明
referenceIdstring辨識旅客付款頁面工作階段的參考 ID,用於記錄和追蹤。請使用 APIKey 和 Customer-Session-ID 的序連字元,中間以下劃線連接,例如:[APIKey]_[SessionID]

類別 (Class):SetupResponse

來自設定呼叫的回應。

性質:

名稱類型說明
version字串函式庫版本,和連往函式庫的 URL 所示版本相同。
encodedBrowserMetadata字串編碼物件,內含從瀏覽器收集的資料。用戶端應將此視為不透明數據,無需解析即可傳給後端支付服務。

類別 (Class):InitSessionRequest

initSession 方法的需求架構。

性質:

名稱類型說明
paymentSessionId字串「Rapid 註冊付款 API」傳回的唯一識別碼。
encodedInitConfig字串編碼物件組態清單,內含初始化所需資料,由「Rapid 註冊付款 API」傳回。

類別 (Class):InitSessionResponse

initSession 方法的回應結構。

性質:

名稱類型說明
statusCode字串initSession 呼叫的狀態。
message字串可選用。標示失敗原因。

statusCode 可能會有以下的值:

說明
SUCCESS初始化成功完成。
SKIPPED沒有進行初始化。
FAILED初始化失敗。訊息欄位包含更多失敗相關的訊息。
TIMEOUT初始化未在時間內完成。時限為 10 秒。

注意:對於所有initSessionresponse statusCode 的值,請使用快速預訂 API 進行操作。

類別 (Class):ChallengeRequest

挑戰 (Challenge) 方法的需求架構。

性質:

statusCode 值測試 encoded_Challenge_config 值說明
SUCCESSW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlNVQ0NFU1MifV0無使用者 iframe 互動
SUCCESS / FAILEDW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlNIT1cifV0無使用者 iframe 互動
FAILEDW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIkZBSUxFRCJ9XQ無使用者 iframe 互動
TIMEOUTW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlRJTUVPVVQifV0
ERRORW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmdlT3V0cHV0Q29uZmlnIjogIkVSUk9SIn1d

statusCode 可能會有以下的值:

說明
SUCCESS3DS 挑戰 (Challenge) 成功完成。
SKIPPED外部應用程式錯誤。
FAILED由於持卡人無法正確回應身分驗證挑戰,故 3DS 挑戰未成功完成。
TIMEOUT挑戰未在時間內完成。時限為 1200 秒。

注意:所有challengeResponse statusCode 值,請透過 Rapid API 完成付款流程。

使用 Rapid API 與 3DS 2.0 進行測試

您可透過輸入對應於 API 所支援特定情境的參數值,測試與 Rapid API 及 3DS 連接器方法的整合功能。

Rapid API

要測試 Rapid API,,請在 HTTP 請求中加入名為test 的額外 HTTP 標頭,並使用該 API 支援的任一值來測試相容情境。

在 SCA 預訂流程中,來自 Rapid API 的測試回應亦可用於測試 3DS 連接器庫方法。

註冊付款 (Register Payments)

以下測試標頭值在 API 回應中會產生不同 encoded_init_config,以及不同 HTTP 回應碼。encoded_init_config 可傳入 JavaScript Library 的 initSession 呼叫,以啟動 3DS Connector Library 中的不同測試用例。

測試標題值HTTP 代碼與回應initSession 測試用例
standard201 – 標準回應SUCCESS
init_skip201 - 不含 encodedInitConfig 的回應Not supported
init_fail201 – 標準回應FAILED
init_timeout201 – 標準回應TIMEOUT
internal_server_error500 – 內部伺服器錯誤
internal_server_error503 - 伺服器無法使用

備註:init_skip 3DS Connector Library.t_config 裡的不同測試案例可傳到 initSession,便會強行產生名為 SKIPPED 的 statusCode

建立預訂

除了在Rapid Booking Test Requests 中為 non-SCA 預訂流程定義的測試標頭外,SCA 工作流程還支援額外的測試標頭值。

測試標頭值會產生不同的 encodedChallengeConfig 值,這些值可傳入 JavaScript Library 的 challenge 呼叫,以觸發不同的測試案例。

測試標題值HTTP 代碼與回應initSession 測試用例
complete_payment_session201 – 含完成付款工作階段連結的回應SUCCESS 無使用者 iframe 互動
complete_payment_session_show201 – 含完成付款工作階段連結的回應SUCCESS/FAILED 有使用者 iframe 互動
complete_payment_session_fail201 – 含完成付款工作階段連結的回應FAILED 無使用者 iframe 互動
complete_payment_session_timeout201 – 含完成付款工作階段連結的回應TIMEOUT
complete_payment_session_error201 – 含完成付款工作階段連結的回應ERROR

完成付款工作階段

在試著完成付款並確認預訂時,測試標頭值會產生不同錯誤情況。

測試標題值HTTP 代碼與回應
payment_declined400 - 付款遭拒回應
price_mismatch409 - 房價不符回應
rooms_unavailable410 - 無空房回應

3DS Connector Library 和 iframe

在無外部相依關係下測試 3DS Connector 時,需使用符合支援方法回應的特定參數值。僅限 iframe 用測試沙箱 URL 載入時才支援這種做法。

初始化工作階段

InitSessionResponse statusCode 所支援的值可用變更 initSessionRequest encodedInitConfig 的方法來測試。

statusCode 值測試 encodedInitConfig 值
SUCCESSW3sicHJvdmlkZXJJZCI6IDAsICJz YW5kYm94SW5pdE91dHB1dENvbmZpZyI6ICJTVUNDRVNTIn1d
FAILEDW3sicHJvdmlkZXJJZCI6IDAsICJz YW5kYm94SW5pdE91dHB1dENvbmZpZyI6ICJGQUlMRUQifV0=
TIMEOUTW3sicHJvdmlkZXJJZCI6IDAsICJz YW5kYm94SW5pdE91dHB1dENvbmZpZyI6ICJUSU1FT1VUIn1d
SKIPPEDNot supported at this time.

注意:encoded_init_config 值也可以使用「註冊付款 API」支援的測試標頭產生。

挑戰 (Challenge)

challengeResponse statusCode 所支援的值可用變更 challengeRequest encondedChallengeConfig 的方法來測試。

statusCode 值測試 encoded_Challenge_config 值說明
SUCCESSW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlNVQ0NFU1MifV0無使用者 iframe 互動
SUCCESS / FAILEDW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlNIT1cifV0無使用者 iframe 互動
FAILEDW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIkZBSUxFRCJ9XQ無使用者 iframe 互動
TIMEOUTW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmd lT3V0cHV0Q29uZmlnIjogIlRJTUVPVVQifV0
ERRORW3sicHJvdmlkZXJJZCI6IDA sICJzYW5kYm94Q2hhbGxlbmdlT3V0cHV0Q29uZmlnIjogIkVSUk9SIn1d

預訂 API 的 SCA 流程支援的測試標頭,亦可產生對應的encodedInitConfig 值。

注意:當根據使用者輸入透過 iframe 檢測挑戰狀態碼值為 SUCCESS 或 FAILED 時,挑戰方法的回應將等待 iframe 中模擬的認證介面完成操作。

3DS iframe 中的 UI 範例:

3DS iframe 範例

用法範例

以下為執行範例,僅供參考。範例中可看到如何使用預先定義的值來測試 Library 進行 3DS 挑戰,而不需要使用者與 iframe 互動。

var c = new PayThreeDSConnector.ThreeDSConnector(’threedsiframe’, ’https://static.pay.expedia.com’); // change to match the 3DS iframe ID
c.setup({ referenceId: ’1000’ })
    .then((setupResponse) => {
        console.log(’Setup Output: ’, setupResponse);
        return c.initSession({
            paymentSessionId: 1,
            encodedInitConfig: ’ W3sicHJvdmlkZXJJZCI6IDAsICJzYW5kYm94SW5pdE91dHB1dENvbmZpZyI6ICJTVUNDRVNTIn1d’,
        }); // SUCCESS
    })
    .then((initResponse) => {
        console.log(’InitSession Output: ’, initResponse);
        $(’#threedsIframeModal’).modal(); // replace with code to show the modal containing the 3DS iframe
        return c.challenge({
            paymentSessionId: 1,
            encodedChallengeConfig:
                ’ W3sicHJvdmlkZXJJZCI6IDAsICJzYW5kYm94Q2hhbGxlbmdlT3V0cHV0Q29uZmlnIjogIlNVQ0NFU1MifV0=’,
        }); // SUCCESS
    })
    .then((challengeResponse) => {
        console.log(’Challenge Output: ’, challengeResponse);
    })
    .finally(() => {
        $(’#threedsIframeModal’).modal(’hide’); // replace with code to hide the modal containing the 3DS iframe
    });

3DS 驗證與旅宿收集

透過旅宿預訂並選擇「取票」服務時,Expedia 不會向信用卡扣款。相反地,我們將其轉交給旅宿進行處理。旅宿可能會用收到的資訊在入住前先進行信用卡驗證。旅客須親臨現場付款於 check-in.

然而,有些旅客在預訂後卻沒有入住,此時旅宿就會收取未入住罰款。這些費用可能受到 SCA 法規的影響,因為它們涉及在旅客不在場時對卡片進行扣款。

當交易受 PSD2 影響而收款手續卻不符規定,則可能會導致交易失敗,旅宿也可能會面臨信用卡公司的罰款。

Expedia Group 為了維持與旅宿的良好關係,並繼續服務我們的合作夥伴,因此提供給旅宿另一項合規辦法:受影響的屬性現在可運用 Expedia Group 來代為提供驗證服務。此舉使物業得以保障其業務,並確保 Rapid API 能持續提供同樣多元化的物業選擇。

Rapid API 在旅宿內容檔案及旅宿內容中提供<payment_registration_recommended=true> 的標誌,這有助於您在專案中識別可能涉及的旅宿。

整合可能產生的影響

若您希望提供需安全驗證的房產服務,則預訂流程應支援 3DS 驗證機制。若未啟用 3DS 驗證功能,當 card-issuing 銀行判定交易需進行身份驗證時,預訂這些房產的交易可能失敗。

旅宿, Rapid API 當美國運通 (美國運通公司) 收取美國運通卡 (no-show) 費用時,將由該卡發卡機構擔任記錄中的商戶。信用卡帳單上的交易描述將由貴機構定義,而非由旅宿決定。若想自訂此名稱,請聯絡 Rapid 合作夥伴服務。

為符合卡組織要求及 Rapid API 啟動流程,請使用 Accepted Payments API 於 check-out 頁面顯示processing_country,以防萬一。no-show. 此要求適用於所有以 Rapid API 為登記商戶的交易,若使用 3DS 驗證且發生「no-show」情況時可能觸發此流程。

如何減輕對整合的影響

若某個 Rapid API 整合方案在預訂流程中不支援安全驗證機制,則可透過停止銷售該房源來降低預訂失敗的風險。請聯絡快速合作夥伴支援團隊,將受影響的旅宿匯率從您的可用性 API 回應中移除。

根據法規,使用代理工具進行交易時,該交易可豁免適用加強型客戶識別程序 (SCA)。如有需要,可在「供應情況 API」的 sales_channel 欄位加註。

錯誤處理

「建立預訂 API」和「完成付款工作階段 API」可能會產生預訂確認和付款交易。

系統整合時請考慮以下說明,以避免財物損失和客戶操作的情形。

來源功能建議時限錯誤復原做法需採取的行動
Rapid API註冊付款的預訂前價格檢查記號10 秒重試或選擇其他住宿、客房或房價-
JavaScript3DS Connector 設定10 秒重試相同的要求-
Rapid API註冊付款工作階段10 秒在不包含 ["Expect: 100-Continue"] 的情況下重新嘗試相同的請求](https://tools.ietf.org/html/rfc7231#section-6.2.1 ’Follow link’)-
JavaScript初始化付款工作階段10 秒重試相同的要求-
Rapid API建立預訂90 秒重試相同的要求所有錯誤:用 affiliate_reference_id 取回預訂
JavaScript顯示驗證挑戰10 秒重試相同的要求-
JavaScript等待 challenge.statusCode180 ~ 1200 秒要求完成付款工作階段-
Rapid API完成付款工作階段 (Complete Payment Session)90 秒重試相同的要求所有錯誤:用 affiliate_reference_id 取回預訂
Rapid API所有錯誤:用 affiliate_reference_id 取回預訂30 秒重試相同的要求所有錯誤:等待 90 秒後再重試,用 API 回應碼 404 或 200 確認預訂最後狀態
這個頁面有幫助嗎?
我們能如何改善內容?
感謝您協助我們進行改善!