3DS Server API Docs
Table of contents
Overview
mSIGNIA 3DS Server is a certified 3DS Server software that supports 2.1 and 2.2 3DS specifications. This document covers the APIs of the 3DS Server software.
The 3DS Server has three main endpoints that are used at different phases of a 3DS transaction, the first two get normally executed sequentially while the third one would rather be called conditionally, only when a challenge flow has been performed.
Below is a recommended sequence of calls of the 3DS Server endpoints:
- Look us the Directory Server (DS) as well as the 3DS protocol version (either 2.1 or 2.2) to perform the transaction with by invoking a
GetSupportedVersions
endpoint. - Perform a 3DS authentication flow by calling the
Authenticate
endpoint. - Optionally, only when the authentication ended up with a challenge flow, get the results of challenge flow by calling a
GetResult
endpoint.
The remainder of this page documents the endpoints.
GetSupportedVersions
A merchant usually calls the GetSupportedVersions
endpoint before an actual 3DS transaction begins. The merchant passes an aacctNumber
and the 3DS Server resolves it to a Directory Server, 3DS protocol version as well as optionally 3DS Method URL to be performed for given acctNumber
.
The merchant is then supposed to articulate the information received to a 3DS SDK so it can perform the right transactions tailored to the right Directory Server and the right protocol version.
- URL:
/api/v2/supportedVersions
- HTTP Method: POST
- Request body: A JSON document as shown in the example below
{
"acctNumber": "4801373551708708"
}
A response would then this:
[
{
"dsIdentifier": "A000000003",
"threeDSMethodURL": "https://acs-server.foo-bank.com/api/v1/3ds_method",
"acsStartProtocolVersion": "2.1.0",
"acsEndProtocolVersion": "2.1.0",
"dsEndProtocolVersion": "2.2.0",
"dsStartProtocolVersion": "2.1.0",
"threeDSServerTransID": "cb124b43-8cab-4c75-83ab-d32ab5906138"
}
]
Note that the response is actually an array. The case there’s more than one item returned would mean that particular acctNumber
may be handed by more than on Directory Server which is the case of a dual-branded cards. mSIGNIA mobile and Browser uSDKs handle the case - they display a Directory Server popup so the user would pick a preferred one. Alternatively, the merchant may make the over either DS to use on the backend.
If the case the 3DS Server encounters an error, it returns a 3DS Erro
message as per 3DS specification.
Authenticate
The authenticate, called by the merchant, kicks off a 3DS transaction. The merchant passes all the data 3DS AReq
data elements according to the 3DS protocol version used for this transaction:
- URL:
/api/v2/authenticate
- HTTP Method: POST
- Request body: A JSON document as shown in the example below
Sample Browser authentication request
{
"acctNumber": "4801373551708708",
"acquirerBIN": "444444",
"acquirerMerchantID": "550e8400",
"addrMatch": "N",
"billAddrCity": "New York",
"billAddrCountry": "840",
"billAddrLine1": "711 5th Ave",
"billAddrPostCode": "10022",
"billAddrState": "NY",
"browserAcceptHeader": "Accept",
"browserColorDepth": "16",
"browserIP": "54.209.204.159",
"browserJavaEnabled": true,
"browserJavascriptEnabled": "true",
"browserLanguage": "en-us",
"browserScreenHeight": "1024",
"browserScreenWidth": "1280",
"browserTZ": "-300",
"browserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2)",
"cardExpiryDate": "2211",
"cardholderName": "Omega - New York",
"challengeWindowSize": "03",
"deviceChannel": "02",
"email": "john@doe.com",
"homePhone": {
"cc": "1",
"subscriber": "2122073333"
},
"mcc": "5411",
"merchantCountryCode": "840",
"merchantName": "Mastercard Merchant",
"messageCategory": "01",
"messageType": "AReq",
"messageVersion": "2.1.0",
"mobilePhone": {
"cc": "1",
"subscriber": "2122073333"
},
"notificationURL": "https://merchant-backend.com/api/v1/challenge/complete",
"purchaseAmount": "100",
"purchaseCurrency": "840",
"purchaseDate": "20200121124334",
"purchaseExponent": "2",
"shipAddrCity": "New York",
"shipAddrCountry": "840",
"shipAddrLine1": "10 Columbus Cir Space 207",
"shipAddrPostCode": "10019",
"shipAddrState": "NY",
"threeDSCompInd": "Y",
"threeDSRequestorAuthenticationInd": "01",
"threeDSRequestorID": "MAS00001_1000",
"threeDSRequestorName": "ACME Atoms",
"threeDSRequestorURL": "https://merchant-backend.com",
"workPhone": {
"cc": "1",
"subscriber": "2129561120"
}
}
Sample Mobile authentication request
{
"acctNumber": "2303770003400004",
"acquirerBIN": "444444",
"acquirerMerchantID": "550e8400",
"addrMatch": "N",
"billAddrCity": "New York",
"billAddrCountry": "840",
"billAddrLine1": "711 5th Ave",
"billAddrPostCode": "10022",
"billAddrState": "NY",
"cardExpiryDate": "2211",
"cardholderName": "Omega - New York",
"deviceChannel": "01",
"deviceRenderOptions": {
"sdkUiType": [
"01",
"02",
"03",
"04",
"05"
],
"sdkInterface": "03"
},
"email": "john@doe.com",
"homePhone": {
"cc": "1",
"subscriber": "2122073333"
},
"mcc": "5411",
"merchantCountryCode": "840",
"merchantName": "Mastercard Merchant",
"messageCategory": "80",
"messageType": "AReq",
"messageVersion": "2.1.0",
"mobilePhone": {
"cc": "1",
"subscriber": "2122073333"
},
"purchaseAmount": "100",
"purchaseCurrency": "840",
"purchaseDate": "20200121124334",
"purchaseExponent": "2",
"sdkAppID": "c294e1af-8503-4de7-a7aa-a16bc3b7793a",
"sdkEncData": "eyJhbGciOiJSU0.EtT0FFUC0yNTYiLCJ.lbmMiOiJB.MTI4R0NNIn0",
"sdkEphemPubKey": {
"kty": "EC",
"crv": "P-256",
"x": "AZwDG9ewggtHK5b7zV8S6PGij250pXhzII8ZZ-Yr4zE",
"y": "D-4MhGm91pN_r80aIXHDIiXKUiTs8XSGuoVikXX1rGk"
},
"sdkMaxTimeout": "20",
"sdkReferenceNumber": "3DS_LOA_SDK_MSIG_020200_00193",
"sdkTransID": "d34f3607-2013-41f3-a999-38e07fbadf73",
"shipAddrCity": "New York",
"shipAddrCountry": "840",
"shipAddrLine1": "10 Columbus Cir Space 207",
"shipAddrPostCode": "10019",
"shipAddrState": "NY",
"threeDSRequestorAuthenticationInd": "01",
"threeDSRequestorID": "MAS00001_1000",
"threeDSRequestorName": "ACME Atoms",
"threeDSRequestorURL": "https://merchant-backend.com",
"workPhone": {
"cc": "1",
"subscriber": "2129561120"
}
}
If the 3DS Server encounters an error, it returns a 3DS Erro message as per 3DS specification.
GetResult
If a 3DS transaction led to a challenge flow, the GetRestult
endpoint should be used by the merchant to get the final result.
- URL:
/api/v2/results
- HTTP Method: POST
- Request body: A JSON document as shown in the example below
{
"threeDSServerTransID": "cb124b43-8cab-4c75-83ab-d32ab5906138"
}
The result then will be this:
{
"acsTransID": "67138001-f5eb-499e-86e0-f6c4e478020a",
"authenticationType": "02",
"authenticationValue": "BwABApFSYyd4l2eQQFJjAAAAAAA=",
"dsTransID": "00f32b61-6abe-451a-b9f1-0f6fd80f29f6",
"eci": "02",
"interactionCounter": "01",
"messageCategory": "01",
"messageType": "RReq",
"messageVersion": "2.2.0",
"threeDSServerTransID": "0bb95b5b-cd23-49e9-8e1a-da3f2ce8074c",
"transStatus": "Y"
}
If there’s no such transaction found, the app will return another document:
{
"errorMessage": "Transaction ID received is not valid for the receiving component."
}
License Key Checking
The 3DS Server periodically validates the license key passed at boot time. It may stop processing the requests to the three main endpoints if there was no successful check within last 72 hours. In this case the application produces the following response back:
- HTTP Status: 500
- Content-Type: application/json
{
"code": 500,
"description": "License key check failed for more than X hours"
}