3DS Messages

Message Flow

AReq

3DS Server sends transaction through the DS and device data to the ACS requesting authentication.

ARes

ACS responds with the authentication result or indicates a challenge is required.

CReq / CRes

Cardholder device and ACS exchange challenge data directly.

RReq / RRes

ACS reports the final authentication outcome to the 3DS Server.

Common Fields

These fields are present across most or all messages and are used to route and correlate the transaction between components.

Field	Description
`messageType`	Identifies the type of message (e.g. AReq, ARes, CReq).
`messageVersion`	The active EMV 3DS Protocol Version in use (e.g. 2.2.0).
`messageExtension`	An optional array for carrying supplementary data not defined in the core specification.
`threeDSServerTransID`	UUID generated by the 3DS Server for this transaction.
`dsTransID`	UUID assigned by the Directory Server
`acsTransID`	UUID assigned by the ACS.
`sdkTransID`	UUID generated by the 3DS SDK on the cardholder's device. Present for APP channel transactions only.

AReq - Authentication Request

Merchant & Transaction

Sent by the merchant's 3DS Server through the DS to the ACS to initiate authentication. Contains rich data about the purchase, the device, and the cardholder to support a risk-based decision.

Field	Description
`threeDSRequestorID`	The 3DS Requestor's unique identifier assigned by the DS.
`threeDSRequestorName`	The name of the 3DS Requestor.
`threeDSRequestorURL`	The web address of the 3DS Requestor or their customer care site.
`threeDSRequestorAuthenticationInd`	Indicates the type of request (e.g. payment, recurring, instalment, add card).
`threeDSRequestorChallengeInd`	Indicates whether the merchant prefers a Frictionless Flow, prefers a Challenge, or is mandated to Challenge.
`threeRIInd`	For 3RI transactions, explains the reason for the merchant-initiated request (e.g. recurring payment, split shipment).
`acquirerBIN`	The BIN of the acquiring institution.
`acquirerMerchantID`	The acquirer-assigned merchant identifier.
`merchantName`	The merchant name as used in the authorisation message.
`mcc`	MCC describing the merchant's type of business.
`purchaseAmount`	Transaction amount in minor units.
`purchaseCurrency`	Purchase currency in ISO 4217 numeric format.
`purchaseExponent`	The decimal exponent for the purchase amount.
`purchaseDate`	Date and time of the purchase in UTC.
`transType`	ISO 8583-1 code identifying the transaction type (e.g. goods purchase, account funding).
`messageCategory`	Identifies the category of the message. 01 = Payment Authentication (PA), 02 = Non-Payment Authentication (NPA).
`merchantCountryCode`	ISO 3166-1 numeric three-digit country code of the merchant.
`notificationURL`	Fully qualified URL to which the CRes or error message is posted by the ACS at the end of the challenge.
`recurringExpiry`	Date after which no further authorisations shall be performed for Recurring Payment transactions.
`recurringFrequency`	Minimum number of days between authorisations for Recurring Payment transactions.
`purchaseInstalData`	Maximum number of authorisations permitted for instalment payments. Present when `threeDSRequestorAuthenticationInd` indicates an instalment transaction.
`threeDSRequestorDecReqInd`	Indicates whether the 3DS Requestor requests Decoupled Authentication. Values: Y, N.
`threeDSRequestorDecMaxTime`	Maximum time in minutes the 3DS Requestor will wait for the result of a Decoupled Authentication transaction.

Cardholder & Account

Field	Description
`acctNumber`	The cardholder's PAN or network token.
`acctID`	Additional account information optionally provided by the 3DS Requestor.
`acctType`	Indicates the type of account. Values: 01 = Not applicable, 02 = Credit, 03 = Debit.
`cardExpiryDate`	Expiry date of the card or token.
`cardholderName`	Name of the cardholder.
`email`	Cardholder's email address.
`homePhone`	Cardholder's home phone number.
`mobilePhone`	Cardholder's mobile phone number.
`workPhone`	Cardholder's work phone number.
`acctInfo`	A composite object containing behavioural account data such as account age, password change history, recent purchases, and indicators of suspicious activity.
`addrMatch`	Y/N indicator of whether the billing and shipping addresses are identical.
`billAddrCity`	Billing address city.
`billAddrCountry`	Billing address country.
`billAddrLine1`	First line of the cardholder billing address.
`billAddrLine2`	Second line of the cardholder billing address.
`billAddrLine3`	Third line of the cardholder billing address.
`billAddrPostCode`	Postal code of the cardholder billing address.
`billAddrState`	Billing address state or region.
`shipAddrCity`	Shipping address city.
`shipAddrCountry`	Shipping address country.
`shipAddrLine1`	First line of the requested shipping address.
`shipAddrLine2`	Second line of the requested shipping address.
`shipAddrLine3`	Third line of the requested shipping address.
`shipAddrPostCode`	Postal code of the requested shipping address.
`shipAddrState`	Shipping address state or region.
`merchantRiskIndicator`	A composite object assessing transaction risk based on delivery timeframe, pre-order status, and gift card usage.
`payTokenInd`	Indicates the transaction was de-tokenised prior to being received by the ACS. Present when the PAN is a network token.
`whiteListStatus`	Indicates whether the 3DS Requestor is on the cardholder's Whitelist. Values: Y, N, E (Not eligible), P (Pending), R (Rejected), U (Unknown).
`whiteListStatusSource`	Identifies which system set the whitelist status. Values: 01 = 3DS Server, 02 = DS, 03 = ACS.

Device & Browser

Field	Description
`deviceChannel`	Identifies the origin of the transaction. 01 = APP, 02 = BRW, 03 = 3RI.
`deviceInfo`	Encrypted device data gathered by the 3DS SDK. Present for APP channel transactions only.
`deviceRenderOptions`	Tells the ACS which UI formats the cardholder's device supports (e.g. Native UI, HTML).
`browserAcceptHeader`	HTTP Accept header from the cardholder's browser.
`browserIP`	IP address of the cardholder's browser.
`browserLanguage`	Language of the cardholder's browser.
`browserUserAgent`	User agent string of the cardholder's browser.
`browserScreenHeight`	Browser screen height in pixels.
`browserScreenWidth`	Browser screen width in pixels.
`browserJavaEnabled`	Whether Java is enabled in the cardholder's browser.
`browserJavascriptEnabled`	Whether JavaScript is enabled in the cardholder's browser.
`browserColorDepth`	Colour depth of the browser screen in bits.
`browserTZ`	UTC offset of the browser's timezone in minutes.
`sdkAppID`	Unique identifier created when the merchant app was installed.
`sdkEphemPubKey`	Cryptographic key used to establish a secure session with the ACS for 3DS SDK-based challenges.
`sdkEncData`	JWE-encrypted device data collected by the 3DS SDK and forwarded to the ACS for risk assessment. APP channel only.
`sdkMaxTimeout`	Maximum time in minutes allowed for all 3DS SDK exchanges. APP channel only.
`sdkReferenceNumber`	Identifies the 3DS SDK vendor and version, assigned by EMVCo upon approval. APP channel only.
`threeDSCompInd`	Indicates whether the background 3DS Method successfully captured additional browser data before the AReq was sent. Browser channel only.

ARes - Authentication Response

Sent by the ACS back to the merchant in response to the AReq.

Field	Description
`transStatus`	The authentication result. Y = Authenticated, N = Not Authenticated, C = Challenge Required, D = Decoupled Challenge Confirmed, A = Attempts Processing, R = Rejected, U = Unknown, I = Informational Only.
`transStatusReason`	Reason code explaining the outcome when the status is N, R, or U.
`eci`	ECI value providing proof of the authentication result to the acquirer.
`authenticationValue`	The CAVV generated by the ACS as cryptographic proof of authentication.
`authenticationType`	Indicates the type of challenge that will be used if a challenge is required (e.g. OTP, OOB).
`acsChallengeMandated`	Indicates whether local regulations (such as PSD2) require the issuer to challenge.
`acsRenderingType`	Tells the 3DS SDK what UI format the ACS will use for the challenge.
`acsSignedContent`	A JWS object containing the ACS's ephemeral keys to establish encrypted challenge communication.
`acsURL`	The endpoint the 3DS SDK or browser must contact to begin the challenge.
`cardholderInfo`	Custom text from the issuer to display to the cardholder (e.g. "Please call your bank at...").
`acsDecConInd`	Indicates whether the ACS confirms utilisation of Decoupled Authentication. Values: Y, N.
`acsOperatorID`	DS-assigned identifier for the ACS.
`acsReferenceNumber`	Unique reference assigned to the ACS by EMVCo upon testing and approval.
`dsReferenceNumber`	Unique identifier assigned to the DS by EMVCo.
`whiteListStatus`	Communicates Whitelist status between the ACS, DS, and 3DS Requestor. Values: Y, N, E (Not eligible), P (Pending), R (Rejected), U (Unknown).
`whiteListStatusSource`	Identifies which system set the whitelist status. Values: 01 = 3DS Server, 02 = DS, 03 = ACS.

CReq - Challenge Request

Sent directly from the cardholder's device to the ACS during a challenge.

Field	Description
`challengeDataEntry`	The data entered by the cardholder in the Native UI input field (e.g. an OTP).
`challengeHTMLDataEntry`	The data entered by the cardholder if the challenge was presented using HTML.
`challengeNoEntry`	Indicates the cardholder submitted the form without entering any data.
`challengeCancel`	Indicates the cardholder cancelled the challenge.
`challengeWindowSize`	Dimensions of the challenge window displayed to the browser user.
`oobContinue`	Indicates the cardholder completed an OOB task (e.g. opened their banking app) and clicked Continue.
`resendChallenge`	Indicates the cardholder requested a new OTP by clicking Resend.
`whitelistingDataEntry`	The cardholder's response (Y/N) to adding the merchant to their Whitelist.
`sdkCounterStoA`	A security counter used to keep the encrypted 3DS SDK channel synchronised with the ACS.

CRes - Challenge Response

Sent from the ACS to the cardholder's device to drive the challenge UI.

Field	Description
`challengeCompletionInd`	Y if the challenge is complete, N if further steps are required.
`acsUiType`	The UI template to render (e.g. Text, Single Select, Multi-Select, OOB).
`challengeInfoHeader`	The main title displayed on the challenge screen.
`challengeInfoText`	Instructional text shown to the cardholder (e.g. "We sent a code to your phone ending in 1234").
`challengeInfoLabel`	Label text displayed alongside the input field (e.g. "Enter code here").
`challengeInfoTextIndicator`	Controls whether a visual warning icon is shown alongside the challenge text.
`challengeSelectInfo`	The list of options presented when the UI type is Single or Multi-select.
`expandInfoLabel`	Label for a collapsible section containing additional instructions.
`expandInfoText`	Content of the collapsible additional instructions section.
`whyInfoLabel`	Label for a collapsible section explaining why the cardholder is being challenged.
`whyInfoText`	Content of the why-am-I-being-challenged section.
`issuerImage`	URL of the issuer's logo to display on the challenge screen.
`psImage`	URL of the payment scheme's logo to display on the challenge screen.
`submitAuthenticationLabel`	Text for the Submit button.
`resendInformationLabel`	Text for the Resend Code button.
`oobContinueLabel`	Text for the Continue button shown after an OOB step.
`oobAppURL`	Deep link to open the issuer's banking app for OOB authentication.
`oobAppLabel`	Button text for the link to open the banking app.
`whitelistingInfoText`	The prompt asking the cardholder whether they want to add the merchant to their Whitelist.
`acsHTML`	Raw encoded HTML provided by the ACS when Native UI is not used. Rendered directly on the cardholder's device.
`acsCounterAtoS`	Security counter for the ACS-to-3DS SDK encrypted channel. Counterpart to `sdkCounterStoA` in the CReq. APP channel only.
`transStatus`	Present when the challenge is complete. Y = Authenticated, N = Not Authenticated.

RReq - Results Request

Sent by the ACS to the 3DS Server (via the DS) once the challenge is complete, reporting the final outcome.

Field	Description
`transStatus`	Final authentication status. Y = Authenticated, N = Not Authenticated, U = Unknown, R = Rejected.
`transStatusReason`	Reason code if the challenge failed or was rejected.
`authenticationValue`	The CAVV generated as cryptographic proof of the completed authentication.
`eci`	Final ECI value.
`interactionCounter`	The number of times the cardholder attempted the challenge.
`authenticationMethod`	Identifies how the challenge was ultimately performed (e.g. SMS OTP, biometrics).
`challengeCancel`	Indicates why the authentication was cancelled. Values: 01 = Cardholder selected Cancel, 03 = Timed out (decoupled), 04 = Timed out at ACS, 05 = First CReq not received, 06 = Transaction error, 07 = Unknown, 08 = Timed out at 3DS SDK.
`messageCategory`	Identifies the category of the message. 01 = Payment Authentication, 02 = NPA.
`acsRenderingType`	Identifies the ACS UI template used during the challenge (e.g. Native UI, HTML UI).
`whiteListStatus`	Communicates Whitelist status at the conclusion of the challenge. Values: Y, N, E, P, R, U.
`whiteListStatusSource`	Identifies which system set the whitelist status. Values: 01 = 3DS Server, 02 = DS, 03 = ACS.

RRes - Results Response

Sent by the 3DS Server back to the ACS to acknowledge receipt of the RReq.

Field	Description
`resultsStatus`	Indicates whether the RReq was received successfully, or provides a reason why the challenge result could not be processed.

Erro - Error Message

Generated by any component if something goes wrong during the processing of any 3DS message.

Field	Description
`errorCode`	A numeric code classifying the specific problem (e.g. 201 for missing data, 302 for decryption failure).
`errorComponent`	Identifies which system raised the error. C = 3DS SDK, S = 3DS Server, D = DS A = ACS.
`errorDescription`	Human-readable summary of the issue.
`errorDetail`	Technical detail, such as the exact field name that was missing or malformed.
`errorMessageType`	The type of message (e.g. AReq, CReq) that triggered the error.