認証APIv1からv2へのAPI移行

このページはActiveServer API v1からAPI v2へ移行するためのガイドです。ActiveServer API v1とはGPayments社が以前公開しましたActiveServerのAPI仕様です。

ActiveServerインハウス（オンプレミス）をご導入いただいてるお客様に対して、API v1のサポート期限は2020年Q4（欧米カレンダー）までと予定されております。詳細については改めてお知らせいたします。なお、ActiveServerホスティング・サービス（SaaS）はAPI v2のみ対応しますので、ホスティング・サービスをご利用いただくお客様はAPI v2でご導入いただきます。

主な変更¶

/api/v2/auth/認証APIのエントリーポイントを追加しました。
ActiveServerはカード番号（PAN）を保持しないようになりました。ActiveServerはPANの上6桁と下4桁のみ、プレーンテキストでデータベースに保存します。よって、万が一、サイバー攻撃に遭う際の情報漏洩を最小限に抑えることができます。また、PCI審査の要件項目を減らすことも期待されております。なお、管理UI上、取引PANの検索機能は上6桁と下4桁のみマッチングするようになります。
暗号化PANは保存されないため、API v2を使用する場合は加盟店ごとの暗号化キーは不要になります。API v1においては引き続き必須です。
弊社の3DSリクエスター・サンプル・コードは、API v1ならびにAPI v2へ対応できるように更新されました。

ActiveServer変更¶

ActiveServerバージョンv1.3.0以降、API v2を通じて認証を実行しますと、ActiveServerは暗号化されたカード番号（PAN）を保存しないようになります。代わりに、トランケート形式（PANを部分的に切り捨てる形式）で、暗号化せずにプレーンテキストでデータベースに保存します。PANの上6桁と下4桁のみが保存され、全桁のPANは復元できなくなります。例えば、4123456789876543のPANは412345XXXXXX6543のようにデータベースに保存されます。また、管理UI上も同様、412345XXXXXX6543と表示されます。

その結果、加盟店ごとの暗号化キーは不要となり、将来、この機能は削除される予定です。

なお、全桁のPANを保持しなくなるため、PAN全桁での取引検索はできなくなります。ですが、PANの残り桁での検索することは可能です。その場合、検索したいPANの全桁を検索欄に入力しますと、検索結果は上6桁と下4桁のみ一致する取引が返されます。仮にそれ以外の桁が違っても、その取引は検索結果に返されます。その場合、他の絞り込み条件（Transaction ID、Date/Time、Purchase amount、Currency、など）を使用し、お探しの取引を特定することを推奨します。API v2で実行された取引は引き続きPAN全桁での検索が可能です。

上記の変更により、API v2をご導入いただきますと以下のメリットが期待されております：

パフォーマンスの向上：全取引にPANを暗号化する処理が省かれる
セキュリティーの向上：万が一、サイバー攻撃に遭う際の情報漏洩を最小限にできる
PCI受審期間の短縮化、または受審コストの削減：PCI受審時のカード会員データ環境(英：Cardholder Data Environment)のスコープを縮小できる

Important

上記の変更はAPI v2を使用する場合のみ適応されます。API v1に関する変更は下記をお読みください。

API v1への影響、およびAPI v2へのマイグレーション計画¶

API v1によって実行された取引は上記の変更に影響されません。現在統合済みのAPI v1システムは引き続き稼働可能です。その間、API v2へのマイグレーションの計画をご検討いただくようお願い申し上げます。API v1のサポート期限は2020年Q4（欧米カレンダー）までと予定されております。

以前API v1で実行された取引認証は引き続き、全桁のPANを暗号化し、加盟店ごとの暗号化キーと共にデータベースに保存されます。また、API v2へのマイグレーションをスムーズに行えるよう、弊社はAPI v2マイグレーション・ツールをリリースする予定です。このツールは以下の機能が予定されております：

API v1によって実行された取引をAPI v2形式へ変換します。
暗号化キーストアをクリアします。
API v1を無効化します。

弊社はお客様になるべく早くAPI v2へ移行することを推奨します。

APIの変更 - BRW認証API v2へのマイグレーション¶

API v2のBRW APIに関する主な変更は、カード会員情報は/api/v2/auth/brw (Execute Authentication)のAPIによって送信されるようになります。API v1においては、カード会員情報は/api/v2/auth/brw/init (Initialise Authentication)のAPIによって送信されていました。

API v2において、/api/v2/auth/brw/init (Initialise Authentication)は単に認証前のブラウザー情報収集、および3DS Method（ACSから追加のブラウザー情報収集処理）の実行（適用される場合のみ）を行います。

下記はリクエストのJSONメッセージ変更：

赤ハイライト - このフィールドは削除されました。
緑ハイライト - このフィールドは追加されました。
ハイライトなし - このフィールドはAPI v1と同様です。

フィールド変更に関する詳細は認証APIドキュメントをご参照ください。

`Initialise Authentication`の変更¶

{messageCategory}パラメーターはリクエストメッセージURLからExecute Authentication (/api/v2/auth/brw)リクエストの本文へ移行されました。
下記、削除された取引情報フィールドはExecute authenticationのAPIへ移行されました。
authUrlフィールドはレスポンス・メッセージに追加され、Execute authenticationリクエストの送信先となります。
エラーコードのフィールドは成功した取引認証のレスポンス・メッセージから削除されました。

リクエスト本文¶

以下は/api/v1/auth/brw/init/{messageCategory}と/api/v2/auth/brw/initのリクエスト本文の相違点を記します。

{
-  "acctID": "ActiveServer 3DS Test Account 000000001",
-  "acctInfo": {
-   "chAccAgeInd": "03",
-   "chAccChange": "20160712",
-   "chAccChangeInd": "04",
-   "chAccDate": "20140328",
-   "chAccPwChange": "20170328",
-   "chAccPwChangeInd": "02",
-   "nbPurchaseAccount": "11",
-    "paymentAccAge": "20160917",
-    "paymentAccInd": "04",
-    "provisionAttemptsDay": "3",
-    "shipAddressUsage": "20160714",
-    "shipAddressUsageInd": "04",
-    "shipNameIndicator": "02",
-    "suspiciousAccActivity": "01",
-    "txnActivityDay": "1",
-    "txnActivityYear": "21"
-  },
   "acctNumber": "7654310438720050", 
-  "acctType": "03",
-  "authenticationInd": "01",
-  "authenticationInfo": {
-    "threeDSReqAuthData": "validlogin at UL TS BV",
-    "threeDSReqAuthMethod": "02",
-    "threeDSReqAuthTimestamp": "201711071307"
-  },
-  "cardExpiryDate": 1910,
-  "cardHolderInfo": {
-    "billAddrCity": "Bill City Name",
-    "billAddrCountry": 840,
-    "billAddrLine1": "Bill Address Line 1",
-    "billAddrLine2": "Bill Address Line 2",
-    "billAddrLine3": "Bill Address Line 3",
-    "billAddrPostCode": "Bill Post Code",
-    "billAddrState": "CO",
-    "cardholderName": "Cardholder Name",
-    "email": "example@example.com",
-    "homePhone": {
-      "cc": "123",
-      "subscriber": "123456789"
-    },
-    "mobilePhone": {
-      "cc": "123",
-      "subscriber": "123456789"
-    },
-    "shipAddrCity": "Ship City Name",
-    "shipAddrCountry": "840",
-    "shipAddrLine1": "Ship Address Line 1",
-    "shipAddrLine2": "Ship Address Line 2",
-    "shipAddrLine3": "Ship Address Line 3",
-    "shipAddrPostCode": "Ship Post Code",
-    "shipAddrState": "CO",
-    "workPhone": {
-      "cc": "123",
-      "subscriber": "123456789"
-    }
-  },
-  "challengeInd": "02",
   "eventCallbackUrl": "https://example.requestor.com/3ds-notify",
   "merchantId": "1234567890123456789012345678901234",
-  "merchantName": "string",
-  "merchantRiskIndicator": {
-    "deliveryEmailAddress": "deliver@email.com",
-    "deliveryTimeframe": "01",
-    "giftCardAmount": "337",
-    "giftCardCount": "02",
-    "giftCardCurr": "840",
-    "preOrderDate": "20170519",
-    "preOrderPurchaseInd": "02",
-    "reorderItemsInd": "01",
-    "shipIndicator": "02"
-  },
-  "payTokenInd": true,
-  "priorTransID": "59ae264e-b0f4-43c7-870e-4d14bd52806e",
-  "purchaseAmount": "12345",
-  "purchaseCurrency": "978",
-  "purchaseDate": "20180122153045",
-  "purchaseInstalData": "024",
-  "recurringExpiry": "20180131",
-  "recurringFrequency": "2",
   "threeDSRequestorTransID": "2409a5df-b777-4ebc-ad59-2a61091187f1",
-  "transType": "03"
}

レスポンス¶

以下は/api/v1/auth/brw/init/{messageCategory}と/api/v2/auth/brw/initのレスポンス本文の相違点を記します。

{
- "errorCode": "1005",
- "errorComponent": "A",
- "errorDescription": "Data element not in the required format. Not numeric or wrong length.",
- "errorDetail": "billAddrCountry,billAddrPostCode,dsURL",
- "errorMessageType": "AReq",
+ "authUrl": "https://demo.3dsserver.com/api/v2/auth/brw?t=dbb270aa890028817afe58fda659526e",
  "monUrl": "https://demo.3dsserver.com/brw/init/mon?t=6afa6072-9412-446b-9673-2f98b3ee98a2",
  "threeDSServerCallbackUrl": "https://demo.3dsserver.com/brw/callback?transId=6afa6072-9412-446b-9673-2f98b3ee98a2",
  "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2"
}

Important

API v2において、Execute Authentication処理はActiveServerが作成した動的（ダイナミック）URL（authUrl）を使用することが必須となります。3DSリクエスターはこのURLを使用します。以前API v1のみ対応したデモ用3DSリクエスター・サンプル・コードはハードコードされたURLがありますが、そのURLは使用しません。

`Execute Authentication`の変更¶

Execute Authentication (/api/v2/auth/brw)のエントリーポイントは、Initialise authenticationレスポンス内のauthUrlへ変更されました。
Initialise Authenticationから削除されたカード会員情報と取引情報のパラメーターはリクエスト本文へ移行されました。
threeDSRequestorTransIDとthreeDSServerTransIDのフィールドは不要になったため、削除されました。
acctNumberフィールドが追加されました。
browserInfoフィールドが追加されました。このフィールドはブラウザー情報収集処理によって収集された情報です。詳細は3DS Requestor changesをご参照ください。
API v1にありましたInitialise Authentication {messageCategory}パラメーターはAPI v1 URLから削除され、レスポンス本文へ移行されました。
addrMatchオプション・フィールドはcardHolderInfo JSONオブジェクトに追加されました。請求先住所はお届け先住所と同じの場合はYを設定、同じでない場合はNを設定します。請求先住所とお届け先住所は必須情報です。
threeDSRequestorTransIDフィールドは不要になったため、削除されました。
エラーコードのフィールドは成功した取引認証のレスポンス・メッセージから削除されました。

リクエスト本文¶

以下は/api/v1/auth/brwと/api/v2/auth/brwのリクエスト本文の相違点を記します。

{
+  "acctID": "ActiveServer 3DS Test Account 000000001",
+  "acctInfo": {
+   "chAccAgeInd": "03",
+   "chAccChange": "20160712",
+   "chAccChangeInd": "04",
+   "chAccDate": "20140328",
+   "chAccPwChange": "20170328",
+   "chAccPwChangeInd": "02",
+   "nbPurchaseAccount": "11",
+    "paymentAccAge": "20160917",
+    "paymentAccInd": "04",
+    "provisionAttemptsDay": "3",
+    "shipAddressUsage": "20160714",
+    "shipAddressUsageInd": "04",
+    "shipNameIndicator": "02",
+    "suspiciousAccActivity": "01",
+    "txnActivityDay": "1",
+    "txnActivityYear": "21"
+  },
+  "acctNumber": "7654310438720050",
+  "acctType": "03",
+  "authenticationInd": "01",
+  "authenticationInfo": {
+    "threeDSReqAuthData": "validlogin at UL TS BV",
+    "threeDSReqAuthMethod": "02",
+    "threeDSReqAuthTimestamp": "201711071307"
+  },
+  "browserInfo": "Base64 encoded browser informaction", --New field added from V2
+  "cardExpiryDate": "1910",
+  "cardHolderInfo": {
+    "addrMatch": "N",
+    "billAddrCity": "Bill City Name",
+    "billAddrCountry": 840,
+    "billAddrLine1": "Bill Address Line 1",
+    "billAddrLine2": "Bill Address Line 2",
+    "billAddrLine3": "Bill Address Line 3",
+    "billAddrPostCode": "Bill Post Code",
+    "billAddrState": "CO",
+    "cardholderName": "Cardholder Name",
+    "email": "example@example.com",
+    "homePhone": {
+      "cc": "123",
+      "subscriber": "123456789"
+    },
+    "mobilePhone": {
+      "cc": "123",
+      "subscriber": "123456789"
+    },
+    "shipAddrCity": "Sh"ip" City Name",
+    "shipAddrCountry": 840,
+    "shipAddrLine1": "Ship Address Line 1",
+    "shipAddrLine2": "Ship Address Line 2",
+    "shipAddrLine3": "Ship Address Line 3",
+    "shipAddrPostCode": "Ship Post Code",
+    "shipAddrState": "CO",
+    "workPhone": {
+      "cc": "123",
+      "subscriber": "123456789"
+    }
+  },
+  "challengeInd": "02",
+  "merchantName": "Test Merchant",
+  "merchantRiskIndicator": {
+    "deliveryEmailAddress": "deliver@email.com",
+    "deliveryTimeframe": "01",
+    "giftCardAmount": "337",
+    "giftCardCount": "02",
+    "giftCardCurr": "840",
+    "preOrderDate": "20170519",
+    "preOrderPurchaseInd": "02",
+    "reorderItemsInd": "01",
+    "shipIndicator": "02"
+  },
+  "messageCategory": "pa",
+  "payTokenInd": true,
+  "priorTransID": "59ae264e-b0f4-43c7-870e-4d14bd52806e",
+  "purchaseAmount": "12345",
+  "purchaseCurrency": "978",
+  "purchaseDate": "20180122153045",
+  "purchaseInstalData": "024",
+  "recurringExpiry": "20180131",
+  "recurringFrequency": "2",
-  "threeDSRequestorTransID": "2409a5df-b777-4ebc-ad59-2a61091187f1",
   "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2", 
+  "transType": "03"
}

レスポンス¶

以下は/api/v1/auth/brwと/api/v2/auth/brwのレスポンス本文の相違点を記します。

{
  "acsChallengeMandated": "Y",
  "acsReferenceNumber": "3DS_GP_ACS_201_13579",
  "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
  "authenticationType": "02",
  "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  "cardholderInfo": "For example, Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx. \n Length: Maximum 128 characters\n Optional",
  "challengeUrl": "https://demo.acs.com/challenge",
  "dsReferenceNumber": "string",
  "dsTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
  "eci": "02",
- "errorCode": "1005",
- "errorComponent": "A",
- "errorDescription": "Data element not in the required format. Not numeric or wrong length.",
- "errorDetail": "billAddrCountry,billAddrPostCode,dsURL",
- "errorMessageType": "AReq",
  "messageVersion": "string",
  "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
  "transStatus": "Y",
  "transStatusReason": 11
}

`Result`の変更¶

authenticationTypeとinteractionCounterフィールドを追加しました。これはカード会員へのチャレンジに関して情報をもっと提供するためです。
acsReferenceNumberとdsReferenceNumberフィールドは削除されました。これはExecute Authentication処理にすでに提供されているからです。
エラーコードのフィールドは成功した取引認証のレスポンス・メッセージから削除されました。

リクエスト¶

リクエスト本文への変更はありません。

レスポンス¶

以下は/api/v1/auth/brw/resultと/api/v2/auth/brw/resultのレスポンス本文の相違点を記します。

{
- "acsReferenceNumber": "3DS_GP_ACS_201_13579",
  "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
+ "authenticationType": "02",
  "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
- "dsReferenceNumber": "string",
  "dsTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
  "eci": "02",
+ "interactionCounter": "02",
- "errorCode": "1005",
- "errorComponent": "A",
- "errorDescription": "Data element not in the required format. Not numeric or wrong length.",
- "errorDetail": "billAddrCountry,billAddrPostCode,dsURL",
- "errorMessageType": "AReq",
  "messageVersion": "string",
  "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
  "transStatus": "Y",
  "transStatusReason": 11
}

APIの変更 - APP認証API v2へのマイグレーション¶

/api/v1/auth/app/{messageCategory}のパスは/api/v2/auth/appへ変更されました。{messageCategory}フィールドはURLからリクエスト本文へ移行されました。
addrMatchオプション・フィールドはcardHolderInfo JSONオブジェクトに追加されました。請求先住所はお届け先住所と同じの場合はYを設定、同じでない場合はNを設定します。請求先住所とお届け先住所は必須情報です。
interactionCounterフィールドは/api/v2/auth/app/resultのレスポンスへ追加されました。この値はカード会員が試した認証回数を示すため、ACSから返される場合があります。

APIの変更 - 3RI認証API v2へのマイグレーション¶

/api/v1/auth/3ri/{messageCategory}のパスは/api/v2/auth/3riへ変更されました。{messageCategory}フィールドはURLからリクエスト本文へ移行されました。

3DSリクエスターの変更¶

3DSリクエスターのバックエンド・コードは、返されたauthURLをWebサーバー・セッションのinitAuthレスポンスに保存します。後に、authURLはBRW認証チャンネルのExecute Authentication処理に使われます。
3DSリクエスターはeventCallbackUrlにて3DSMethodFinishedもしくは3DSMethodSkippedのeventを受信する際、paramパラメーターの中にはActiveServerが収集したブラウザー情報がBase64エンコード方式で含まれています。そのため、弊社の3DSリクエスター・サンプル・コードには新しいAPI v2対応の3ds-web-adapterが追加されました。3DSリクエスターは、Execute AuthenticationリクエストにあるbrowserInfoフィールド内に、上記のBase64エンコードされたブラウザー情報を送信します。
3DSリクエスターはPANを二回ActiveServerへ送信します。/api/v2/auth/brw/initと/api/v2/auth/brwのAPIコールを通じてPANを送信します。これは、ActiveServerは暗号化されたPANを保存しなくなったためです。

認証APIv1からv2へのAPI移行

主な変更¶

ActiveServer変更¶

API v1への影響、およびAPI v2へのマイグレーション計画¶

APIの変更 - BRW認証API v2へのマイグレーション¶

Initialise Authenticationの変更¶

リクエスト本文¶

レスポンス¶

Execute Authenticationの変更¶

リクエスト本文¶

レスポンス¶

Resultの変更¶

リクエスト¶

レスポンス¶

APIの変更 - APP認証API v2へのマイグレーション¶

APIの変更 - 3RI認証API v2へのマイグレーション¶

3DSリクエスターの変更¶

`Initialise Authentication`の変更¶

`Execute Authentication`の変更¶

`Result`の変更¶