- インテグレーションガイドライン
- Hosted Sessionのインテグレーションの実装
Hosted Sessionのインテグレーションの実装
Hosted Session JavaScript クライアントライブラリを利用すると、QNB ALAHLIによりホストされる支払フォームフィールドを使用して、支払者から機密認証データを含む支払詳細が収集できます。ゲートウェイは支払セッション中に機密認証データを含む支払詳細を収集し、後で使用するためにその詳細を一時的に保存します。支払詳細の代わりに支払セッションを取引リクエストに格納して、支払いを処理できます。詳細については、「支払セッション」を参照してください。
Hosted Sessionとは、SAQ-A コンプライアンスを実現する PCI v3 準拠のインテグレーション方法です。この方法では、支払画面のレイアウトとスタイルが管理できます。このモデルでは、機密認証データを含む支払情報のフィールドがすべて、QNB ALAHLIより送信および制御される iFrame に組み込まれます。ブラウザの標準的なセキュリティ保護メカニズムにより機密認証データを含むフィールドが貴社と切り離され、ゲートウェイにより提供される支払チャネルの完全性が維持されます。
前提条件
- 加盟店プロファイルがHosted Sessionサービスで有効なことを確認する。
- Hosted Sessionは、<<webServicesIntegration>> バージョン 18 以降でのみサポートされています。
Hosted Sessionインタラクションのリクエスト
このセクションでは、支払者のクレジットカードの詳細情報を収集するための、Hosted Sessionの簡単なインテグレーションについて説明します。
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <h3>Credit Card</h3> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="2" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="3" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay('card');">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } PaymentSession.configure({ session: "<your_session_ID>", fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
手順 1: セッションの作成
サーバ側アプリケーションから Create Session
リクエストを送信することでセッションを作成します。セッション認証は 25 を上限に指定してください。レスポンスは、後続の手順でこのセッションを参照する必要があるセッション ID を返します。
URL | https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session |
HTTP メソッド | POST |
{ "session":{ "authenticationLimit":25 } }
手順 2: 注文金額と通貨でのセッションの更新
サーバ側アプリケーションから Update Session
リクエストを送信することで、少なくとも通貨および注文金額でセッションを更新します。この手順は、カードがサポートされているかどうか、そしてカードのセキュリティコードが必要かどうかを後で照会するのに必要です。
URL | https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session/<your_session_ID> |
HTTP メソッド | PUT |
{ "order":{ "amount":100.00, "currency":"USD" } }
手順 3: 支払画面に session.js クライアント JavaScript ライブラリ を含める
支払画面で、head
要素に script
要素を追加することにより、ゲートウェイからホストされる session.js
クライアント JavaScript ライブラリを読み込みます。このファイルへのパスには、API バージョンとセッションの加盟店識別子の両方が含まれます。これで、PaymentSession
オブジェクトはウィンドウネームスペースに配置されます。
<script type="text/javascript" src="https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<your_gateway_merchant_ID>/session.js"></script>
手順 4: クレジットカードフィールドを含む支払画面用の HTML の作成
readonly
であり、name
属性を持たないことを確認します。手順 5: PaymentSession.configure(configuration)
関数の呼び出し
configuration
オブジェクトでは、支払画面へのホスト型フィールドの追加や、支払インタラクションの設定が可能です。以下を提供する必要があります。
- 手順 1 で作成した session.id を含めます。セッションを作成します。
- クレジットカードフィールド用のフィールドセレクタ。提供すると、セレクタは、QNB ALAHLIによりホストされる iFrame に組み込まれた対応するプロキシフィールドに置き換えられます。このプロキシフィールドは、置き換えられたフィールドと外観や雰囲気が同じです。他の支払タイプの場合でも支払詳細が取得できます。「Hosted Sessionでサポートされる支払方法」を参照してください。
-
クリックジャッキングを回避するためのリスク軽減オプション
クリックジャッキングは「UI redress attack」とも呼ばれ、攻撃者は複数の透過または不透過レイヤを利用して、ユーザーが最上位レベルのページをクリックしようとしたときに、別のページのボタンまたはリンクをクリックさせます。Hosted Sessionを使用する場合、クリックジャッキング攻撃に対する以下の防止策を 1 つまたは複数実装する必要があります。
フレームに関するリスク軽減オプション 実装 javascript
支払画面に「frame-breaker」JavaScript を含めます。 x-frame-options
サーバが X-Frame Options HTTP レスポンスヘッダーを返す必要があります。 csp
サーバが frame-ancestors ディレクティブを含む Content-Security-Policy HTTP レスポンスヘッダーを返す必要があります。 どの防止策を実装するかを、
PaymentSession.configure(configuration)
コールのframeEmbeddingMitigation
パラメータで指定する必要があります。クリックジャッキング攻撃に対する防止策については、OWASP 外部 Web サイトの「Clickjacking Defense Cheat Sheet」を参照してください。 -
Hosted Session インタラクション中にさまざまなイベントを処理するコールバック
initialized( )
:ホスト型フィールドを支払画面に追加する際に呼び出されます。formSessionUpdate( )
:PaymentSession.updateSessionFromForm(paymentType)
関数に対するレスポンスで呼び出されます(次のステップを参照)。
手順 6:updateSessionFromForm の呼び出し
PaymentSession.updateSessionFromForm('card')
を呼び出して、支払タイプ 'card'
について取得された支払詳細を支払画面に保存します。操作が完了すると、結果のパラメータを使用して formSessionUpdate()
コールバックが呼び出されます。result.status
値を確認して、操作が成功したかどうかを判定する必要があります。「コールバックレスポンスの処理」を参照してください。
手順 7: 支払セッションデータの使用
返された支払セッション(session.id)を使用して、必要に応じてトークン化または支払取引を実行できます。詳細については、「セッションを使用した操作の実行」を参照してください。
Hosted Sessionでサポートされる支払方法
Hosted Sessionでは、以下の 1 つまたは複数の支払方法を設定して、支払者からの支払詳細が取得できます。支払詳細は、支払フォームに追加されたホスト型フィールドを介して取得されます。ただし、支払詳細がウォレットインタラクションから取得されるデジタルウォレットは例外です。
ホスト型フィールドを使用して、次のカード詳細が取得できます。
card.number
card.expiryMonth
card.expiryYear
card.securityCode
card.nameOnCard
card.expiryMonth
が設定されている場合には、card.expiryYear
は必須です。逆も同様です。ホスト型フィールドを使用して、次のギフトカード詳細が取得できます。
giftCard.number
giftCard.pin
「Hosted Session を使用したギフトカードインテグレーション」を参照してください。
Hosted Session によって、Direct Payments (支払い) および Direct Deposits (返金) の支払詳細を <<ach>>を経由して取得することができます。ホスト型フィールドを使用して、次の <<ach>> 詳細が取得できます。
ach.routingNumber
ach.bankAccountNumber
ach.bankAccountNumberConfirmation
ach.bankAccountHolder
ach.accountType
「Hosted Session を使用した <<ach>> インテグレーション」を参照してください。
Hosted Sessionを使用して、ウォレットインタラクションから支払詳細が取得できます。現在は、セキュアリモートコマースウォレットインタラクションがサポートされています。このインタラクションを開始するには、QNB ALAHLI経由でセキュアリモートコマースを利用できるようにする必要があります。「セキュアリモートコマース」を参照してください。
フィールドデータ検証フィードバック
Hosted Session は、支払インタラクションのさまざまな段階において、ユーザーインターフェイス上で支払者に検証フィードバックを提供できるようにします。
onValidityChange
コールバックを確認することによる各キーストローク
PaymentSession.onValidityChange(["card.number", "card.nameOnCard"], function (selector, result) { if (result.isValid) { console.log("The field value is valid"); document.querySelector(selector).style.borderColor = "green"; } else if (result.isIncomplete) { console.log("The field value is not yet valid"); document.querySelector(selector).style.borderColor = "grey"; } else { console.log("The field value is invalid"); document.querySelector(selector).style.borderColor = "red"; } });
- 支払者がタイピングを終了し、フィールドを離れた場合:
onBlur()
イベントを確認しますvalidate()
を呼び出しますvalidate()
コールバックからそのフィールドのエラーを表示します
PaymentSession.onBlur( ["card.number", "card.nameOnCard", "card.securityCode", "card.expiryYear", "card.expiryMonth"], function (selector, role) { PaymentSession.validate('card', function (allresult) { if (allresult.card[role].isValid) { console.log("The field is valid"); document.querySelector(selector).style.borderColor = "green"; } else { console.log("The field is invalid"); document.querySelector(selector).style.borderColor = "red"; } }); });
- 支払者がそのページで次の操作をするボタンをクリックした場合:
updateSessionFromForm()
を呼び出しますformSessionUpdate
コールバックからのエラーを表示します
どの方法であっても、formSessionUpdate
コールバックからエラーがあることを予期し、対処する必要があります。validate()
の方法では妥当性が示される一方、formSessionUpdate
の検証はより包括的で、追加のエラーが検出されることがあります。
コールバックレスポンスの処理
initialized(result)
を介したホスト型フィールドの結果result.status=="ok"
の場合ホスト型フィールドは支払画面に正常に追加されました。
// An ok response { "status":"ok", }
result.status=="system_error"
または result.status=="request_timeout"
の場合ホスト型フィールドを追加したときにエラーが発生しました。しばらくしてから再試行する必要があります。
// An error response (system_error) { "status": "system_error", "message": "System error message." } // An error response (request_timeout) { "status" : "request_timeout", "message": "Request timeout error message." }
formSessionUpdate(result)
を介した Update Session の結果result.status=="ok"
の場合収集されたカード詳細がセッションに含まれています。
// An ok response { "status":"ok", "merchant": "TESTMERCHANT", "session": { "id": "SESSION000218450948092491657986" "updateStatus":"SUCCESS", "version":"e3f144ce02" }, "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "nameOnCard": "John Smith", "number": "512345xxxxxx8769", "scheme": "MASTERCARD" } }, "type": "CARD" }, "version": "43" }
result.status=="fields_in_error"
の場合支払者の入力が無効であり、支払者に入力の更新を求める必要があります。errors
レスポンス構造体には、無効なフィールドに関する情報が含まれています。
// An error response (fields_in_error) { "status": "fields_in_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "cardNumber": "invalid", "securityCode": "invalid" }, version: "43" }
result.status=="system_error"
または result.status=="request_timeout"
の場合更新の処理中にエラーが発生しました。しばらくしてからセッションの更新を再試行する必要があります。
// An error response (system_error) { "status": "system_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "System error message." }, "version": "43" } // An error response (request_timeout) { "status" : "request_timeout", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "Request timeout error message." }, "version": "43" }
ホスト型フィールドでのイベントの監視
Hosted Session では、コールバック機能を登録して、支払者のインタラクション中にホスト型フィールドで発生する可能性のあるイベントを処理することができます。
onChange( )
:iFrame 内のホスト型フィールドの入力値が変更されたときに呼び出されます。onFocus( )
:iFrame 内のホスト型フィールドが選択されたときに呼び出されます。onBlur( )
:iFrame 内のホスト型フィールドが選択解除されたときに呼び出されます。onMouseOver( )
:ホスト型フィールドでマウスオーバーイベントが発生したときに呼び出されます。onMouseOut( )
:ホスト型フィールドでマウスアウトイベントが発生したときに呼び出されます。
/** * Provide an array of field roles for proxy fields as the first parameter * Each callback function is invoked with the selector for the field whose proxy triggered the event. */ PaymentSession.onBlur(['card.number'], function(selector) { //handle blur event }); PaymentSession.onFocus(['card.number', 'card.securityCode'], function(selector) { //handle focus event }); PaymentSession.onChange(['card.securityCode'], function(selector) { //handle change event }); PaymentSession.onMouseOver(['card.number'], function(selector) { //handle mouse over event }); PaymentSession.onMouseOut(['card.number'], function(selector) { //handle mouse out event });
ホスト形フィールドの詳細スタイル
Hosted Session では、ホスト型フィールドのスタイルを設定して、支払画面で置き換えられるフィールドの外観と雰囲気に一致させることができます。
setFocus( )
:指定したホスト型フィールドを選択状態に設定します。setFocusStyle( )
:指定したホスト型フィールドが選択されたときのスタイル属性を設定します。setHoverStyle( )
:指定したホスト型フィールド上にマウスカーソルが移動されたときのスタイル属性を設定します。setPlaceholderStyle( )
:指定したホスト型フィールドのプレースホルダーテキストのスタイル属性を設定します。setPlaceholderShownStyle( )
:プレースホルダーテキストが表示される場合に、指定したホスト型フィールドのスタイル属性を設定します。
PaymentSession.setFocus('card.number'); PaymentSession.setFocusStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setHoverStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setPlaceholderStyle(["card.number", "card.nameOnCard"], { color: 'blue', fontWeight: 'bold', textDecoration: 'underline' }); PaymentSession.setPlaceholderShownStyle(["card.number", "card.nameOnCard"], { color: 'green', fontWeight: 'bold', textDecoration: 'underline' });
有効期限の月および年のドロップダウンフィールド
Hosted Sessionでは有効期限の月および有効期限の年にドロップダウンの値を使用できます。詳細については、以下のサンプルコードを参照してください。
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month: <select id="expiry-month" class="form-control input-md" required="" readonly> <option value="">Select Month</option> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> </div> <div>Expiry Year: <select id="expiry-year" class="form-control input-md" required="" readonly> <option value="">Select Year</option> <option>21</option> <option>22</option> <option>23</option> <option>24</option> <option>25</option> <option>26</option> <option>27</option> <option>28</option> <option>29</option> <option>30</option> <option>31</option> <option>32</option> <option>33</option> <option>34</option> <option>35</option> <option>36</option> <option>37</option> <option>38</option> <option>39</option> </select> </div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="3" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
ホスト型フィールドのアクセシビリティの設定
Hosted Sessionでは Web サイトのアクセシビリティを改善できる機能が提供されています。
<!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="card security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div>
以下のオプションでは、アクセシビリティ面のニーズがある支払者のユーザーエクスペリエンスをより詳細に管理できます。
iFrame タイトルの設定
ホスト型フィールドの iFrame title 属性を、そのフィールドで title 属性を使用して管理できます。
アクセシビリティの高いインターネットアプリケーション属性の設定
Hosted Session は、aria 属性をサポートしています。この属性を使用して、アシスティブ技術を使用する支払者のエクスペリエンスを高めることができます。
無効な文字表示パラメーターの設定
アシスティブ技術を使用する支払者のエクスペリエンスを高めるために、ホスト型フィールドですべての文字を受け入れることを考慮します。これを行うには、PaymentSession.configure()
メソッドで表示パラメータ interaction.displayControl.invalidFieldCharacters=ALLOW
を設定します。
言語属性を設定します
言語 属性を HTML 要素に追加します。
<html lang="en"> <head></head> <body></body> </html>
非表示のラベルとエラーメッセージ
すべてのホスト型フィールドには非表示のラベルが含まれ、必須のホスト型フィールドには非表示のエラーメッセージが含まれます。PaymentSession.updateSessionFromForm()
を呼び出すことによって生じたエラーは、エラーメッセージラベルを生成します。PaymentSession.setMessage()
の方法を使用して、追加で独自のエラーを生成することができます。
たとえば、カード番号フィールドに対する非表示のラベルは、“カード番号" です。未入力のカード番号に対する非表示のエラーメッセージは、“カード番号がありません、値を入力してください" です。無効なカード番号に対する非表示のエラーメッセージは、“カード番号が無効です、正しい値を入力してください" です。ホスト型フィールドをタブで移動すると、非表示のラベルと非表示のエラーメッセージのみがスクリーンリーダーで読み取られますが、UI に表示される実際のラベルまたはエラーメッセージは読み取られません。
設定オブジェクトでロケールプロパティを設定します
ロケールプロパティは、非表示のラベルとエラーメッセージを含むすべてのホスト型フィールドの翻訳を提供します。これが設定されていない場合、英語がデフォルトになります。このプロパティでサポートされている値は、de_DE、el_GR、en_US、es_MX、es_ES、fr_CA、fr_FR、it_IT、ja_JA、pl_PL、pt_BR、ro_RO、zh_CN です。
支払者の混乱を避けるため、言語属性とロケールプロパティを同じにすることを推奨します。
PaymentSession.configure({ fields: { card: { nameOnCard: cardHolderNameField ? "#card-holder-name" : null, number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year" } }, frameEmbeddingMitigation: ["javascript"], locale:"fr", callbacks: { } });
自動選択
HTML5 のデフォルト機能の 1 つは、ホスト型フィールドで作動しません。たとえば、支払者がラベルをクリックしても、対応する入力/選択要素を自動的に選択しません。setFocus
を使って、この操作を行ってください。
Hosted Session での複数のカードの承諾
Hosted Session では、同一ページ上で支払者の複数のカードを承諾できます。この場合、カードごとに別々の支払セッション、別々の注文になります(支払取引で支払セッションを使用する場合)。これは、たとえば、お客様が同じ予約に対して複数のカードを使用して支払いを行いたい場合などに役に立つことがあります。このとき Web サイトでは、別々の支払セッションから生成された注文を、その顧客の単一の予約に統合する必要があります。
複数の Hosted Session インタラクションのリクエスト
複数のカードを承諾するには、scope
パラメータを使用して PaymentSession.configure()
関数を呼び出す必要があります。このパラメータは、カード支払データブロックを識別するために使用する任意の一意の文字列にすることができ、ページ上の特定の HTML を参照する必要はありません。加盟店サーバ上に保存する各カードのデータは、別々の範囲に保持する必要があります。
PaymentSession.configure('configuration', scope)
次の Hosted Session 呼び出しの scope
パラメータは、最初の PaymentSession.configure()
呼び出しが scope
で呼び出されると必須になります。
PaymentSession.updateSessionFromForm('card', 'card-type', scope)
PaymentSession.setFocus('cardNumber', scope)
範囲を使用してインタラクションが設定された場合、次の呼び出しでは scope
パラメータは任意指定です。呼び出しで範囲が指定されていない場合、ホスト型 iFrame 内のすべてのカードデータセットに関数/コールバックが適用されます。
PaymentSession.setFocusStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.setHoverStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.onFocus([<HostedFieldsRole>],function(selector), scope)
PaymentSession.onBlur([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onChange([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOver([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOut([<HostedFieldsRole>], function(selector), scope)
例
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION AS PER USUAL MANNER. if (response.status) { if ("ok" == response.status) { // RECORD THE SESSIONID RETURNED AND ASSOCIATE IT WITH THE SCOPE CONFIGURED. sessions.push(JSON.parse('{ "scopeId": "' + response.scopeId + '", "sessionId": "' + response.session.id + '"}')); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }, 'card-payment-details-#1'); // ADD ANY UNIQUE STRING IDENTIFIER VALUE TO THE CONFIGURE CALL function pay() { sessions.forEach(function (e) { // UPDATE THE SESSION WITH THE FIELD VALUES. THE SCOPE MUST BE THE THIRD PARAMETER. PaymentSession.updateSessionFromForm('card', undefined, e.scopeId); }); } </script> </body> </html>
インテグレーションのテスト
実際の取引処理を開始する前に、正しく機能することを確認するためにインテグレーションをテストする必要があります。
テスト用加盟店 ID を使用した Hosted Session インテグレーションのテスト時に追加のログをサポートするには、URL に ?debug=true
を追加します。
https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<TESTMERCHANTID>/session.js?debug=true
トラブルシューティングと FAQ
このイベントは次のように処理します。PaymentSession.updateSessionFromForm('card')
レスポンスのカードタイプ情報(sourceOfFunds.provided.card.brand
と sourceOfFunds.provided.card.scheme
)を確認して、サポートされているカードタイプのリストと照合し、そのカードタイプが受け入れられない場合はエラーメッセージを表示します。
支払者が CSC/CVV を提供していない場合、PaymentSession.updateSessionFromForm('card')
レスポンスで securityCode
フィールドが返されません。CSC/CVV が必要で、それらが提供されていない場合、支払者にエラーを表示する必要があります。
以下のオペレーティングシステムおよびブラウザで、イベントのコールバックに問題があります。
- Windows 10 での Internet Explorer 11:
interaction.displayControl.formatCard=EMBOSSED
の場合、ホスト型フィールドの値が変更されてもonChange
イベントがトリガーされません。 - iPhone 6+ での iOS9 : 支払者がホスト型フィールドにデータを入力して、支払画面の別のフィールドに移っても、
onChange( )
イベントとonBlur( )
イベントがトリガーされません。また、支払者は支払画面でホスト型フィールドからその他のフィールドに移動することができません。逆も同様です。
API のバージョン 51 以降では、Hosted Session インタラクションで 1 枚以上のクレジットカードの支払詳細を収集できます。これにより、支払者は複数のクレジットカードを使用して 1 つの予約の支払いを行うことができます。ただし、各カードの支払詳細により別々の注文が生成されるため、それらの別々の注文を支払者の単一の予約に統合するのは加盟店側の責任になります。
各カードに対して一意のセッション識別子が作成されます。これを Web サーバに保存する必要があります。支払者はインタラクション中にカードを削除することができ、その場合、そのカードに関連付けられたセッションデータは Web サーバから削除されます。
<<hostedPaymentForm>> POST モデルは、Hosted Session JavaScript (session.js) のインテグレーションによって廃止されました。
既存の <<hostedPaymentForm>> POST インテグレーションについては、『インテグレーションガイドライン』と『API リファレンス』を参照してください。
<<hostedPaymentForm>> HPF.js JavaScript モデルは、Hosted Session JavaScript (session.js) のインテグレーションによって廃止されました。
既存の<<hostedPaymentForm>> HPF.js インテグレーションについては、『インテグレーションガイドライン』と『API リファレンス』を参照してください。