If a transaction is determined to be a high-risk by the ACS, the client will be required to pass an authentication challenge. The challenge is required when an Authentications' threeDSecureResponse has a "transStatus" : "C".

This challenge can be loaded into an iframe via a form that posts the encdodedCreq to the acsURL from the Authentications response. The form will return a challenge window (HTML with embedded styling and javascript) with which the client will interact. The challenge could require an OTP (one time passcode), the selection of one or more answers, or some other interaction. When the client completes the challenge, the challenge window posts the answer(s) to the ACS and a summary (notification) of the challenge results is sent to the notification URL provided in the Authentications request. When that notification is received, a request containing the relevant threeDSServerTransID can then be sent to Challenge Results. The response contains the results of that challenge, and if successful, any additional 3DS information (eci, dsTransId, acsTransId, etc.) needed to process the payment.

Authentications Request and Response

The Authentications request contains a few fields which influence a potential challenge.
^{* denotes a required field}

Field Name	Type	Description
ChallengeWindowSize*	numeric	Determines size of the challenge window. 1 - 250x400 2 - 390x400 3 - 500x600 4 - 600x400 5 - Full Screen (allows for responsive design)
NotificationUrl*	string	Endpoint the ACS will notify following challenge completion
GenerateChallengeRequest	boolean	If true or omitted, an encodedCReq (encoded Challenge Request) is available in the Authentications response. This encodedCReq is required to retrieve a challenge.

An Authentications response which prompts a challenge will contain a couple fields needed to retrieve the challenge.

Field Name	Type	Description
acsURL	string	Endpoint to send the form data (action)
encodedCReq	string	Base64 encoded challenge request. This value should remain encoded. Contains the threeDSServerTransID, acsTransID, challengeWindowSize, messageType, and 3DS messageVersion.

Challenge Request

The challenge request is posted to the acsURL and returns a challenge window.
^{* denotes a required field}

Field Name	Type	Description
creq*	text	encodedCReq from Authentications response
threeDSSessionData	text	Any values to be passed back in the Challenge Response to the NotificationUrl. - Limited to 1024 bytes - Must be AlphaNumeric or Base64 encoded.

POST https://acs-server.mc.msignia-dev.tech/api/v1/browser_challenges
Content-Type: application/x-www-form-urlencoded

creq:eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImIzYWYxOTM2LTY2NDYtNDQ0ZC04ZDI1LTk0ZDY0YmI4M2ZmNSIsImFjc1RyYW5zSUQiOiI2ZGEwMTUxMi00MTVjLTQ5NGItOWE2Zi01ZTJlZWMxN2ZiYzQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0
threeDSSessionData:Anything1024BytesAndAlphaNumeric

The above could be an HTML form that targets an iframe. The response is HTML with embedded styling and JavaScript. An example challenge is below:

Challenge Response

The Client's answer(s) are posted back to the ACS and the ACS sends a notification. That notification will contain the cres and the threeDSSessionData (if included in Challenge Request).

Field Name	Type	Description
cres	text	Base64 encoded challenge response. Contains the acsTransID, messageType, challengeCompletionInd, 3DS messageVersion, transStatus, and threeDSServerTransID.
threeDSSessionData	text	Any values passed in the Challenge Request's threeDSSessionData. - Max 1024 bytes - AlphaNumeric or Base64 encoded.

HTTP Method: POST 
Content-Type: application/x-www-form-urlencoded

cres=eyJhY3NUcmFuc0lEIjoiZDBjM2I5NjAtMTBkZS00ZDkzLTlhZTItNDk1MWM4OGQxN2M0IiwibWVzc2FnZVR5cGUiOiJDUmVzIiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidHJhbnNTdGF0dXMiOiJZIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1M2I3NDQ5ZC0yYzVkLTQwNmEtYjZhNC0xNTVmMDVlZWUwY2IifQ&threeDSSessionData=Anything1024BytesAndAlphaNumeric

Retrieving Challenge Results

Following receipt of the notification from the ACS, the full challenge results can be retrieved from Challenge Results endpoint.

Handling Timeouts

Requestors have 30 seconds from receiving a challenged Authentications response to initiate a challenge request. If a Requestor does not intend to execute a challenge, the requestor should abandon the challenge.