Challenge messages

To initiate a challenge, only redirecting the cardholder to the URL obtained in the acs.url field is not enough; it's necessary to POST the CReq. At the end of the challenges, the 3DS Requestor will receive information (on the URL indicated in the notification_url field) regarding the 3DS transaction in the CRes object.

Sending the CReq

The CReq POSt must be performed with the Content-Type header = application/x-www-form-urlencoded when device_channel = 02 or application/json when device_channel = 01. In this form, the creq parameter must be sent, which has the Base64 encoded CReq (which is a JSON) as its value.

Examples

CReq JSON:

{
    "threeDSServerTransID":"12341234-1234-1234-1234-123412341234",
    "acsTransID":"43214321-4321-4321-4321-432143214321",
    "challengeWindowSize":"05",
    "messageType":"CReq",
    "messageVersion":"2.2.0"
}

CReq Base64:

ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTIzNDEyMzQtMTIzNC0xMjM0LTEyMzQtMTIzNDEyMzQxMjM0IiwKICAgICJhY3NUcmFuc0lEIjoiNDMyMTQzMjEtNDMyMS00MzIxLTQzMjEtNDMyMTQzMjE0MzIxIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICAgIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsCiAgICAibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIKfQ==

Challenge redirecting HTML:

<!DOCTYPE html>

<html>

    <body>
        <form action="https://www.acs.com/challenge" method="POST">
            <input type="text" name="creq"
                value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTIzNDEyMzQtMTIzNC0xMjM0LTEyMzQtMTIzNDEyMzQxMjM0IiwKICAgICJhY3NUcmFuc0lEIjoiNDMyMTQzMjEtNDMyMS00MzIxLTQzMjEtNDMyMTQzMjE0MzIxIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICAgIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsCiAgICAibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIKfQ=="/>

            <input type="submit"/>

        
        </form>

    </body>

</html>

CReq parameters

Parameter	Description	Format	Mandatory
`threeDSRequestorAppURL`	Merchant app declaring their URL within the CReq message so that the Authentication app can call the Merchant app after OOB authentication has occurred.	< 256 AN	NO
`threeDSServerTransID`	3DS Server transaction ID	= 36 AN	YES
`acsTransID`	ACS transaction ID	= 36 AN	YES
`challengeCancel`	Indicator informing the ACS and the DS that the authentication has been canceled. `01` = Cardholder selected “Cancel” `02` = Reserved for future EMVCo use (values invalid until defined by EMVCo). `03` = Transaction Timed Out—Decoupled Authentication `04` = Transaction Timed Out at ACS—other timeouts `05` = Transaction Timed Out at ACS—First CReq not received by ACS `06` = Transaction Error `07` = Unknown `08` = Transaction Timed Out at SDK	= 2 N	NO
`challengeDataEntry`	Contains the data that the Cardholder entered into the Native UI text field.	< 45 AN	NO
`challengeHTMLDataEntry`	Data that the Cardholder entered into the HTML UI.	< 256 AN	NO
`challengeNoEntry`	Indicator informing that the Cardholder submits an empty response (no data entered in the UI). `Y` = No Data Entry	= 1 AN	NO
`challengeWindowSize`	Dimensions of the challenge window that has been displayed to the Cardholder. `01` = 250 x 400 `02` = 390 x 400 `03` = 500 x 600 `04` = 600 x 400 `05` = Full screen	= 2 N	YES
`messageType`	Fixed value `CReq`.	= 4 AN	YES
`messageVersion`	3DS message version: `2.1.0` or `2.2.0`.	< 8 AN	YES
`oobContinue`	Boolean value notifying the ACS that Cardholder has completed the authentication as requested by selecting the Continue button in an Out-of-Band (OOB) authentication method.	< 5 AN	NO
`resendChallenge`	Indicator to the ACS to resend the challenge information code to the Cardholder. `Y` = Resend `N` = Do not Resend	= 1 AN	NO
`sdkTransID`	3DS SDK transaction ID. Mandatory when `device_channel` = `01`.	= 36 AN	COND.
`sdkCounterStoA`	Counter used as a security measure in the 3DS SDK to ACS secure channel.	< 3 AN	NO
`whitelistingDataEntry`	Indicator provided by the SDK to the ACS to confirm whether whitelisting was opted by the cardholder. `Y` = Whitelisting Confirmed `N` = Whitelisting Not Confirmed	= 1 AN	NO
messageExtension[]	Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
`criticalityIndicator`	A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.	< 5 AN	NO
`data`	The data carried in the extension.	Object	NO
`id`	A unique identifier for the extension.	< 64 AN	NO
`name`	The name of the extension data set as defined by the extension owner.	< 64 AN	NO

Receiving the CRes

The CRes will be sent in JSON format, Base64 encoded, on the URL informed on the authentication service (notification_url field).

CRes parameters

Parameter	Description	Format
`threeDSServerTransID`	3DS Server transaction ID	= 36 AN
`acsCounterAtoS`	Counter used as a security measure in the ACS to 3DS SDK secure channel.	< 3 AN
`acsTransID`	ACS transaction ID	= 36 AN
`challengeCompletionInd`	Indicator of the state of the ACS challenge cycle and whether the challenge has completed or will require additional messages. Shall be populated in all CRes messages to convey the current state of the transaction. `Y` = Challenge completed, and no further challenge message exchanges are required `N` = Challenge not completed and additional challenge message exchanges are required	= 1 AN
`messageType`	Fixed value `CRes`.	= 4 AN
`messageVersion`	3DS message version: `2.1.0` or `2.2.0`.	< 8 AN
`sdkTransID`	3DS SDK transaction ID	= 36 AN
`transStatus`	Indicates whether a transaction qualifies as an authenticated transaction or account verification. `Y` = Authentication Verification Successful. `N` = Not Authenticated /Account Not Verified; Transaction denied. `U` = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq. `A` = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided. `C` = Challenge Required; Additional authentication is required using the CReq/CRes. `D` = Challenge Required; Decoupled Authentication confirmed. `R` = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.	= 1 AN
messageExtension[]	Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
`criticalityIndicator`	A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.	< 5 AN
`data`	The data carried in the extension.	Object
`id`	A unique identifier for the extension.	< 64 AN
`name`	The name of the extension data set as defined by the extension owner.	< 64 AN