Completing a Challenge

Implementing a 3DS challenge flow within the client's browser

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 NameTypeDescription
ChallengeWindowSize*numericDetermines size of the challenge window.
1 - 250x400
2 - 390x400
3 - 500x600
4 - 600x400
5 - Full Screen (allows for responsive design)
NotificationUrl*stringEndpoint the ACS will notify following challenge completion
GenerateChallengeRequestbooleanIf 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 NameTypeDescription
acsURLstringEndpoint to send the form data (action)
encodedCReqstringBase64 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 NameTypeDescription
creq*textencodedCReq from Authentications response
threeDSSessionDatatextAny values to be passed back in the Challenge Response to the NotificationUrl.
- Limited to 1024 bytes
- Must be AlphaNumeric or Base64 encoded.
Content-Type: application/x-www-form-urlencoded


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:


Example OTP Challenge

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 NameTypeDescription
crestextBase64 encoded challenge response.
Contains the acsTransID, messageType, challengeCompletionInd, 3DS messageVersion, transStatus, and threeDSServerTransID.
threeDSSessionDatatextAny 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


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.