- インテグレーションガイドライン
- サポートされている機能(支払方法)
- ブラウザ経由の支払いのインテグレーションの実装
- PayPal での支払い
PayPal での支払い
PayPal は、QNB ALAHLI でサポートされているブラウザ経由の支払方法です。 このページでは、ゲートウェイ経由の支払いを受け入れるための PayPal ビジネスアカウントの設定方法、ブランディング要件などの、PayPal に固有のインテグレーションの詳細について説明します。PayPal インテグレーションを構築する前に、「ブラウザ経由の支払いのインテグレーションガイドライン」を読んでおくことをお勧めします。
<<webServicesIntegration>> バージョン 50 より前のバージョンを統合して PayPal を使用する場合は、ここをクリックしてください。
前提条件
PayPal をQNB ALAHLIを介した支払方法として使用するには、ゲートウェイに対して PayPal ビジネスアカウントが設定されている必要があります。 詳細については、「PayPal ビジネスアカウントの設定」を参照してください。
PayPal ビジネスアカウントに登録するには、ここをクリックしてください。
PayPal チェックアウト操作
次のセクションは、サイトに最適な PayPal チェックアウト操作を選択するのに役立ちます。
PayPal を使用すると、支払者が利用者のサイトで迅速かつ安全にチェックアウトすることができ、支払いに PayPal の口座を使用し、必要に応じて発送先情報をサイトに提供することができます。 PayPal では、支払者が加盟店のサイトでチェックアウトプロセスを開始して完了します。
ゲートウェイでは、PayPal によるチェックアウトと PayPal による支払いという 2 種類の PayPal チェックアウトフローがサポートされています。
PayPal によるチェックアウトフローでは、ショッピングサイトのカード確認ページで [PayPal によるチェックアウト] を経由して、支払者をユーザーのサイトから PayPal にリダイレクトできます。
- 支払者は通常のチェックアウトフローをバイパスし、PayPal アカウントに保存されている情報を使用してチェックアウトします。
- PayPal は、支払者のアカウントから、名前、メールアドレス、発送先住所を提供します。 このアクションにより、より高速なチェックアウトが可能になります。
- PayPal は PayPal で支払者から発送先住所を収集します。支払者はこの情報を必要に応じて追加または編集できます。
- 注文の詳細を検証した後、支払者は [続行] ボタンを選択します。
- 確認のため、支払者は支払画面にリダイレクトされます。
- 必要に応じて、支払いを承諾する前に注文を変更できます (たとえば、PayPal から返された住所に基づいて配送料および手数料を追加するなど)。
チェックアウトフローのサンプル
以下の図は PayPal によるチェックアウトフローを表しており、支払者は PayPal に保存されている発送先住所を使用しています。 支払者は加盟店のサイトで支払内容を参照して確認します。
チェックアウトフローは以下のとおりです。
- 支払者は加盟店のサイトを参照し、製品を選択して、チェックアウトページで [PayPal によるチェックアウト] をクリックします。
- 支払者が [PayPal によるチェックアウト] ボタンをクリックした場合、
Initiate Browser Payment
呼び出しがゲートウェイに送信され、レスポンスで返された PayPal の URL に支払者がリダイレクトされます。 - ゲートウェイは支払者を PayPal のページにリダイレクトします。
- 支払者は PayPal ログインページを使用して PayPal アカウントにログインします。
- 支払者は発送先住所を指定します。 支払者は PayPal に既に保存されている発送先住所を選択することも、新しい住所を入力することもできます。
- 支払者は PayPal で資金源を選択し、"[続行]" ボタンをクリックして支払いを続行します。
- 支払者はゲートウェイを経由して PayPal からサイトにリダイレクトされました。
Retrieve Transaction
操作を使用して、支払者のアカウントの電子メールアドレスおよび発送先住所を含む取引の詳細を取得します。 - この情報に基づいて確認用ページが支払者に表示されます(たとえば配送料および手数料が追加される場合など)。 支払者が [今すぐお支払い] ボタンをクリックして支払いを処理した場合、
Confirm Browser Payment
呼び出しがゲートウェイに送信されます。支払者は、[今すぐお支払い] ボタンをクリックする前に発送先住所を更新できます。 - ゲートウェイは取引詳細を含むレスポンスを送信します。これは、支払いの成功または失敗を示しているため、支払者にステータスを表示することができます。
{ "apiOperation":"INITIATE_BROWSER_PAYMENT", "browserPayment":{ "operation":"AUTHORIZE", "paypal":{ "paymentConfirmation":"CONFIRM_AT_MERCHANT" }, "returnUrl":"Https://test.com" }, "order":{ "amount":"4.20", "currency":"USD" }, "sourceOfFunds":{ "type":"PAYPAL" } }
PayPal による支払いフローでは、支払者が通常のチェックアウトフローを進めながら、請求先と発送先の情報をサイトに入力します。 支払者に支払方法の選択が求められたら、支払者はサイトの請求ページに指定された PayPal オプションおよびその他の支払方法を選択します。 PayPal によるチェックアウト取引とは異なり、サイトは支払者の発送先住所を PayPal に提供します。 デフォルトでは、PayPal で発送先住所が表示されないようにしたり、編集を無効にしたりすることを選択できます。 これを PayPal インテグレーションで実装する方法の詳細については、下記の「発送先住所の表示/上書き」を参照してください。 [今すぐお支払い] ボタンを使用すると、支払者はサイトにリダイレクトされる前に PayPal で支払いを確認できます。 このオプションでは、支払者が PayPal で支払いを完了するため、より迅速なチェックアウトの操作が可能になります。
チェックアウトフローのサンプル
以下の図は PayPal による支払いフローを表しており、支払者は PayPal で支払いを確認および確定しています。
チェックアウトフローは以下のとおりです。
- 支払者は加盟店のサイトを参照し、製品を選択して、チェックアウトページで [PayPal] をクリックします。
- 支払者が [PayPal] ボタンをクリックした場合、
Initiate Browser Payment
呼び出しがゲートウェイに送信され、レスポンスで返された PayPal の URL に支払者がリダイレクトされます。 - ゲートウェイは支払者を PayPal のページにリダイレクトします。
- 支払者は PayPal ログインページを使用して PayPal アカウントにログインします。
- 支払者は請求情報の詳細を確認し、PayPal で [今すぐお支払い] ボタンをクリックして支払いを確定します。
- ゲートウェイは取引詳細を含むレスポンスを送信します。これは、支払いの成功または失敗を示しているため、支払者にステータスを表示することができます。
{ "apiOperation":"INITIATE_BROWSER_PAYMENT", "browserPayment":{ "operation":"PAY", "paypal":{ "paymentConfirmation":"CONFIRM_AT_PROVIDER" }, "returnUrl":"Https://test.com" }, "order":{ "amount":"4.20", "currency":"USD" }, "sourceOfFunds":{ "type":"PAYPAL" } }
PayPal によるチェックアウトと PayPal による支払いの両方のチェックアウトフローで、[今すぐお支払い] ボタンまたは [続行] ボタンを PayPal に表示するよう選択できます。
[今すぐお支払い] ボタンを使用すると、支払者はサイトにリダイレクトされる前に PayPal で支払いを確認できます。 このオプションでは、支払者が PayPal で支払いを完了するため、より迅速なチェックアウトの操作が可能になります。
[続行] ボタンを使用すると、支払者はサイトにリダイレクトされ、すべての注文の詳細を参照した後に支払いを確認します。 このオプションでは、支払いを承諾する前に必要に応じて注文を変更することができます(たとえば、PayPal から返された住所に基づいて配送料および手数料を追加するなど)。 または、他のチェックアウト手順を含めることもできます(たとえば、注文確定ページでのアップセリングなど)。
これを PayPal インテグレーションで実装する方法の詳細については、以下の「支払いの確認」を参照してください。
PayPal によるチェックアウトと PayPal による支払いのどちらのチェックアウトフローを使用するかに応じて、それぞれ加盟店のサイトまたは PayPal から支払者の発送先住所を収集するように選択できます。 デフォルトでは、PayPal は PayPal で支払者から発送先住所を収集します。支払者はこの情報を必要に応じて追加または編集できます。 発送先住所が表示されないようにしたり、編集を無効にしたりすることを選択できます。 これを PayPal インテグレーションで実装する方法の詳細については、下記の「発送先住所の表示/上書き」を参照してください。
PayPal インテグレーション
<<checkout>> のチェックアウトオプションとしての PayPal
QNB ALAHLI 支払画面 (<<checkout>>) を使用している場合、your payment service provider が加盟店プロファイルに PayPal アクワイアラーリンクを設定していれば、PayPal が支払者に対して自動的にチェックアウトオプションとして提供されます。 詳細については、「<<checkout>> インテグレーションによるブラウザ経由の支払い」を参照してください。
Create Checkout Session リクエストの送信時に API バージョン 50-59 をお使いの場合、支払者はサイトから PayPal にリダイレクトされ、ログイン後に支払詳細を完了します。
支払画面のチェックアウトオプションとしての PayPal
API バージョン 50 以降にインテグレーションされている場合、支払画面のチェックアウトオプションとして PayPal を追加できます。 PayPal インタラクションを開始するには、サーバ側アプリケーションから Initiate Browser Payment
リクエストを送信する必要があります。
支払者はサイトから PayPal にリダイレクトされ、ログイン後に支払詳細を完了します。 詳細については、「Direct Payment 経由の PayPal」を参照してください。
Direct Payment 経由の PayPal
Initiate Browser Payment リクエストの以下のフィールドは、PayPal に固有のフィールドか、PayPal インテグレーションで固有の使用方法があります。 その他の詳細については、「Direct Payment インテグレーションのブラウザ経由の支払い」を参照してください。
sourceOfFunds.type = PAYPAL
browserPayment.operation
=AUTHORIZE
またはPAY
PayPal では、承認が発生してから 3 日間、資金を保持できます(支払期間)。 3 日間経過した後に決済請求を処理する場合は、Update Authorization 操作を使用するか、Merchant Administration を経由して開始できます。
デフォルトでは、PayPal 加盟店アカウントは単一の決済請求のみに対して設定されています。 複数の決済請求をサポートするように設定を変更する必要がある場合は、PayPal にお問い合わせください。-
browserPayment.paypal.paymentConfirmation
PayPal による支払いを開始する場合、支払者が PayPal または利用者のサイトで支払いを確認するかどうかを利用者が指定する必要があります。
支払いの確認フィールド API リファレンス [REST][NVP]
プロバイダ (PayPal) で確認を行う場合、PayPal に ["今すぐお支払い"] ボタンが表示され、これにより支払者はサイトにリダイレクトされる前に PayPal で支払いを確認できます。 加盟店は
Retrieve Transaction
リクエストを QNB ALAHLI に送信して、支払いが成功したか失敗したかを判断する必要があります。サイトで確認を行う場合、PayPal に ["続行"] ボタンが表示され、これにより支払者が加盟店のサイトにリダイレクトされ、そこで支払いを確認できます。 利用者は
Retrieve Transaction
要求をゲートウェイに送信して、支払者が支払いを続行したかどうかについて詳細を取得する必要があります。 支払者がサイトで支払いを続行した場合、Confirm Browser Payment
呼び出しを送信して PayPal での支払いを確認する必要があります。Confirm Browser Payment
レスポンスには、支払いが成功したか失敗したかに関する情報が含まれています。Confirm Browser Payment API リファレンス [REST][NVP]
どちらの場合でも、支払いが成功していれば、Retrieve Transaction によって以下が返されます。
- 支払者の PayPal アカウントのメールアドレス
- 支払者の PayPal アカウントの口座所有者名
- 発送先住所の詳細
リクエストの例{ "apiOperation":"CONFIRM_BROWSER_PAYMENT", "order":{ "amount":"4.20", "currency":"USD" } }
-
[任意指定] 発送先住所を表示/発送先住所を上書き
支払者が発送先住所を提供する方法を以下の 2 つのフィールドを使用して管理できます。
browserPayment.paypal.displayShippingAddress
— true (デフォルト) に設定されている場合、発送先住所が PayPal に表示されます。browserPayment.paypal.overrideShippingAddress
— true (デフォルト) に設定されている場合、支払者は発送先住所を PayPal で変更できます。
デフォルトでは、PayPal は PayPal で支払者から発送先住所を収集します。 発送先住所を支払者からサイトで収集することを選択した場合、PayPal で発送先住所が支払者に表示されないようにするには、
browserPayment.paypal.displayShippingAddress
を false に設定する必要があります。 これは、発送先住所が注文に必要ない場合にも当てはまります (たとえば、デジタル製品のみの場合)。Initiate Browser Payment
リクエストで発送先住所が指定されている場合、またはbrowserPayment.paypal.displayShippingAddress
が true に設定されている場合、ゲートウェイは常にRetrieve Transaction
レスポンスで発送先住所を返します。インテグレーションに応じて適用される各種シナリオについては以下の表を参照してください。 支払い別に異なるシナリオを選択することができます。
Initiate Browser Payment PayPal 発送先住所を表示 発送先住所を上書き 発送先住所が必要か 発送先住所が提供されるか 発送先住所が有効か 発送先住所が支払者に表示されるか 表示される発送先住所の取得元 支払者は発送先住所を変更できるか 真 (デフォルト) 真 (デフォルト) 任意指定 いいえ 非該当 はい PayPal が発送先住所を収集します。 はい 真 (デフォルト) 真 (デフォルト) 任意指定 はい はい はい PayPal はリクエストに指定された発送先住所を PayPal に表示します。 はい 真 (デフォルト) 真 (デフォルト) 任意指定 はい いいえ はい PayPal は、リクエストに指定された発送先住所を無視し、代わりに PayPal で発送先住所を収集します。 はい 真 (デフォルト) 偽 必須 はい はい はい PayPal はリクエストに指定された発送先住所を PayPal に表示します。 いいえ 真 (デフォルト) 偽 必須 はい いいえ いいえ PayPal は要求を拒否します。 非該当 偽 非該当 非該当 はい はい いいえ PayPal はリクエストに指定された発送先住所を無視します。 いいえ 偽 非該当 非該当 非該当 非該当 いいえ PayPal には表示する発送先住所がありません。 非該当 すべてのシナリオで、発送先住所が PayPal で支払者によって変更された場合は、取引応答で返された発送先住所を使用する必要があります。 PayPal は米国の発送先住所に対して市、州、郵便番号の組み合わせを検証します。 -
[任意指定] 品目詳細
Initiate Browser Payment
要求で品目詳細を指定して、支払者が支払いを確認する前に注文のすべての詳細を支払者に提示できます。 消費者調査では、PayPal チェックアウトで個別の品目および注文の詳細を参照した場合のほうが購買を完了する可能性が高いことが示されています。 そのため、支払者が購買を取り消さずに支払いを続行するように促すために、PayPal チェックアウトを開始する場合には注文の情報を提供することをお勧めします。アイテムの名前および単価が指定されていれば、品目が提供されたとみなされます。 品目詳細については、「品目データ」を参照してください。
取引の結果の解釈方法
次の表に、ブラウザ経由の支払いを開始した後に発生する可能性があるシナリオでの取引応答コードを示しています。
Initiate Browser Payment レスポンス |
結果 |
---|---|
response.gatewayCode=SUBMITTED result=SUCCESS |
レスポンスで指定される URL を使用して支払者をリダイレクトします。 |
response.gatewayCode=SUBMITTED result=FAILURE or PENDING or UNKNOWN |
別の INITIATE_BROWSER_PAYMENT リクエストを送信します。 |
Retrieve Transaction/Retrieve Order レスポンス |
結果 |
response.gatewayCode=APPROVED result=SUCCESS |
支払いは正常に処理されました。 |
response.gatewayCode= PENDING result=PENDING |
支払いは、PayPal システムで確認の保留中です。 「保留中の支払い」を参照してください。 |
response.gatewayCode= CANCELLED result=FAILURE |
支払者が支払いのインタラクションをキャンセルしました。 支払者に他の支払方法を試すオプションを提示します。 |
response.gatewayCode= DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTED result=FAILURE |
支払いは PayPal によって拒否されました。 |
response.gatewayCode= ACQUIRER_SYSTEM_ERROR result=FAILURE |
アクワイアラーは取引を処理できませんでした。 支払いの失敗の理由をアクワイアラーに問い合わせるか、もう一度 RETRIEVE_TRANSACTION をやり直すことができます。 また、支払者に他の支払方法を試すオプションを提示することもできます。 |
response.gatewayCode= SYSTEM_ERROR result=FAILURE |
ゲートウェイは取引を処理できませんでした。 |
response.gatewayCode=TIMED_OUT result=FAILURE |
支払者と PayPal システムの間のインタラクションは正常に完了しませんでした。たとえば、ゲートウェイが 24 時間以内に加盟店から支払者のブラウザのリダイレクトを受け取らなかった場合や、ゲートウェイが支払者と PayPal システムの間のインタラクションの詳細を取得できなかったために支払いが不完全である場合などです。 |
response.gatewayCode=UNKNOWN result=UNKNOWN |
ゲートウェイは、支払いが正常に処理されたかどうかについて確認できませんでした。 |
承認の更新
Update Authorization 操作を使用するか、または Merchant Administration を経由して、承認の支払期間を更新したり、PayPal の有効な承認取引の承認金額を増額したりできます。 これをできるようにするには、your payment service provider で加盟店プロファイルの「承認の更新」特権が有効にされている必要があります。 詳細については、「Update Authorization」を参照してください。
当初の 3 日間(支払期間)の経過後、引き続き支払いを受けられるように承認を更新することをお勧めします。 再承認された支払いには新たに 3 日間の支払期間が設定されます。 3 日間の支払期間は、29 日間の有効期間内に最大 1 回更新できます。
承認の更新は、元の承認金額の最大 115% または $75 USD に 1 回更新できます。
決済請求、返金、および取消
PayPal による支払いでは、Capture 操作を使用するか、または Merchant Administration を経由して、承認金額を一部 決済請求できます。
Pay および Capture 取引で、PayPal 経由で処理された支払いを一部またはすべて返金することができます。 Refund 操作または Merchant Administration を使用して、Refund リクエストを送信できます。
決済請求の試行が失敗した場合は決済前の承認取引を取り消すか、Pay 取引を取り消して支払いをキャンセルすることができます。 Void 操作を使用するか、または Merchant Administration を経由して、取消リクエストを送信できます。
保留中の支払い
ゲートウェイが取引応答で PENDING のステータスを返すことがあります。 たとえば、取引が現在 PayPal でリスク評価中である場合などです。 ステータスが保留中である場合、加盟店が独自の不正管理フィルタを設定していれば、PayPal ビジネスアカウントにログオンして支払いを確認する必要があります。 PayPal は、保留中の取引のステータスが PayPal によって更新された場合はゲートウェイに通知します。
保留中の支払いを確認せず、拒否したい場合は、返金を開始できます。 Retrieve Transaction
操作を使用して、更新された取引の結果を取得できます。
請求契約と登録型決済
PayPal によるチェックアウトまたは PayPal による支払いを使用して、支払者の請求契約を設定できます。これにより、支払者から追加の同意を得なくても、その請求契約に対して照会取引(定額/定期または要求に応じた支払い)を開始できます。 詳細については、「請求契約と登録型決済」を参照してください。
PayPal インテグレーションの設定
このセクションでは、QNB ALAHLI で PayPal インテグレーションを設定する方法について説明します。 PayPal アカウントを作成したら、アカウント情報の詳細 (PayPal アカウント ID) を決済代行会社に提供、決済代行会社が PayPal 用のゲートウェイで加盟店プロファイルを設定できるようにする必要があります。
MSO は、Merchant Manager ポータルの [アクワイアラーリンクの詳細情報] セクションで、複数のアクワイアラーリンクを設定することができます。
PayPal を使用して取引を処理するには、Merchant Administration にログインして、QNB ALAHLI が加盟店用に送信する特定の API コールに対して QNB ALAHLI への権限を付与する必要があります。
[PayPal の設定] 画面が表示されると、MSO が設定した PayPal 加盟店アクワイアラーリンクが表示されます。 アクワイアラーリンクに第三者権限が付与されていない場合、[Account ID] フィールドは空欄になります。
新しいメールアカウントで PayPal API のサードパーティ権限を付与するには、以下を行います。
- 特定のアクワイアラーリンクにサードパーティ権限を与えるには、[有効化] を選択します。
- [PayPal サンドボックス] 画面に必要な情報を入力し、[次へ] を選択します。
- 必要な情報を入力し、[ユーザー契約、プライバシーに関する声明] チェックボックスを選択します。
- [TNS 社のテスト店] チェックボックスを選択します。
- [同意、アカウント作成] を選択します。
- ビジネス関連情報を入力し、[次へ] をクリックします。
- ユーザー関連情報を入力し、[送信] をクリックします。
登録確認ページに PayPal アカウントを有効にする手順が表示されます。
- 登録時に入力したメールアドレスに送信された手順に従い、PayPal アカウントを有効化します。
- [TNS 社のテスト店に戻る] を選択します。
特定の PayPal アクワイアラーリンクに必要なサードパーティ権限が付与されました。 ステータスが有効になり、PayPal アカウント ID が表示されます。
- サードパーティー権限を取り消すには [無効化] を、任意の情報を更新するには [更新] を選択します。
何らかの問題でサードパーティ権限に失敗した場合、エラーメッセージが表示されます。
登録済みのメールアカウントで PayPal API のサードパーティ権限を付与するには、以下を行います。
- 特定のアクワイアラーリンクにサードパーティ権限を与えるには、[有効化] を選択します。
- [PayPal サンドボックス] 画面に必要な情報を入力し、[次へ] を選択します。
- 資格情報を入力し、[ログイン] を選択します。
TNS 社のテスト店に PayPal を登録し、連携させることに成功しました。
- [TNS 社のテスト店に戻る] を選択します。
特定の PayPal アクワイアラーリンクに必要なサードパーティ権限が付与されました。 ステータスが有効になり、PayPal アカウント ID が表示されます。
- サードパーティー権限を取り消すには [無効化] を、任意の情報を更新するには [更新] を選択します。
何らかの問題でサードパーティ権限に失敗した場合、エラーメッセージが表示されます。
拡張売り手保護制度
Initiate Browser Payment
とその後の Tokenize Browser Payment
実行後の Pay または Authorize リクエストで支払者の追加データを送信することで、取引の処理前に PayPal に取引のリスク評価を行うことを許可できます。
PayPal は次のフィールドのデータを使用して取引前のリスク管理評価を実行します。
device.fingerprint
: PayPal FraudNet Javascript ライブラリを使用して生成できる、デバイスの一意の識別子。 これにより、PayPal は取引のリスク評価を実行できるようになります。risk.custom
: 支払いに関する追加データをこのフィールドに入力できます。 提供する値については、PayPal と契約を締結している必要があります。risk.custom.headOfficeLocation
=London UK など。sourceOfFunds.token
: ゲートウェイで PayPal から受け取った、請求契約の詳細を識別するトークン ID。 このトークン ID を、1 回限りの支払いと登録型決済に使用できます。 詳細については、「請求契約と登録型決済」を参照してください。
超過返金
PayPal サイトでは、超過返金を有効にする必要があります。 Capture リクエスト、または Merchant Administration を通じて、超過した承認金額を決済請求できます。
元の承認取引の最大 115% の超過決済請求が許可されています。 Pay および Capture 取引で、PayPal 経由で処理された超過分の支払いを返金できます。
Refund 操作または Merchant Administration を経由して、Refund リクエストを送信できます。
超過返金の場合、元の取引金額を超えた金額を含めます。 決済請求金額を超過して返金する場合、PayPal 加盟店プロファイルで超過返金が有効になっていることを確認します。
PayPal プロファイルで超過返金が有効になっている場合、QNB ALAHLI 加盟店プロファイルについても同様に設定していることを確認してください。
PayPal インテグレーションにおけるセキュリティのベストプラクティス
セキュリティのベストプラクティスについては、ここをクリックしてください。
インテグレーションのテスト
QNB ALAHLI では PayPal シミュレーターが提供されています。これを使用して、ゲートウェイ経由で PayPal 機能を使用するためのインテグレーションをテストできます。