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 ofExecute 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 theExecute 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 useauthUrl
returned by the response ofInitialise 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 thecardHolderInfo
JSON object.Y
should be set if billing address and shipping address is the same, otherwiseN
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
andinteractionCounter
fields have been added to provide more information about the cardholder challenge that was performed. - The
acsReferenceNumber
anddsReferenceNumber
fields have been removed as they are already provided inExecute 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 thecardHolderInfo
JSON object.Y
should be set if billing address and shipping address is the same, otherwiseN
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 theinitAuth
response in the web server sessions and will be reused in the laterExecute Authentication
call in the BRW channel. - When the 3DS Requestor receives
3DSMethodFinished
or3DSMethodSkipped
event at theeventCallbackUrl
, theparam
parameter will contain browser information collected by the ActiveServer in Base64 encoded form. A new3ds-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 fieldbrowserInfo
in theExecute 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.