- インテグレーションガイドライン
- サポートされている機能(セキュリティ)
- RuPay 支払者認証
- RuPay JavaScript API を使用した RuPay 認証の実装
RuPay JavaScript API を使用した RuPay 認証の実装
このページでは、RuPay JavaScript (JS) API を用いて RuPay 認証を使用するためにゲートウェイとのインテグレーションを行う方法について説明します。
手順 1: セッションの作成と更新
Rupay JS は、セッションベースの認証を使用します。最初のステップとしてセッションを作成する必要があります。その後、セッションに保存するリクエストフィールドと値を更新できます。
Create Session コールを使用して、セッションを作成できます。これはサーバ側 API コールで、JS API とのインテグレーションの前提条件です。以下のフィールドを返します。
session.id
:一意のセッション識別子で、セッションの内容を参照するために後続のリクエストで提供する必要があります。session.authenticationLimit
:リクエストで指定した上限またはゲートウェイのデフォルト値。session.aes256Key
:支払者のブラウザやモバイル機器を経由して Web サイトに伝達された機密認証データを復号するために使用できる鍵。session.version
:このフィールドを使用して、セッションの内容のオプティミスティックロック機能を実装できます。session.updateStatus
:セッションの変更を最後に試みた結果の概要。
Create Session API リファレンス[REST][NVP]
Update Session コールを使用して、セッション内のフィールドを追加または更新できます。支払いと支払者データをセッションに追加すると、後に入力情報として、認証操作で支払者に関連するリスクを決定する際に使用することができます。セッションの中で、以下のフィールドが必要になります。
必須フィールド
- sourceOfFunds.provided.card.*:支払いに使用されるカードの詳細。
order.amount
- order.currency:注文の通貨。
- transaction.id:この支払認証用の一意の識別子。
- order.id:この注文用の一意の識別子。
authentication.channel
=PAYER_BROWSER
:認証リクエストが開始したチャネル。authentication.purpose
=PAYMENT_TRANSACTION
:支払者の認証がリクエストされたコンテキストを示します。authentication.redirectResponseUrl
:支払者認証プロセスが完了した後に支払者をリダイレクトする URL。
セッションからフィールドを削除することはできませんが、既存のフィールドの値を上書きすることができることにご注意ください。
手順 2: API を初期化します
ゲートウェイサーバから RuPay JS API (rupay.js
) を照会します。これで、rupay
オブジェクトはウィンドウ/グローバルなネームスペースに配置されます。
rupay.js Reference[JavaScript]
セッションの作成後、configure( )
メソッドを使用して API を初期化します。このメソッドは、ページのロード中、または DOM が準備完了の状態の時に行われる必要があります。これはページロードで 1 回だけ起動されなければなりません。このメソッドの起動後、RuPay JS はメンバー変数として設定値を入力します。
RuPay JS API は、configure()
メソッドで呼び出すことによって初期化できます。以下の必須フィールドがマップオブジェクトで引数になります。
merchantId
:ゲートウェイでの加盟店の識別子。sessionId
:Create Session コールを使用して、作成したセッション ID。containerId
:API が非表示の iframe を入れる HTML の中の <div> ID。callback
:API が初期化した後に起動する機能。configuration
:ユーザー言語 (オプション)、REST API バージョン (wsVersion) など、JSON 値がサポートするデータ要素。
<html> <head> <script src="https://qnbalahli.test.gateway.mastercard.com/static/rupay/1.0.0/rupay.js" data-error="errorCallback" data-cancel="cancelCallback"> </script> <script type="text/javascript"> //The output of this call will return 'false', since the API is not configured yet console.log(Rupay.isConfigured()); /** Configure method with the configuration{} parameter set and demonstrates the state change of the rupay object before and after the configure method is invoked. */ Rupay.configure({ merchantId: "TESTMERCHANT", sessionId: "SESSION0002899787259G30902270H6", containerId: "ABC", callback: function() { if (Rupay.isConfigured()) console.log("Done with configure"); }, configuration: { userLanguage: "en-US", wsVersion: 55 } }); </script> </head> <body> <div id="RupayUI"></div> </body> </html>
手順 3: 認証開始
すべての支払者と支払データがセッションに収集された後に、initiateAuthentication()
メソッドを起動することによって認証を初期化できます。加盟店が特定のカードに対して RuPay 支払者認証を利用できるかどうかを判断できるようにします。カードのタイプが RuPay の場合、ゲートウェイは RuPay カード BIN が電子商取引に対して使用可能であるかどうかを判断します。
initiateAuthentication()
メソッドの次の必須フィールドを指定することで、認証を開始できます。
- orderId:この注文用の一意の識別子。
- transactionId:この支払認証用の一意の識別子。
- コールバック:コールバック機能。
- optionalParams:(オプション) correlationId など、追加の Initiate Authentication REST API リクエストフィールドにある引数。
支払者の RuPay 認証を利用できる場合、コールバック機能の data
引数で以下のフィールドを返します。それ以外の場合は、応答にはエラーが含まれます。
data.restApiResponse
:Initiate Authentication REST API コールからの生のレスポンスを含みます。data.correlationId
:Initiate Authentication REST API コールを行う時に使用された、最後の相関 ID。レスポンスをリクエストに一致できるようになります。data.gatewayRecommendation
次の手順を決定するには、gatewayRecommendation フィールドに示されているゲートウェイの推奨事項を確認します。
gatewayRecommendation |
次の手順 |
---|---|
PROCEED | authenticatePayer( ) メソッドコールを使用して、支払者の認証に進むことができます。 |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 支払者に別の支払い方法(新しいカードや別の支払い方法など)を尋ね、新しい内容でリクエストを再度送信してください。同じリクエストを再度送信しないでください。 |
Rupay 認証の各種シナリオでの Initiate Authentication レスポンスを下表に示しています。
状況 | response.gatewayRecommendation |
transaction.authenticationStatus |
response.gatewayCode |
result |
---|---|---|---|---|
|
PROCEED | AUTHENTICATION_AVAILABLE | AUTHENTICATION_IN_PROGRESS | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
var optionalParams = { sourceOfFunds: { type: "CARD" }, order: { walletProvider: "MASTERPASS_ONLINE" } }; Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) { if (data && data.error) { var error = data.error; //Something bad happened, the error value will match what is returned by the Authentication API console.error("error.code : ", error.code); console.error("error.msg : ", error.msg); console.error("error.result : ", error.result); console.error("error.status : ", error.status); } else { console.log("After Initiate RuPay ", data); //data.response will contain information like gatewayRecommendation, authentication version, etc. console.log("REST API raw response ", data.restApiResponse); console.log("Correlation Id", data.correlationId); console.log("Gateway Recommendation", data.gatewayRecommendation); console.log("HTML Redirect Code", data.htmlRedirectCode); console.log("Authentication Version", data.authenticationVersion); switch (data.gatewayRecommendation) { case "PROCEED": authenticatePayer();//merchant's method break; case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS": tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method break; } } }, optionalParams);
手順 4: 支払者の認証
Initiate Authentication レスポンスが、RuPay カードに対して認証を利用できることを示している場合 (authentication.version=RUPAY)、authenticatePayer()
メソッドを起動できます。これは、支払者がチェックアウトページで [今すぐお支払い] ボタンをクリックしたときに起動します。
Authenticate Payer 操作では、カード番号などの必要な情報が、加盟銀行と RuPay PaySecure の間で安全に交換されます。PaySecure は一意の取引 ID (tran_ID)を返し、これが後続の Authorization または Pay 操作で使用されます。
次の必須フィールドを指定することによって、authenticatePayer()
メソッドを起動する必要があります。
orderId
:前に行われたinitiateAuthentication()
メソッドと同じ orderId。transactionId
:前に行われたinitiateAuthentication()
メソッドと同じ transactionId。callback
:コールバック機能。optionalParams
:(オプション)fullScreenRedirect
やbilling
など、追加の支払者の認証 REST API リクエストフィールドにある引数。
コールバック機能の data
引数で以下のフィールドを返します。
data.restApiResponse
:支払者の認証 REST API コールからの生のレスポンスを含みます。data.correlationId
:支払者の認証 REST API コールを行う時に使用された、最後の相関 ID。レスポンスをリクエストに一致できるようになります。data.gatewayRecommendation
data.htmlRedirectCode
:ゲートウェイは、支払者に表示した画面の入力用にこのフィールドを常に返します。
次の手順を決定するには、コールバックで返された gatewayRecommendation
フィールドに示されているゲートウェイの推奨事項を確認します。
gatewayRecommendation |
次の手順 |
---|---|
Proceed | 認証プロセスを完了するよう続行し (検証フロー)、または支払いを完了するよう続行することができます (円滑フロー)。 |
DO_NOT_PROCEED_ABANDON_ORDER | 同じリクエストを再び送信しないでください。決済代行会社、スキーム、イシュアー (カード発行会社) が、注文を放棄するよう求めています。 |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 支払者に別の支払い方法(新しいカードや別の支払い方法など)を尋ね、新しい内容でリクエストを再度送信してください。同じリクエストを再度送信しないでください。 |
ゲートウェイによって PROCEED
が推奨されている場合、支払者に表示されているページに htmlRedirectCode
レスポンスフィールドの内容を貼り付けます。
Rupay 認証の各種シナリオでの authenticatePayer()
レスポンスを下表に示しています。
状況 | response.gatewayRecommendation |
transaction.authenticationStatus |
authentication.payerInteraction |
response.gatewayCode |
result |
---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_PENDING | REQUIRED | PENDING | PENDING |
|
DO_NOT_PROCEED_ABANDON_ORDER | AUTHENTICATION_REJECTED | NOT_REQUIRED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
OTP 認証
ゲートウェイは、支払者のブラウザをイシュアー (カード発行会社) の OTP 検証 UI にリダイレクトします。ここで支払者は有効な OTP を入力するように求められます。OTP を入力すると、支払者は Web サイトに再度リダイレクトされます。支払者のブラウザから Web サイトに戻ると、コールバックで次のフィールドが返されます。
- order.id
- transaction.id
- result
- response.gatewayRecommendation
response.gatewayRecommendation
フィールドに返された値を使用して、認証の結果を判断できます。
response.gatewayRecommendation |
次の手順 |
---|---|
PROCEED | 認証が付与されるため、支払いを続行できます。支払いの承認が正常に行われた場合、資金の決済請求を処理し、該当する場合は商品を発送します。 |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 支払者に別の支払い方法(新しいカードや別の支払い方法など)を尋ね、新しい内容でリクエストを再度送信してください。同じリクエストを再度送信しないでください。 |
ゲートウェイは、OTP 認証から結果を取得した後に Authentication Payer レスポンスフィールドを更新します。
都道府県 | response.gatewayRecommendation |
transaction.authenticationStatus |
authentication.payerInteraction |
response.gatewayCode |
result |
---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_SUCCESSFUL | REQUIRED | APPROVED | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_FAILED | REQUIRED | DECLINED | FAILURE |
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
Rupay.authenticatePayer("5678", "ABC", function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code ", data.htmlRedirectCode);
}
}, optionalParams);
手順 5:支払操作での認証結果の使用
authenticatePayer()
メソッドの結果が、支払いを続行できることを示している場合 (gatewayRecommendation=PROCEED)、Authorize または Pay 操作を開始できます。標準のフィールドに加えて以下のフィールドを指定する必要があります。
-
order.id:
initiateAuthentication()
およびauthenticatePayer()
メソッドで入力したorderId
を入力します。 -
authentication.transactionId:
initiateAuthentication()
およびauthenticatePayer()
メソッドで入力したtransactionId
を入力します。認証を実行するように要求すると、ゲートウェイは authentication.transactionId を使用して認証結果を探すので、認証パラメータグループのフィールドを含める必要はありません。ゲートウェイは必要な情報をアクワイアラーに渡します。
URL | https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
HTTP メソッド | PUT |
{ "apiOperation":"PAY", "order":{ "amount":"100", "currency":"INR" }, "sourceOfFunds":{ "provided":{ "card":{ "expiry":{ "month":"01", "year":"21" }, "number":"6074819900004939", "securityCode":"111" } }, "type":"CARD" }, "authentication": { "transactionId":"8286737" } }
{ "authentication": { "transactionId": "471707320" }, "authorizationResponse": { "transactionIdentifier": "500000000000000000000002347854" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTMERCHANT", "order": { "amount": 100.00, "chargeback": { "amount": 0, "currency": "INR" }, "creationTime": "2019-07-03T09:08:28.309Z", "currency": "INR", "id": "802014086", "merchantCategoryCode": "4511", "status": "CAPTURED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 100.00, "totalRefundedAmount": 0.00 }, "response": { "acquirerCode": "00", "acquirerMessage": "Success", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "RUPAY", "expiry": { "month": "1", "year": "21" }, "fundingMethod": "DEBIT", "issuer": "DMBB9990001", "number": "607481xxxxxx4939", "scheme": "RUPAY", "storedOnFile": "NOT_STORED", "tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"SMS\"}" } }, "type": "CARD" }, "timeOfRecord": "2019-07-03T09:08:28.309Z", "transaction": { "acquirer": { "id": "<acquirer_id>", "merchantId": "423555234334123" }, "amount": 100.00, "authorizationCode": "143835", "currency": "INR", "frequency": "SINGLE", "id": "108379916", "receipt": "918409000035", "source": "INTERNET", "terminal": "88011019", "type": "PAYMENT" }, "version": "72" }
インテグレーションのテスト
インテグレーションをテストするには、テスト用加盟店プロファイルを本番環境で使用できます。