3DS Server API Docs

Table of contents

3DS Server API Docs

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"
}