- インテグレーションガイドライン
- <<checkout>> のインテグレーションの実装
<<checkout>> のインテグレーションの実装
前提条件
必須:
加盟店プロファイルが <<checkout>> サービスで有効になっていることを確認します。有効になっていない場合は、サービスプロバイダにお問い合わせください。加盟店プロファイルで Hosted Checkout を有効にするには、Merchant Manager ポータルおよび『Merchant Manager ユーザガイド』を参照してください。任意指定:
支払いが正常に行われた場合、、電子メール /Webhook を通じて通知を受信できるように、通知サービスを選択することをお勧めします。このサービスを選択することで、ゲートウェイがユーザーに代わって支払者に電子メール通知を送信することができるようになります。ヒント:
Hosted Checkout 機能の統合プロセスを開始する前に、「ベストプラクティスとヒント」を参照してください。
<<checkout>> インタラクションのリクエスト
<<checkout>> インタラクションをリクエストするには、以下の手順に従います。
Initiate Checkout
操作を使用して、精算セッションをリクエストします。リクエストには支払いとインタラクションのデータ、および完了に関する指示を含める必要があります。Initiate Checkout
操作のカールスニペットのサンプルを以下に示します。Initiate Checkout のサンプルコードcurl https://qnbalahli.test.gateway.mastercard.com/api/nvp/version/72 \ -d "apiOperation=INITIATE_CHECKOUT" \ -d "apiPassword=$PWD" \ -d "apiUsername=merchant.<your_merchant_id>" \ -d "merchant=<your_merchant_id>" \ -d "interaction.operation=AUTHORIZE" \ -d "interaction.merchant.name=<your_merchant_name>" \ -d "order.id=<unique_order_id>" \ -d "order.amount=100.00" \ -d "order.currency=USD" \ -d "order.description=<description_of_order>"
API パスワードを生成する方法については、API パスワードの生成を参照してください。この操作に対する正常処理されたレスポンスには、
session.id
パラメータとsuccessIndicator
パラメータが含まれます。successIndicator
パラメータで返された値をショップシステムに保存して、支払いが成功したかどうかを検証できます。「支払結果の取得」を参照してください。- ゲートウェイサーバから checkout.min.js ファイルを照会します。これで、
Checkout
オブジェクトはグローバルな範囲に配置されます。チェックアウトファイルを照会するサンプルコード<script src="https://qnbalahli.test.gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
承認と購入の両方の取引タイプが有効になっている場合、<<checkout>> バージョン 52 以降を使用する必要があります。checkout.js 照会 [JavaScript]
- 返された
session.id
およびその他のリクエストパラメータが含まれている JSON オブジェクトを渡して、Checkout.configure()
を呼び出します。Checkout.configure() のサンプルコードCheckout.configure({ session: { id: '<your_initiate_checkout_ID>' }, interaction: { merchant: { name: 'Your merchant name', address: { line1: '200 Sample St', line2: '1234 Example Town' } } } });
Checkout.configure()
で渡されるデータは、Initiate Checkout
操作で提供されたデータを上書きすることはありません。 - 以下のいずれかを呼び出して、支払プロセスを開始します。
- 組み込まれたページで精算インタラクションを表示するには、以下を行います。
Checkout.showEmbeddedPage('#embed-target')
- <<hostedPaymentPage>> で精算インタラクションを表示するには、以下を行います。
Checkout.showPaymentPage()
- 組み込まれたページで精算インタラクションを表示するには、以下を行います。
チェックアウトインタラクションをリクエストする HTML コードのサンプル
<html> <head> <script src="https://qnbalahli.test.gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script> <script type="text/javascript"> function errorCallback(error) { console.log(JSON.stringify(error)); } function cancelCallback() { console.log('Payment cancelled'); } Checkout.configure({ session: { id: '<your_initiate_checkout_session_ID>' } }); </script> </head> <body> ... <div id="embed-target"> </div> <input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" /> <input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" /> ... </body> </html>
Checkout.configure()
で渡すことができます。- リテラル (例:
quantity : 300
) - 値を返す関数 (例:
quantity : function() { return 100 + 200 }
)。
関数は支払プロセスがトリガーされると実行されます。
モーダルチェックアウトインタラクションをシミュレートする HTML コードのサンプル
<html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous"> <title>Hello, world!</title> </head> <body> <h1>Hello, world!</h1> <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal"> Launch demo modal </button> <div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true"> <div class="modal-dialog" role="document"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="exampleModalLabel">Modal title</h5> <button type="button" class="close" data-dismiss="modal" aria-label="Close"> <span aria-hidden="true">×</span> </button> </div> <div class="modal-body" id="hco-embedded"> </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button> <button type="button" class="btn btn-primary">Save changes</button> </div> </div> </div> </div> <script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script> <script src="https://qnbalahli.test.gateway.mastercard.com/static/checkout/checkout.min.js" ></script> <script> // Configure Checkout first Checkout.configure({ session: { id: "SESSION123123123" } }) // after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded') $('#exampleModal').on('shown.bs.modal', function (e) { Checkout.showEmbeddedPage('#hco-embedded') }); </script> </body> </html>
Hosted Checkout の機能
コールバック
コールバックは、支払インタラクション中に発生する可能性があるイベントを処理するために提供されます。
コールバックの使用は任意ですが、checkout.js を照会する同じ <script>
タグの本文で必要なコールバックを定義する必要があります。
すべての定義されたコールバックは実装を含む必要があります。これらは関連するイベントがトリガーされると開始されます。
<script src="https://qnbalahli.test.gateway.mastercard.com/static/checkout/checkout.min.js" data-cancel="cancelCallback" data-beforeRedirect="Checkout.saveFormFields" data-afterRedirect="Checkout.restoreFormFields"> </script> <script> function cancelCallback() { confirm('Are you sure you want to cancel?'); // code to manage payer interaction } // or if you want to provide a URL: // cancelCallback = "someURL" </script>
コールバックメソッドには 2 つのタイプがあります。
基本コールバックは、次のイベントを処理するために提供されます。
cancel
:支払者が支払インタラクションをキャンセルした場合。コールバックのキャンセルは、支払画面でのみ使用でき、組み込まれた画面には使用できません。error
:エラーが発生した場合。complete
:支払者が支払インタラクションを完了した場合。timeout
:支払者が支払いを行うことができる期限内に、支払いが完了しなかった場合。
これらは関数または URL です。コールバックで関数の代わりに URL を提供した場合、イベントがトリガーされると、支払者はこの URL にリダイレクトされます。
<<checkout>>では、支払いを続行するために支払者を他の Web サイトにリダイレクトする必要がある支払インタラクション(PayPal など)がサポートされています。そのため、リダイレクトの前または<<checkout>>に戻った後に取引処理を確定するためにどのような処理を行うかを管理するコールバックが提供されています。
beforeRedirect
:支払者に支払インターフェイスが提示される前。afterRedirect
で使用するページの状態を復元するために必要なデータを返します。afterRedirect
:支払者が支払インタラクションの完了から戻ったとき。beforeRedirect
によって保存されるデータを使用して、保存された支払インターフェイスの状態を返します。
Checkout
オブジェクトは、beforeRedirect
コールバックと afterRedirect
コールバックの実装に役立つ 2 つの関数を提供します。
saveFormFields
:restoreFormFields
で使用する現在のすべてのフォームフィールドを保存します。beforeRedirect
の実装で使用するか、beforeRedirect
をCheckout.saveFormFields
として実装します。restoreFormFields
:saveFormFields
によって保存されるフォームフィールドを復元します。afterRedirect
の実装で使用するか、afterRedirect
をCheckout.restoreFormFields
として実装します。
checkout.js 照会 [JavaScript]
支払結果の取得
支払インタラクションが完了したら、支払者をショッピングサイトに戻し、独自のレシートページを支払者に提示できます。ショップシステムを更新して支払詳細を示すこともできます。
支払者をショッピングサイトに戻すには、次のいずれかを行う必要があります。
Initiate Checkout
操作でinteraction.returnUrl
を提供する。- <<checkout>> リクエストで
complete
コールバックを定義する。これはベーシックおよびリダイレクトのコールバックの両方に適用されます。「コールバック」を参照してください。
ゲートウェイは、resultIndicator
パラメータで次のいずれかの方法によって支払いの結果を送信します。
- 支払者をショッピングサイトに戻すために使用される URL (
interaction.returnUrl
) に付加する。 complete
コールバックで提供されている関数への入力パラメータとして指定するか、またはcomplete
コールバックで提供される URL に付加する。
resultIndicator
パラメータを、Initiate Checkout
レスポンスで返された successIndicator
パラメータと比較することにより、支払いの成功を判断できます。一致している場合は、支払いが成功したことを示します。
resultIndicator
パラメータでの値は、レシート番号としては使用できません。成功した場合、ショッピングサイトで支払者に支払レシートを提示し、ショップシステムを更新して支払詳細を示します。Retrieve Order
操作を使用してこれらを取得できます。
Merchant Administration 経由
支払詳細は、Merchant Administration の [注文と取引の詳細] ページに記録されます。支払いを検索し、その後の操作を行うこともできます。
<<reportingAPI>> の使用
<<reportingAPI>> を契約している場合は、<<checkout>> 支払データをフォーマットされたレポートとして QNB ALAHLI からダウンロードできます。
電子メールまたは Webhook の通知経由
Merchant Administration で電子メール通知を契約した場合、支払いが成功するたびに電子メール通知を受信します。
支払操作のカスタマイズ
<<checkout>> では、ビジネスに関する情報の表示および支払者とのインタラクションを Initiate Checkout
操作または Checkout.configure()
メソッドで制御できます。Initiate Checkout
リクエストで提供されたデータは、Checkout.configure()
メソッドで提供されたデータよりも常に優先されますので、ご注意ください。セキュリティを強化するため、Initiate Checkout
操作を使用したセッション内でデータを提供することをお勧めします。
URL | https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session |
HTTP メソッド | POST |
{ "apiOperation": "INITIATE_CHECKOUT", "interaction": { "operation": "AUTHORIZE" }, "order" : { "amount" : "122.0", "currency" : "USD", "description": "Ordered goods", "id": "232E32323ddd" } }
Checkout.configure({ session: { id: '<your_initiate_checkout_ID>' }, billing : { address: { street : '123 Customer Street', city : 'Metropolis', postcodeZip : '99999', stateProvince: 'NY', country : 'USA' } }, interaction: { merchant : { name : 'Your merchant name', address: { line1: '200 Sample St', line2: '1234 Example Town' }, email : 'order@yourMerchantEmailAddress.com', phone : '+1 123 456 789 012', logo : 'https://imageURL' }, locale : 'en_US', style: { theme: 'default' }, displayControl: { billingAddress : 'OPTIONAL', customerEmail : 'OPTIONAL', shipping : 'HIDE' } } });
interaction.merchant
パラメータグループで指定されたフィールドは、ホスト型支払画面インテグレーションのレシートページのみで表示され、埋め込まれた画面のレシートページには表示されません。次のオプションで支払操作をカスタマイズできます。
- ブランド情報の表示
ここにはロゴおよび連絡先の詳細が含まれます。
詳細については、以下を参照してください。
- 支払者への請求先および電子メールアドレスの表示の管理
支払者から請求先および電子メールアドレスを収集した後に、
interaction.displayControl.billingAddress
およびinteraction.displayControl.customerEmail
フィールドを次のいずれかに設定して、これらの情報を表示し、編集機能を制御できます。HIDE
:<<checkout>> でこれらのフィールドを表示しない場合。MANDATORY
:<<checkout>> でこれらのフィールドを表示し、支払者に対してデータ入力を必須にする場合。OPTIONAL
:<<checkout>> でこれらのフィールドを表示するが、支払者がデータを入力しないことを選択できるようにする場合。READ_ONLY
:<<checkout>> でこれらのフィールドを表示するが、支払者がフィールドを編集できないようにする場合。
- 発送先の詳細の表示の管理
支払者から発送先の詳細を収集した後に、
interaction.displayControl.shipping
フィールドを次のいずれかに設定することによって、これらの表示を制御できます。HIDE
:<<checkout>> でこれらのフィールドを表示しない場合。READ_ONLY
:<<checkout>> でこれらのフィールドを表示するが、支払者がフィールドを編集できないようにする場合。
支払者は以前提供された発送先の詳細を編集できません。
必要な発送先の詳細が指定されていない場合、[発送先住所と同じ] チェックボックスの機能は使用できなくなります。 - 言語とテーマの管理
デフォルトでは、<<checkout>>で表示される言語は支払者のブラウザによって決定されます。ただし、
locale
フィールドで言語の識別子または IETF 言語タグ (en_US
、es
、fr_CA
など) を指定することにより、この動作を上書きできます。指定する言語が QNB ALAHLI によってサポートされていない場合、<<checkout>> は最も一致する言語で表示されます。デフォルトでは、決済代行会社によってデフォルトとして設定されているテーマが <<checkout>> の外観と雰囲気を決定します。決済代行会社が複数のテーマをサポートする場合、リクエストで
interaction.style.theme
フィールドを提供することによって、デフォルトのテーマを上書きするように選択できます。この時点で使用できるテーマは
<<hppThemes>>
です。 - 注文 ID
<<checkout>> から開始された支払いを簡単に識別できるように、リクエストに
order.id
を含めることをお勧めします。買い物かごによって生成された識別子を使用するか、自分で識別子を指定できます。ただし、識別子が一意であることを確認してください。 - カード番号
支払者がカードを使用した支払いを選択した場合、支払者はチェックアウトのインタラクションで、クレジットカードまたはデビットカードの詳細を入力できます。ただし、アクワイアラーのうち少なくとも 1 社がコンボカード (デビットカードやクレジットカードのいずれにも使用できるカード) をサポートしている場合、支払者は支払画面 (デビットカードまたはクレジットカード) で支払方法を選択して、この支払いでカードが処理されるモードを指定する必要があります。
3D セキュア認証
Hosted Checkout インテグレーションで 3D セキュア認証を使用するには、決済代行会社に問い合わせて、加盟店アカウントに必要な特権を有効にしてください。
3D セキュア認証でインテグレーションが機能することをテストするには、本番環境でテスト用加盟店プロファイルを使用できます。
次のテストカードを使用して、インテグレーションのテストを行います
カードのタイプ | 認証ステータス | テストカード |
---|---|---|
Mastercard | 3DS2 - 検証 | 5123450000000008 |
Mastercard | 3DS1 - 3DS2 に未登録、3DS1 にフォールバック | 5506900140100305 |
Visa | 3DS2 - 検証 | 4440000009900010 |
Visa | 3DS1 - 3DS2 に未登録、3DS1 にフォールバック | 4508750015741019 |
認証に関する詳細情報については、「認証についてのよくある質問」を参照してください。
EMV 3DS を有効にする
EMV 3D セキュア (EMV 3DS) は、加盟店や発行者が非対面取引を認証できるように設計されたグローバルな業界標準です。EMV 3D セキュア または EMV 3D セキュア 2.0 と呼ばれる EMVCo 業界標準の最新世代は、現在のバージョン (3D セキュア 1) よりも堅牢なプロトコルと強力な認証機能を備えています。EMV 3DS を有効にすることで、詐欺、誤判定、不要な摩擦を減らし、デジタル支払操作を向上させます。
加盟店の前提条件 (インドおよびバングラデシュのみ)
- 加盟店のアクワイアラーは、アクワイアラーの前提条件を完了する必要があります。
- アクワイアラーがサポートする各スキームについて、支払ゲートウェイの加盟店プロファイルで追加の設定が必要です。
- Mastercard、Visa、Amex には別途、加盟店特権が必要です。この特権は、Merchant Manager ポータル内の [加盟店プロファイル] ページ > [支払い詳細情報] ページ > [カード所有者検証] セクションで設定することができます。
加盟店インテグレーション
- Web サービス API (WS-API) v57 以降と統合します。
- 以下のヘルプページに記載されている手順に従います。
- Admin > インテグレーション設定 > Hosted Checkout に進んで、Merchant Administrator 経由で EMV 3DS を有効にします。
WCAG (Web Content Accessibility Guidelines)コンプライアンスの実現
WCAG 2.0 Level AA に準拠したユーザーエクスペリエンスを提供するように、<<checkout>>を設定できます。『WCAG 2.0 ガイドライン』を参照して、Web サイトがこの技術標準に準拠するようにします。
言語属性を設定します
言語属性を HTML 要素に追加します。
<html lang="en"> <head></head> <body></body> </html>
支払区分の提示
加盟店プロファイルで支払区分が設定されている場合、デフォルトでは、加盟店設定でのすべての支払区分は <<checkout>> 時に支払者に提示されます。ただし、支払者が使用できる支払区分は、支払者が入力したカード番号と注文での通貨によって決定されます。
取引ごとに支払区分に制約を設けて、オファーで使用できる支払区分を制限できます。支払者に提示された支払方法が事前に定義された基準に適合していることを確認し、支払者が支払区分データを改ざんした場合に支払プロセスを実行できないようにする場合に役立つ機能です。リクエストで次のフィールドを使用して、制約を指定できます。
constraints.paymentPlans.supported[n]
:この取引に対して提示される支払区分。constraints.paymentPlans.numberOfPayments
:支払区分で許可されている分割払い回数。constraints.paymentPlan.numberOfDeferrals
:支払区分で許可されている猶予期間の月数。
デフォルトでは、支払区分の支払条件 (使用できる場合) は、<<checkout>> に表示されます。Checkout.configure()
で interaction.displayControl.paymentTerms=HIDE
を設定すると、支払条件を非表示にできます。
支払詳細の検証のサポート
ギフトカード、および<<ach>>での支払いでは、<<checkout>>のみが支払詳細の検証をサポートしています。
Initiate Checkout リクエストで interaction.operation=VERIFY
を設定すると、この機能を使用することができます。
<<checkout>> では、設定されたアクワイアラーによってサポートされた検証方法とリクエストで提供されたデータを使用します。
resultIndicator
と successIndicator
を比較することにより、検証操作の成功を確認できます。
インタラクションが成功しなかった場合、<<checkout>> では検証が失敗したことを示すメッセージが表示され、支払者に再度試みるように求めます。
非 E コマースのインテグレーションのサポート
加盟店プロファイルに取引ソース (インターネット、コールセンター、電話注文など) が設定された <<checkout>> を使用できます。
Initiate Checkout リクエストで transaction.source
を指定すると、この機能を使用することができます。
<<checkout>> が INTERNET
以外の transaction.source
でリクエストされた場合、支払者が関与する必要がある支払方法はサポートされません。
リクエストで transaction.source
を提供しない場合:
- 加盟店アクワイアラーリンクでサポートされていない場合、デフォルトでは
INTERNET
になります。 - サポートされていない場合、デフォルトでは加盟店プロファイルの取引ソースになります。
カードのセキュリティコードの管理
Initiate Checkout リクエストの interaction.displayControl.cardSecurityCode
を次のいずれかの値に設定すると、支払いを処理するために支払者がカードのセキュリティコードを提供する必要があるかどうかを管理できます。
OPTIONAL
:<<checkout>>にカードのセキュリティコード入力フィールドを表示するようにするが、このフィールドへの入力が必須でない場合。MANDATORY
(デフォルト):<<checkout>> にカードのセキュリティコード入力フィールドを表示し、入力を必須にする場合。
セキュリティ機能のバイパス
3D セキュア認証またはリスク管理サービスを設定している場合、希望すれば、これらをバイパスすることを選択できます。
- 支払認証のバイパス: Initiate Checkout リクエストに
interaction.action.3DSecure=BYPASS
を設定します。 - BYPASS:支払者に 3DS 認証を提供しないこと。
- MANDATORY:3DS 認証が可能な場合、支払者に提供する。
- リスク評価のバイパス: Initiate Checkout リクエストに
risk.bypassMerchantRiskRules=ALL
を設定します。
CREATE_CHECKOUT_SESSION
リクエストにある interaction.action.3DSecure
フィールドには、以下の値を取ることができます。
インテグレーションのテスト
実際の取引処理を開始する前に、正しく機能することを確認するためにインテグレーションをテストする必要があります。
トラブルシューティングと FAQ
<<checkout>>では、いくつかのインテグレーションエラーが返される可能性があります。「インテグレーションのテスト」を参照してください。
エラーページは、間違った <<checkout>> リクエストが行われたときに表示されます。よくあるエラーの原因は次のとおりです。
- 必須フィールドが指定されていない。
- リクエストで指定された URL が絶対ではない。
支払者が [支払い] ボタンを二重に送信した場合、取引はお客様自身の銀行または支払者の銀行との間で繰り返し処理されません。
はい、Edge 18 はサポートされています。
ベストプラクティスとヒント
ゲートウェイに認証する必要があるため、<<checkout>> モデルは安全です。支払画面で収集された支払詳細は、支払者のブラウザからゲートウェイに直接送信されます。
ファイルサイズやロゴの幅に制限はありません。高さについて、推奨される最小値は 144 px です。
はい。あらゆるプロバイダでロゴの画像をホスティングできますが、URL が安全であること (HTTPS) が必須です。ホスト型プロバイダが安全な URL をサポートしていない場合、次の URL で HTTPS ホスティングを無料で提供できるプロバイダのリストをご覧ください。https://www.google.com.au/search?q=secure+image+hosting+providers
このチェックボックスは、発送先住所のすべての必要なフィールドが入力された場合にのみ表示されます。支払者がこれらのフィールドへの入力を完了したこと、または入力されていないフィールド(商品が国際便で発送されない場合の shipping.country
など)があることを確認する必要があります。
モバイルでの <<checkout>> 利用の最適化など、お客様により良いモバイル体験を提供したいときは、サイトのページに meta タグ 'viewport' を追加することをお勧めします。次に例を示します。
<meta name="viewport" content="width=device-width, initial-scale=1">
ページに合わせて適切な viewport 値を選択すること、また、変更をサイトでテストしてみることが重要です。