Skip to content

API migration from v1 to v2

This is a reference guide for migrating from ActiveServer API v1 to API v2.

The sunset timing for using API v1 for on-premise clients is currently planned for Q4 2020, which will be communicated to clients closer to the date. Any clients using the GPayments Hosted SaaS will be required to use API v2 from service launch.

Major change overview

  • Added /api/v2/auth/ authentication API entry points.
  • ActiveServer no longer stores encrypted cardholder PANs in the database, only the truncated PAN is stored (first 6 and last 4 digits). This improves security by significantly reducing the impact of a breach and potentially reduces some PCI compliance requirements. PAN search functionality will be limited to the first 6 and last 4 digits when searching for API v2 transactions.
  • Due to encrypted PANs no longer being stored, per merchant encryption keys are no longer required when using API v2. They are still required for API v1 transactions.
  • GPayments 3DS Requestor demo code has been upgraded to support both API v1 and API v2.

ActiveServer changes

As of ActiveServer version 1.3.0, ActiveServer will no longer store an encrypted PAN for transactions executed via API v2, and instead will only store a truncated PAN. Only the first 6 digits and last 4 digits will be stored in plain text and be visible to users, e.g. a PAN of 4123456789876543 will be stored as 412345XXXXXX6543 in the database and shown as the same on the administration interface.

As a result, per merchant encryption keys are only used for API v1 transactions and will be removed in a future release.

As ActiveServer no longer stores full PANs, the transaction search function in Admin UI will no longer support full PAN matching for those executed via API v2. Although, partial PAN search is still available. Users can enter a full PAN in the search box as usual, and the results will return all transactions that match the first 6 and last 4 digits of the entered PAN. Combining partial PAN search along with other attributes e.g. Transaction ID, Date/Time, Purchase amount or Currency, should allow a particular transaction to be identified. Transaction search functionality for API v1 transactions is not affected.

By implementing API v2, clients may enjoy the following benefits:

  • Improved performance: ActiveServer no longer needs to call transaction encryption functions
  • Increased security: Reduces the impact of a security breach
  • Reduced time and costs for PCI auditing: Potentially reduces the scope of the Cardholder Data Environment (CDE).

Important

Note the above changes are only applicable when using Auth API v2. Read below for the impact on API v1.

Auth API v1 impact and migration plan

Transactions using Auth API v1 will be unaffected by the changes mentioned above. Current integrations will continue to work, allowing for a stable upgrade path to API v2 to be planned. The current sunset timing is planned for Q4 2020.

All past API v1 transactions will still have encrypted PANs using per merchant encryption keys stored in the database. To assist clients transition smoothly into from API v1 to API v2, an API v2 migration utility will be provided in a future release, and will contain the following functionality:

  • Convert all API v1 transactions into the new API v2 format
  • Clear up the encryption keystores
  • Disable API v1

GPayments encourages all ActiveServer clients to upgrade to API v2 as soon as possible, to take advantage of all its included benefits.

API Changes - migrating to v2 BRW Auth API

The main change to the v2 BRW API is that all cardholder fields are now sent in the /api/v2/auth/brw (Execute Authentication) API call, rather than in /api/v2/auth/brw/init (Initialise Authentication). The Initialise authentication process will be used simply to collect pre-authentication browser information, and to execute the 3DS Method (optional additional browser information collection by the ACS) if it is available.

See below for the JSON message changes for the requests.

  • Red highlight - the field is removed.
  • Green highlight - the field is added.
  • No highlight - the field is unchanged from API v1.

Please refer to the API documentation for detailed field descriptions.

Changes to Initialise Authentication

  • The {messageCategory} parameter has been removed from the request message URL and added to the request body of Execute Authentication (/api/v2/auth/brw).
  • The transaction related fields removed from the request message below have been added to Execute authentication.
  • The authUrl field has been added to the response message, this is now used as the URL to send the Execute authentication request.
  • The error code fields are no longer included in a successful response message.

Request body

Below shows the difference of the request body between /api/v1/auth/brw/init/{messageCategory} and /api/v2/auth/brw/init:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
{
-  "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"
}

Response

Below shows the difference of the response body between /api/v1/auth/brw/init/{messageCategory} and /api/v2/auth/brw/init:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
- "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 requires the Execute Authentication process to utilise a dynamic URL (authUrl) generated by ActiveServer. The 3DS Requestor is required to use this URL instead of the hardcoded one in the v1 3DS Requestor demo code.

Changes to Execute Authentication

  • The entry point of Execute Authentication (/api/v2/auth/brw) has been changed to use authUrl returned by the response of Initialise Authentication.
  • Cardholder and transaction information parameters removed from Initialise Authentication have been added to the request body.
  • The acctNumber field has been added.
  • The browserInfo field has been added, which is the result of the browser info collection process. More information can be found in the 3DS Requestor changes section below.
  • The API v1 Initialise Authentication {messageCategory} parameter has been removed from the API v1 URL and added to the request body.
  • The optional addrMatch field has been added under the cardHolderInfo JSON object. Y should be set if billing address and shipping address is the same, otherwise N should be set. Billing and shipping address information must still be provided.
  • The threeDSRequestorTransID field has been removed as it is no longer needed.
  • The error code fields are no longer included in a successful response message.

Request body

Below shows the difference of the request body between /api/v1/auth/brw and /api/v2/auth/brw:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
+  "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"
}

Response

Below shows the difference of the response body between /api/v1/auth/brw and /api/v2/auth/brw:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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
}

Changes to Result

  • The authenticationType and interactionCounter fields have been added to provide more information about the cardholder challenge that was performed.
  • The acsReferenceNumber and dsReferenceNumber fields have been removed as they are already provided in Execute Authentication.
  • The error code fields are no longer included in a successful response message.

Request

No changes were made to the request body.

Response

Below shows the difference of the response body between /api/v1/auth/brw/result and /api/v2/auth/brw/result:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
- "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 Changes - migrating to v2 APP Auth API

  • Path has been changed from /api/v1/auth/app/{messageCategory} to /api/v2/auth/app. The {messageCategory} field has been moved from the URL to the request body.
  • The optional addrMatch field has been added under the cardHolderInfo JSON object. Y should be set if billing address and shipping address is the same, otherwise N should be set. Billing and shipping address information must still be provided.
  • Added the interactionCounter field to the response of /api/v2/auth/app/result, this value may be returned by the ACS to indicate the number of authentication cycles attempted by the cardholder.

API Changes - migrating to v2 3RI Auth API

  • Path has been changed from /api/v1/auth/3ri/{messageCategory} to /api/v2/auth/3ri. The {messageCategory} field has been moved from the URL to the request body.

3DS Requestor changes

  • The 3DS Requestor backend code has been updated to store the returned authUrl in the initAuth response in the web server sessions and will be reused in the later Execute Authentication call in the BRW channel.
  • When the 3DS Requestor receives 3DSMethodFinished or 3DSMethodSkipped event at the eventCallbackUrl, the param parameter will contain browser information collected by the ActiveServer in Base64 encoded form. A new 3ds-web-adapter v2 has been added to the 3DS Demo code to cater for this change. The 3DS Requestor is required to include this Base64 encoded browser information unchanged in the field browserInfo in the Execute Authentication request.
  • 3DS Requestor will now pass the PAN twice to the 3DS server through the API calls /api/v2/auth/brw/init and /api/v2/auth/brw due to ActiveServer no longer storing the encrypted PAN in the database.