- インテグレーションガイドライン
- サポートされている機能(支払方法)
- ブラウザ経由の支払いのインテグレーションの実装
- PayPal
- PayPal JS SDK へのゲートウェイのインテグレーション
PayPal JS SDK へのゲートウェイのインテグレーション
このガイドは、ゲートウェイから提供された PayPal の JavaScript SDK をインテグレーションすることによって、支払画面に PayPal スマートボタンを追加する方法を説明します。
前提条件
支払者に対して PayPal スマートボタンをチェックアウトオプションとして提供するには、ゲートウェイの PayPal JavaScript SDK を使用して以下を行ないます。
- your payment service provider が加盟店プロファイルで PayPal を有効にしたことを確認します。
- Merchant Administration の [Admin] メニューで [PayPal 設定] をクリックして、PayPal にオンボーディングする手順に従って加盟店プロファイルに対して PayPal をアクティブにします。PayPal 設定を更新するには、必須の特権が必要です。
ゲートウェイの PayPal JavaScript SDK を使用したスマートボタンの追加
以下に説明された手順に従って、ゲートウェイの PayPal JavaScript SDK へのインテグレーションを構築します。
手順 1: セッションの作成
ゲートウェイの PayPal JavaScript SDK は、セッションベースの認証を使用します。セッションを作成して、保存するリクエストフィールドと値を更新します。
セッションを作成するには、サーバ側アプリケーションから Create Session リクエストを送信します。レスポンスは、後の手順でこのセッションを参照する必要のあるセッション ID を返します。
URL | https://qnbalahli.test.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
HTTP メソッド | POST |
手順 2: 注文、取引、ブラウザ経由の支払いの詳細でのセッションの更新
サーバ側アプリケーションから Update Session リクエストを送信することで、注文金額および通貨でセッションを更新します。
サーバ側アプリケーションから Update Session リクエストを送信することで、少なくとも注文 ID、取引 ID、注文金額、通貨、ブラウザ経由の支払いの詳細 (支払確認) でセッションを更新します。
browserPayment.returnUrl
の提供は任意です。PayPal スマートボタンのインタラクションが作動する上では必須ではありません。URL | https://qnbalahli.test.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
HTTP メソッド | PUT |
{ "apiOperation": "UPDATE_SESSION", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }
手順 3: 支払画面にゲートウェイ PayPal JS SDK を含める
支払画面で、head 要素に script
要素を追加することにより、ゲートウェイの PayPal JavaScript SDK (gateway-paypal.js) を含めます。これで、GatewayPaypal
オブジェクトはウィンドウネームスペースに配置されます。
<script type="text/javascript" src="https://qnbalahli.test.gateway.mastercard.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
手順 4: ゲートウェイ PayPal インタラクションの設定
支払画面をロードする際に、GatewayPaypal.configure (config, errorCallback, completeCallback, cancelCallback) を起動することで PayPal インタラクションを開始します。これにより、支払画面がゲートウェイ PayPal メソッドの configure.html にリダイレクトされます。
function errorCallback(error) { }; function completeCallback(response) { }; function cancelCallback(response) { }; var config = { merchantId: '<your_gateway_merchant_ID>', // required orderId: '<order_ID>',//required and must match the value provided in Step 2 transactionId: '<transaction id>',// required and must match the value provided in Step 2 sessionId: '<your_session_ID>',// required currency: '<order_currency>', // required paymentConfirmation: '<confirmation_of_payment>', // optional, must be one of CONFIRM_AT_PROVIDER (if you want the payer to commit to the payment on the PayPal website) or CONFIRM_AT_MERCHANT (if you want the payer to commit to the payment on your website). If not provided, the value is defaulted to "CONFIRM_AT_PROVIDER". operation: '<type_of_transaction>', // required, must be one of AUTHORIZE (transaction created in the gateway is an AUTHORIZATION transaction) or PAY (transaction created in the gateway is a PAYMENT transaction). For a successful Authorization transaction, submit a CAPTURE request to move the funds from the payer's account to your account. apiVersion: '',// optional, Must be version 60 or above. If not provided, the value is defaulted to 60. buttonElement: '',// required style: {// Style options for customizing the PayPal Smart Button. color: '<color_of_the_button>', // optional, must be one of "gold" (Recommended by PayPal), "blue", "silver", "white", "black" shape: '<shape_of_the_button>', // optional, must be one of "rect", "pill". If not provided, the value is defaulted to "rect". label: '<label_on_the_button>', // optional, must be one of "paypal", "checkout", "buynow", "pay". If not provided, the value is defaulted to "paypal". tagline: '<tagline_to_be_displayed>', // optional, must be one of "true", "false". If not provided, the value is defaulted to "true". size: '<size_of_the_button>' // optional. If not provided, the value is defaulted to the size of its container element. To customize the button width, alter the width of the container element. To customize the button height, set the height option to a value from 25 to 55. } }; GatewayPaypal.configure(config, errorCallback, completeCallback, cancelCallback);
merchantId
merchantId
は必須です。これにより、ゲートウェイは支払方法を正しく決定できます。
apiVersion
SDK apiVersion
は、Create Session リクエストを送信する間に使用されるバージョンと一致する必要があります。例えば、セッションを作成している間に apiVersion
61 を使用すると、その他すべての関連する設定に同じ apiVersion
が使用されるようにします。apiVersion
に不一致があると、操作は失敗します。
apiVersion
は 61 です。apiVersion
に値を提供しない場合、デフォルト値が考慮されます。buttonElement
画面のボタンの位置を決定します。ボタンがどの場所に表示するかを示す DOM 要素の識別子です。
paymentConfirmation
チェックアウトフローのどの場所で支払者が支払いを確定するのかを示します。これはユーザーの Web サイトでも PayPal でもどちらでも構いません。
エラーレスポンス
GatewayPaypal.configure()
コールは、以下のエラーレスポンスを返す場合があります。
response.cause | resp.explanation | アクションが必要 |
---|---|---|
エラー | 引数なし:Merchant ID、Hosted Session ID、Payment Confirmation、Button Element、3 つのコールバック機能はすべて configure() メソッドで必要な引数です。 | インテグレーションを修正してください。すべての必須フィールドに値を指定します。 |
エラー |
|
正しい関数を指定することにより、インテグレーションを修正します。 |
エラー | API バージョンは <MIN_VERSION> 以降を使用する必要があります。 | インテグレーションを修正してください。apiVersion を 60 以降に設定してください。 |
支払いの確認
PayPal によるチェックアウトと PayPal による支払いの両方のチェックアウトフローで、[今すぐお支払い] ボタンまたは [続行] ボタンのいずれかを PayPal のページに表示するよう選択できます。
PayPal での支払いの確認
CONFIRM_AT_PROVIDER
を送信することで、[今すぐお支払い] ボタンは PayPal のモーダルに表示されるようになります。[今すぐお支払い] ボタンで、支払者は PayPal モーダルで支払いを確定できるようになります。このオプションでは、支払者が PayPal で支払いを完了するため、より迅速なチェックアウトの操作が可能になります。
支払者が PayPal サイトで支払いを確定した場合、Retrieve Transaction または Retrieve Order リクエストをゲートウェイに送信して、取引結果を検証できます。その後、最新の詳細と併せて [支払完了] ページを表示できます。
回復の拒否
回復の拒否は、PayPal の使用でのみサポートされています。取引処理中に手段が拒否された場合、支払者は支払いを行うためにあと 2 回試行することができます。3 回すべての試行について、支払者は PayPal に登録されているものと同じまたは異なる手段で支払いを処理することができます。新しい手段の場合、支払者は支払いを処理する前に PayPal に登録する必要があります。支払者は、支払いを行うために合計 3 回試行できます。3 回目の試行の後に手段が拒否された場合であっても、your payment service provider は TRANSACTION_REFUSED
または INSTRUMENT_DECLINED
レスポンスを送信します。これ以降、支払者は取引プロセスを続行できなくなります。
回復の拒否中のイベントのシーケンス
- browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER を使用して、ゲートウェイに Initiate Browser Payment リクエストを送信します。
PayPal の支払フォームが表示されます。
- 支払者が PayPal の支払フォームにログインして、決済手段を選択し、[今すぐお支払い] をクリックします。
- Confirm Browser Payment リクエストを送信して、PayPal の支払実行リクエストを呼び出します。
- 手段が拒否された場合であっても、PayPal は
INSTRUMENT_DECLINED
レスポンスを支払実行リクエストに送信します。支払者は、支払いを行うために合計 3 回試行できます。
- onApprove イベントハンドラは INSTRUMENT_DECLINED レスポンスを受領すると、actions.restart() 関数をコールして支払者が別の手段を選択できるようにします。
const restartPaymentOnInstrumentDeclined = (resp, actions) => { if (isInstrumentDeclined(resp)) { return actions.restart(); } else { gatewaySuccessCallbackBP(resp); } }
{ "browserPayment": { "interaction": { "status": "INITIATED", "timeInitiated": "2021-07-15T07:10:16.176Z" }, "operation": "PAY", "paypal": { "displayShippingAddress": true, "interactionId": "EC-9SH774983H4356451", "overrideShippingAddress": true, "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "PP_POI_1", "order": { "amount": 931, "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2021-07-15T07:10:16.152Z", "currency": "USD", "id": "vcc-206", "item": [ { "brand": "MC", "category": "NA", "detail": { "unitDiscountRate": 0 }, "name": "name", "quantity": 1, "sku": "sku", "unitDiscountAmount": 0, "unitPrice": 931 } ], "itemAmount": 931, "lastUpdatedTime": "2021-07-15T07:12:19.571Z", "merchantAmount": 931, "merchantCurrency": "USD", "reference": "my order", "status": "INITIATED", "taxAmount": 0, "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "INSTRUMENT_DECLINED", "acquirerMessage": "", "debugInformation": "INSTRUMENT_DECLINED, The instrument presented was either declined by the processor or bank, or it can't be used for this payment., e5a837ee6834", "gatewayCode": "SUBMITTED" }, "result": "SUCCESS", "shipping": { "address": { "city": "Los Angeles", "company": "Google", "country": "USA", "postcodeZip": "90001", "stateProvince": "CA", "street": "2nd Main", "street2": "lane 2" }, "contact": { "email": "ramakanth@gmail.com", "firstName": "Ramakanth", "lastName": "Kulkarni", "mobilePhone": "9999999999", "phone": "9999999999" } }, "sourceOfFunds": { "provided": { "paypal": { "accountEmail": "CCREJECT-REFUSED@paypal.com", "accountHolder": "Paul Levetsky", "payerId": "LM9AM5Y34N3X8" } }, "type": "PAYPAL" }, "timeOfLastUpdate": "2021-07-15T07:12:19.571Z", "timeOfRecord": "2021-07-15T07:10:16.171Z", "transaction": { "acquirer": { "date": "15 Jul 2021", "id": "PAYPAL", "merchantId": "NDXE9MFKNPCUA", "time": "07:12:19" }, "amount": 931, "currency": "USD", "id": "1", "source": "INTERNET", "stan": "0", "type": "PAYMENT", "update": [ { "gatewayCode": "SUBMITTED", "time": "2021-07-15T07:10:17.280Z" } ] }, "version": "62" }
{ "browserPayment": { "interaction": { "status": "COMPLETED", "timeCompleted": "2021-07-20T09:17:27.128Z", "timeInitiated": "2021-07-20T09:15:56.313Z" }, "operation": "PAY", "paypal": { "displayShippingAddress": true, "interactionId": "EC-74C02380KE247305K", "overrideShippingAddress": true, "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "PP_POI_1", "order": { "amount": 1.28, "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2021-07-20T09:15:56.278Z", "currency": "USD", "description": "Ordered goods", "id": "testsdkhco33", "item": [ { "brand": "MC", "category": "NA", "name": "name", "quantity": 1, "sku": "sku", "unitPrice": 1.28 } ], "itemAmount": 1.28, "lastUpdatedTime": "2021-07-20T09:17:27.136Z", "merchantAmount": 1.28, "merchantCurrency": "USD", "reference": "my order", "status": "FAILED", "taxAmount": 0, "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "TRANSACTION_REFUSED", "acquirerMessage": "", "debugInformation": "TRANSACTION_REFUSED, The request was refused, cae635b964420", "gatewayCode": "DECLINED" }, "result": "FAILURE", "shipping": { "address": { "city": "Los Angeles", "country": "USA", "postcodeZip": "90001", "stateProvince": "CA", "street": "2nd Main", "street2": "lane 2" }, "contact": { "firstName": "Ramakanth", "lastName": "Kulkarni" } }, "sourceOfFunds": { "provided": { "paypal": { "accountEmail": "CCREJECT-REFUSED@paypal.com", "accountHolder": "Paul Levetsky", "payerId": "LM9AM5Y34N3X8" } }, "type": "PAYPAL" }, "timeOfLastUpdate": "2021-07-20T09:17:27.136Z", "timeOfRecord": "2021-07-20T09:15:56.308Z", "transaction": { "acquirer": { "date": "20 Jul 2021", "id": "PAYPAL", "merchantId": "NDXE9MFKNPCUA", "time": "09:17:27" }, "amount": 1.28, "currency": "USD", "id": "1", "source": "INTERNET", "stan": "0", "type": "PAYMENT", "update": [ { "gatewayCode": "SUBMITTED", "time": "2021-07-20T09:15:57.482Z" }, { "gatewayCode": "DECLINED", "time": "2021-07-20T09:17:27.128Z" } ] }, "version": "62" }
ショッピングサイトでの支払いの確認
CONFIRM_AT_MERCHANT
を送信することで、[続行] ボタンは PayPal のモーダルに表示されるようになります。
[続行] ボタンを使用すると、支払者はショッピングサイトにリダイレクトされ、PayPal モーダルとのインタラクションの完了後に支払いが確定されます。このオプションでは、支払いを承諾する前に必要に応じて注文を変更することができます(たとえば、PayPal から返された住所に基づいて配送料および手数料を追加するなど)。
支払者がユーザーのサイトで支払いを確定した場合、つまり、支払いの確認として CONFIRM_AT_MERCHANT
を使用した場合、支払いの確認画面が支払者に表示されます。Retrieve Transaction または Retrieve Order リクエストをゲートウェイに送信して、取引結果を検証できます。支払者が支払いの続行を判断したら、ゲートウェイに CONFIRM_BROWSER_PAYMENT
を送信して支払いを確定する必要があります。その後、最新の詳細と併せて [支払完了] ページを表示できます。 この操作を使用して、送料などの支払い属性を更新し、PayPal UI で支払者が選択した発送先詳細に反映します。
{ "apiOperation": "CONFIRM_BROWSER_PAYMENT", "order": { "amount": "779.99", "currency": "USD", "shippingAndHandlingAmount": "100.00" } }
取引の詳細情報の取得
PayPal インタラクションの取引詳細は、以下のオプションを通じて取得できます。
- Retrieve Order または Retrieve Transaction 操作
- Merchant Administration の注文と取引の検索:支払者に提供された支払レシートにある照会番号を使用して、取引詳細を参照できます。照会番号は支払者に提供され、銀行明細で確認できます。これにより取引をさらに検証できます。
注文と取引のステータスを理解する
browserPayment.paypal.paymentConfirmation が CONFIRM_AT_PROVIDER
ブラウザ経由の支払いのインタラクションステータス | 取引ゲートウェイ応答コード | 注文のステータス | 説明 |
---|---|---|---|
browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | INITIATE_BROWSER_PAYMENT 操作を使用して、取引が送信されました。 |
browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | 支払者は [今すぐお支払い] ボタンをクリックし、CONFIRM_BROWSER_PAYMENT リクエストが送信されました。 |
INSTRUMENT_DECLINED
を受領した場合、response.gatewayCode のステータスは「SUBMITTED」に、order.status は「INITIATED」になります。手段が支払いを行う最初の 2 回の試行で拒否された場合、このステータスはそのままになります。手段が 3 回目の試行で拒否された場合、取引は拒否され、response.gatewayCode および order.status のステータスはそれぞれ「DECLINED」および「FAILED」に変更されます。browserPayment.paypal.paymentConfirmation is CONFIRM_AT_MERCHANT
ブラウザ経由の支払いのインタラクションステータス | 取引ゲートウェイ応答コード | 注文のステータス | 説明 |
---|---|---|---|
browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | INITIATE_BROWSER_PAYMENT 操作を使用して、取引が送信されました。 |
browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | 支払者は PayPal で [続行] ボタンをクリックし、UPDATE_BROWSER_PAYMENT 操作が送信されました |
browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | CONFIRM_BROWSER_PAYMENT 操作が送信されました。 |
インテグレーションのテスト
PayPal に対するゲートウェイとのインテグレーションが完了すると、PayPal サンドボックスを使用してテストできます。
テストを開始するには、加盟店プロファイルを your payment service provider に設定する間に、PayPal にアカウントを作成し、その資格情報を使用します。これらの取引には、テストではない加盟店を使用するようにします。
- PayPal サンドボックスで作成した加盟店プロファイルを使用します。
- 前述の手順を使用してインテグレーションを行ないます。
- PayPal インテグレーションを Merchant Administration に設定し、第三者権限をゲートウェイに付与することでユーザーに代わって取引を行なえるようにしたことを確認します。