5. Reference

The scenario selector below can be used to narrow down the required fields for a selected authentication scenario. Please note the following:

  1. When All is selected in both dropdowns, no type filters are applied. I.e. both sdkTransID and browserUserAgent is marked as required, even though they will never appear in the same message.

  2. When a Message Category or a Device Channel is selected, messages will be filtered if they are not relevant for the selection. The inclusion might change from e.g. required to optional

Message Category:
Device Channel:

5.1. /preauth endpoint

Input

Key

Format

Required

Comments

acctNumber

^[1-9]\d{12,18}$

Yes

The cardholders account number or e.g. a tokenized PAN.

Output

Key

Format

Required

Comments

acsStartProtocolVersion

messageVersion

Yes

acsEndProtocolVersion

messageVersion

Yes

threeDSServerTransID

UUID

Yes

dsStartProtocolVersion

messageVersion

No

acsInfoInd

ACSInfo

No

threeDSMethodURL

URL

No

5.2. /auth endpoint

Input

Description Comment
acctID
Type: string
Max length: 64
Optional
Additional information about the account optionally provided by the 3DS Requestor.
acctInfo
Optional
Additional information about the Cardholder’s account provided by the 3DS Requestor.
acctNumber
Type: string
Regexp: ^[0-9]{13,19}$
Required
Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, token.
acctType
Type: string
Regexp: ^(0[1-3])|([89][0-9])$
Optional
Indicates the type of account. For example, for a multi-account card product.
acquirerBIN
Type: string
Max length: 11
Conditional
Acquiring institution identification code as assigned by the DS receiving the AReq message.
Required if messageCategory is "01"
acquirerMerchantID
Type: string
Max length: 35
Conditional
Acquirer-assigned Merchant identifier. This may be the same value that is used in authorisation requests sent on behalf of the 3DS Requestor and is represented in ISO 8583 formatting requirements.
Required if messageCategory is "01"
addrMatch
Type: string
One of: Y N
Optional
Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
billAddrCity
Type: string
Max length: 50
Optional
The city of the Cardholder billing address associated with the card used for this purchase.
billAddrCountry
Type: string
Length: 3
Optional
The country of the Cardholder billing address Server associated with the card used for this purchase.
billAddrLine1
Type: string
Max length: 50
Optional
First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
billAddrLine2
Type: string
Max length: 50
Optional
Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
billAddrLine3
Type: string
Max length: 50
Optional
Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
billAddrPostCode
Type: string
Max length: 16
Optional
ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.
billAddrState
Type: string
Max length: 3
Optional
The state or province of the Cardholder billing address associated with the card used for this purchase.
browserAcceptHeader
Type: string
Max length: 2048
Required
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
browserColorDepth
Type: string
One of: 1 4 8 15 16 24 32 48
Required
Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
browserIP
Type: string
Format: ip
Max length: 45
Optional
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
browserJavaEnabled
Type: bool
Required
Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.
browserLanguage
Type: string
Min length: 1
Max length: 8
Required
Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
browserScreenHeight
Type: string
Regexp: ^[0-9]{1,6}$
Required
Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.
browserScreenWidth
Type: string
Regexp: ^[0-9]{1,6}$
Required
Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
browserTZ
Type: string
Regexp: ^[+-]?[0-9]{1,4}$
Required
Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.
browserUserAgent
Type: string
Max length: 2048
Required
Exact content of the HTTP user-agent header.
cardExpiryDate
Type: string
Format: yymm
Optional
Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder.
cardholderName
Type: string
Min length: 2
Max length: 45
Optional
Name of the Cardholder.
deviceChannel
Type: string
One of: 01 02 03
Required
Indicates the type of channel interface being used to initiate the transaction.

Interpretation of values:

01
App-based (APP)
02
Browser (BRW)
03
3DS Requestor Initiated (3RI)
deviceRenderOptions
Required
Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK.
email
Type: string
Format: email
Max length: 254
Optional
The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor.
homePhone
Optional
The home phone number provided by the Cardholder.
mcc
Type: string
Length: 4
Conditional
DS-specific code describing the Merchant’s type of business, product or service.
Required if messageCategory is "01"
merchantCountryCode
Type: string
Format: country
Length: 3
Conditional
Country Code of the Merchant.
Required if messageCategory is "01"
merchantName
Type: string
Max length: 40
Conditional
Merchant name assigned by the Acquirer or Payment System.
Required if messageCategory is "01"
merchantRiskIndicator
Optional
Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
messageCategory
Type: string
One of: 01 02
Required
Identifies the category of the message for a specific use case.

Interpretation of values:

01
PA - Payment
02
NPA - Non-Payment
messageExtension
Max length: 10
Optional
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
messageType
Type: string
One of: AReq ARes CReq CRes PReq PRes RReq RRes Erro
Required
Identifies the type of message that is passed.
messageVersion
Type: string
One of: 2.1.0
Required
Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message.
mobilePhone
Optional
The mobile phone number provided by the Cardholder.
notificationURL
Type: string
Format: url
Max length: 256
Required
Fully qualified URL of the system that receives the CRes message or Error Message. The CRes message is posted by the ACS through the Cardholder browser at the end of the challenge and receipt of the RRes message.
purchaseAmount
Type: string
Regexp: ^\d{0,48}$
Conditional
Purchase amount in minor units of currency with all punctuation removed.
Required if messageCategory is "01" or messageCategory is "02" and threeDSRequestorAuthenticationInd is one of [02, 03]
purchaseCurrency
Type: string
Format: currency
Conditional
Currency in which purchase amount is expressed.
Required if messageCategory is "01" or messageCategory is "02" and threeDSRequestorAuthenticationInd is one of [02, 03]
purchaseDate
Type: string
Conditional
Date and time of the purchase expressed in UTC.
Required if messageCategory is "01" or messageCategory is "02" and threeDSRequestorAuthenticationInd is one of [02, 03]
purchaseExponent
Type: string
Regexp: ^\d$
Conditional
Minor units of currency as specified in the ISO 4217 currency exponent.
Required if messageCategory is "01" or messageCategory is "02" and threeDSRequestorAuthenticationInd is one of [02, 03]
purchaseInstalData
Type: string
Max length: 3
From 2 To 999
Conditional
Indicates the maximum number of authorisations permitted for instalment payments.
Required if threeDSRequestorAuthenticationInd is "03"
payTokenInd
Type: bool
One of: true
Optional
A value of True indicates that the transaction was de-tokenised prior to being received by the ACS. This data element will be populated by the system residing in the 3-D Secure domain where the de-tokenisation occurs (i.e., the 3DS Server or the DS). Note: The Boolean value of true is the only valid response for this field when it is present.
recurringExpiry
Type: string
Format: yyyymmdd
Conditional
Date after which no further authorisations shall be performed.
Required if threeDSRequestorAuthenticationInd is one of [02, 03]
recurringFrequency
Type: string
Regexp: ^\d{0,4}$
Conditional
Indicates the minimum number of days between authorisations.
Required if threeDSRequestorAuthenticationInd is one of [02, 03]
sdkAppID
Type: string
Format: uuid
Required
Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.
sdkEncData
Type: string
Max length: 64000
Required
JWE Object (represented as a string) as defined in Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt.
sdkEphemPubKey
Max length: 256
Required
Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.
sdkMaxTimeout
Type: string
Length: 2
Value: 05 99
Required
Indicates maximum amount of time (in minutes) for all exchanges.
sdkReferenceNumber
Type: string
Max length: 32
Required
Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.
sdkTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
shipAddrCity
Type: string
Max length: 50
Optional
City portion of the shipping address requested by the Cardholder.
shipAddrCountry
Type: string
Length: 3
Conditional
Country of the shipping address requested by the Cardholder.
Required if shipAddrState is not empty
shipAddrLine1
Type: string
Max length: 50
Optional
First line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
shipAddrLine2
Type: string
Max length: 50
Optional
The second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
shipAddrLine3
Type: string
Max length: 50
Optional
The third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
shipAddrPostCode
Type: string
Max length: 16
Optional
The ZIP or other postal code of the shipping address requested by the Cardholder.
shipAddrState
Type: string
Max length: 3
Optional
The state or province of the shipping address associated with the card being used for this purchase.
threeDSCompInd
Type: string
One of: Y N U
Required
Indicates whether the 3DS Method successfully completed.

Interpretation of values:

Y
Successfully completed
N
Did not successfully complete
U
Unavailable— 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.
threeDSRequestorAuthenticationInd
Type: string
Regexp: ^(0[1-6])|([89][0-9])$
Required
Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request.

Interpretation of values:

01
Payment transaction
02
Recurring transaction
03
Instalment transaction
04
Add card
05
Maintain card
06
Cardholder verification as part of EMV token ID&V
threeDSRequestorAuthenticationInfo
Optional
Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.
threeDSRequestorChallengeInd
Type: string
Regexp: ^(0[1-4])|([89][0-9])$
Optional
Indicates whether a challenge is requested for this transaction. For example: For 01-PA, a 3DS Requestor may have concerns about the transaction, and request a challenge. For 02-NPA, a challenge may be necessary when adding a new card to a wallet. For local/regional mandates or other variables.

Interpretation of values:

01
No preference
02
No challenge requested
03
Challenge requested: 3DS Requestor Preference
04
Challenge requested: Mandate
threeDSRequestorID
Type: string
Max length: 35
Required
DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis.
threeDSRequestorName
Type: string
Max length: 40
Required
DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis.
threeDSRequestorPriorAuthenticationInfo
Optional
Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
threeDSRequestorURL
Type: string
Format: url
Max length: 2048
Required
Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3-D Secure system if a problem arises and should provide contact information.
threeDSServerOperatorID
Type: string
Optional
DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS D Server on an individual basis.
threeDSServerRefNumber
Type: string
Optional
Unique identifier assigned by the EMVCo secretariat upon testing and approval.
threeDSServerTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
threeDSServerURL
Type: string
Optional
Fully qualified URL of the 3DS Server to which the DS will send the RReq message after the challenge has completed. Incorrect formatting will result in a failure to deliver the transaction results via the RReq message.
threeRIInd
Type: string
Regexp: ^(0[1-5])|([89][0-9])$
Required
Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing a 3RI request.

Interpretation of values:

01
Recurring transaction
02
Instalment transaction
03
Add card
04
Maintain card information
05
Account verification
transType
Type: string
One of: 01 03 10 11 28
Optional
Identifies the type of transaction being authenticated.

Interpretation of values:

01
Goods/ Service Purchase
03
Check Acceptance
10
Account Funding
11
Quasi-Cash Transaction
28
Prepaid Activation and Load
workPhone
Optional
The work phone number provided by the Cardholder.

Output

Description Comment
acsChallengeMandated
Type: string
One of: Y N
Conditional
Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.
Required if transStatus is "C"
acsOperatorID
Type: string
Max length: 32
Optional
DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis.
acsReferenceNumber
Type: string
Max length: 32
Required
Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.
acsRenderingType
Conditional
Identifies the ACS UI Template that the ACS will first present to the consumer.
Required if deviceChannel is "01" and transStatus is "C"
acsSignedContent
Type: string
Conditional
Contains the JWS object (represented as a string) created by the ACS for the ARes message.
Required if transStatus is "C" and deviceChannel is "01"
acsTransID
Type: string
Format: uuid
Required
Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
acsURL
Type: string
Format: url
Max length: 2048
Conditional
Fully qualified URL of the ACS to be used for the challenge. 02-BRW—3DS Requestor will post the CReq to this URL via the challenge window
Required if deviceChannel is "02" and transStatus is "C"
authenticationType
Type: string
Regexp: ^(0[1-3])$
Conditional
Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message.

Interpretation of values:

01
Static
02
Dynamic
03
OOB
Required if transStatus is "C"
authenticationValue
Type: string
Length: 28
Conditional
Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.
Required if messageCategory is "01" and transStatus is one of [Y, A]
cardholderInfo
Type: string
Max length: 128
Optional
Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”
dsReferenceNumber
Type: string
Max length: 32
Required
EMVCo-assigned unique identifier to track approved DS.
dsTransID
Type: string
Format: uuid
Max length: 36
Required
Universally unique transaction identifier assigned by the DS to identify a single transaction.
eci
Type: string
Max length: 2
Optional
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.
messageExtension
Max length: 10
Optional
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
messageType
Type: string
One of: AReq ARes CReq CRes PReq PRes RReq RRes Erro
Required
Identifies the type of message that is passed.
messageVersion
Type: string
One of: 2.1.0
Required
Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message.
sdkTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
threeDSServerTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
transStatus
Type: string
One of: Y N U A C R
Conditional
Indicates whether a transaction qualifies as an authenticated transaction or account verification.

Interpretation of values:

Y
Authentication/ Account 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
R
Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
Required if messageCategory is "01"
transStatusReason
Type: string
Length: 2
Value: 01 21
Conditional
Provides information on why the Transaction Status field has the specified value.

Interpretation of values:

01
Card authentication failed
02
Unknown Device
03
Unsupported Device
04
Exceeds authentication frequency limit
05
Expired card
06
Invalid card number
07
Invalid transaction
08
No Card record
09
Security failure
10
Stolen card
11
Suspected fraud
12
Transaction not permitted to cardholder
13
Cardholder not enrolled in service
14
Transaction timed out at the ACS
15
Low confidence
16
Medium confidence
17
High confidence
18
Very High confidence
19
Exceeds ACS maximum challenges
20
Non-Payment transaction not supported
21
3RI transaction not supported
Required if transStatus is one of [N, U, R]

5.3. Challenge flow

Challenge request (CReq)

Description Comment
messageType
Type: string
One of: AReq ARes CReq CRes PReq PRes RReq RRes Erro
Required
Identifies the type of message that is passed.
messageVersion
Type: string
One of: 2.1.0 2.2.0
Required
Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message.
messageExtension
Max length: 10
Optional
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
acsTransID
Type: string
Format: uuid
Required
Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
threeDSServerTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
challengeWindowSize
Type: string
One of: 01 02 03 04 05
Required
Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window.

Interpretation of values:

01
250 x 400
02
390 x 400
03
500 x 600
04
600 x 400
05
Full screen

5.4. /postauth endpoint

Input

Key

Format

Required

threeDSServerTransID

UUID

Yes

Output

Description Comment
acsRenderingType
Required
Identifies the ACS UI Template that the ACS will first present to the consumer.
acsTransID
Type: string
Format: uuid
Required
Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
authenticationType
Type: string
Regexp: ^(0[1-3])$
Conditional
Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message.

Interpretation of values:

01
Static
02
Dynamic
03
OOB
Required if transStatus is one of [Y, N]
authenticationValue
Type: string
Length: 28
Conditional
Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.
Required if messageCategory is "01" and transStatus is one of [Y, A]
challengeCancel
Type: string
Regexp: ^(0[14-8])$
Optional
Indicator informing the ACS and the DS that the authentication has been canceled.

Interpretation of values:

01
Cardholder selected "Cancel"
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
dsTransID
Type: string
Format: uuid
Max length: 36
Required
Universally unique transaction identifier assigned by the DS to identify a single transaction.
eci
Type: string
Max length: 2
Optional
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.
interactionCounter
Type: string
Length: 2
Value: 00 99
Required
Indicates the number of authentication cycles attempted by the Cardholder.
messageCategory
Type: string
One of: 01 02
Required
Identifies the category of the message for a specific use case.

Interpretation of values:

01
PA - Payment
02
NPA - Non-Payment
messageExtension
Max length: 10
Optional
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
messageType
Type: string
One of: AReq ARes CReq CRes PReq PRes RReq RRes Erro
Required
Identifies the type of message that is passed.
messageVersion
Type: string
One of: 2.1.0
Required
Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message.
threeDSServerTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
transStatus
Type: string
One of: Y N U A C R
Conditional
Indicates whether a transaction qualifies as an authenticated transaction or account verification.

Interpretation of values:

Y
Authentication/ Account 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
R
Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
Required if messageCategory is "01"
transStatusReason
Type: string
Length: 2
Value: 01 21
Conditional
Provides information on why the Transaction Status field has the specified value.

Interpretation of values:

01
Card authentication failed
02
Unknown Device
03
Unsupported Device
04
Exceeds authentication frequency limit
05
Expired card
06
Invalid card number
07
Invalid transaction
08
No Card record
09
Security failure
10
Stolen card
11
Suspected fraud
12
Transaction not permitted to cardholder
13
Cardholder not enrolled in service
14
Transaction timed out at the ACS
15
Low confidence
16
Medium confidence
17
High confidence
18
Very High confidence
19
Exceeds ACS maximum challenges
20
Non-Payment transaction not supported
21
3RI transaction not supported
Required if transStatus is one of [N, U, R]

5.5. Error object

Description Comment
acsTransID
Type: string
Format: uuid
Optional
Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
dsTransID
Type: string
Format: uuid
Max length: 36
Optional
Universally unique transaction identifier assigned by the DS to identify a single transaction.
errorCode
Type: string
One of: 101 102 103 201 202 203 204 301 302 303 304 305 306 307 402 403 404 405
Required
Code indicating the type of problem identified in the message.

Interpretation of values:

101
Message Received Invalid
102
Message Version Number Not Supported
103
Sent Messages Limit Exceeded
201
Required Data Element Missing
202
Critical Message Extension Not Recognised
203
Format of one or more Data Elements is Invalid according to the Specification
204
Duplicate Data Element
301
Transaction ID Not Recognised
302
Data Decryption Failure
303
Access Denied, Invalid Endpoint
304
ISO Code Invalid
305
Transaction data not valid
306
Merchant Category Code (MCC) Not Valid for Payment System
307
Serial Number not Valid
402
Transaction Timed Out
403
Transient System Failure
404
Permanent System Failure
405
System Connection Failure
errorComponent
Type: string
One of: C S D A
Required
Code indicating the 3-D Secure component that identified the error.

Interpretation of values:

C
3DS SDK
S
3DS Server
D
Directory Server
A
ACS
errorDescription
Type: string
Max length: 2048
Required
Text describing the problem identified in the message.
errorDetail
Type: string
Max length: 2048
Required
Additional detail regarding the problem identified in the message.
errorMessageType
Type: string
One of: ARes AReq PRes PReq CRes CReq RReq RRes Erro
Optional
Identifies the Message Type that was identified as erroneous.
messageType
Type: string
One of: AReq ARes CReq CRes PReq PRes RReq RRes Erro
Required
Identifies the type of message that is passed.
messageVersion
Type: string
One of: 2.1.0
Required
Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message.
sdkTransID
Type: string
Format: uuid
Optional
Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
threeDSServerTransID
Type: string
Format: uuid
Required
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

5.6. Nested objects

DeviceRenderOptions

Description Comment
sdkInterface
Type: string
One of: 01 02 03
Optional
Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.

Interpretation of values:

01
Native
02
HTML
03
Both
sdkUiType
One of: 01 02 03 04 05
Optional
Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.

Interpretation of values:

01
Text
02
Single Select
03
Multi Select
04
OOB
05
HTML Other (valid only for HTML UI)

AcctInfo

Description Comment
chAccAgeInd
Type: string
One of: 01 02 03 04 05
Optional
Length of time that the cardholder has had the account with the 3DS Requestor.

Interpretation of values:

01
No account (guest check-out)
02
Created during this transaction
03
Less than 30 days
04
30−60 days
05
More than 60 days
chAccChange
Type: string
Format: yyyymmdd
Optional
Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
chAccChangeInd
Type: string
One of: 01 02 03 04
Optional
Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

Interpretation of values:

01
Changed during this transaction
02
Less than 30 days
03
30−60 days
04
More than 60 days
chAccDate
Type: string
Format: yyyymmdd
Optional
Date that the cardholder opened the account with the 3DS Requestor.
chAccPwChange
Type: string
Format: yyyymmdd
Optional
Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
chAccPwChangeInd
Type: string
One of: 01 02 03 04 05
Optional
Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.

Interpretation of values:

01
No change
02
Changed during this transaction
03
Less than 30 days
04
30−60 days
05
More than 60 days
nbPurchaseAccount
Type: string
Regexp: ^[0-9]{1,4}$
Max length: 4
Optional
Number of purchases with this cardholder account during the previous six months.
paymentAccAge
Type: string
Format: yyyymmdd
Optional
Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
paymentAccInd
Type: string
One of: 01 02 03 04 05
Optional
Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

Interpretation of values:

01
No account (guest check-out)
02
During this transaction
03
Less than 30 days
04
30−60 days
05
More than 60 days
provisionAttemptsDay
Type: string
Regexp: ^[0-9]{1,3}$
Max length: 3
Optional
Number of Add Card attempts in the last 24 hours.
shipAddressUsage
Type: string
Format: yyyymmdd
Optional
Date when the shipping address used for this transaction was first used with the 3DS Requestor.
shipAddressUsageInd
Type: string
One of: 01 02 03 04
Optional
Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.

Interpretation of values:

01
This transaction
02
Less than 30 days
03
30−60 days
04
More than 60 days
shipNameIndicator
Type: string
One of: 01 02
Optional
Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

Interpretation of values:

01
Account Name identical to shipping Name
02
Account Name different than shipping Name
suspiciousAccActivity
Type: string
One of: 01 02
Optional
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Interpretation of values:

01
No suspicious activity has been observed
02
Suspicious activity has been observed
txnActivityDay
Type: string
Regexp: ^[0-9]{1,3}$
Max length: 3
Optional
Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
txnActivityYear
Type: string
Regexp: ^[0-9]{1,3}$
Max length: 3
Optional
Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

PhoneNumber

MerchantRiskIndicator

Description Comment
deliveryEmailAddress
Type: string
Format: email
Max length: 254
Optional
For Electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeframe
Type: string
One of: 01 02 03 04
Optional
Indicates the merchandise delivery timeframe.

Interpretation of values:

01
Electronic Delivery
02
Same day shipping
03
Overnight shipping
04
Two-day or more shipping
giftCardAmount
Type: string
Regexp: ^\d{0,15}$
Optional
For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount
Type: string
Regexp: ^\d{2}$
Optional
For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
giftCardCurr
Type: string
Format: currency
Optional
For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card, other than those listed in Table A.5.
preOrderDate
Type: string
Format: yyyymmdd
Optional
For a pre-ordered purchase, the expected date that the merchandise will be available.
preOrderPurchaseInd
Type: string
One of: 01 02
Optional
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

Interpretation of values:

01
Merchandise available
02
Future availability
reorderItemsInd
Type: string
One of: 01 02
Optional
Indicates whether the cardholder is reordering previously purchased merchandise.

Interpretation of values:

01
First time ordered
02
Reordered
shipIndicator
Type: string
One of: 01 02 03 04 05 06 07
Optional
Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.

Interpretation of values:

01
Ship to cardholder’s billing address
02
Ship to another verified address on file with merchant
03
Ship to address that is different than the cardholder’s billing address
04
“Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)
05
Digital goods (includes online services, electronic gift cards and redemption codes)
06
Travel and Event tickets, not shipped
07
Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)

MessageExtension

Description Comment
criticalityIndicator
Type: bool
Required
A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.
data
Max length: 8059
Required
The data carried in the extension.
id
Type: string
Max length: 64
Required
A unique identifier for the extension. Note: Payment System Registered Application Provider Identifier (RID) is required as prefix of the ID.
name
Type: string
Max length: 64
Required
The name of the extension data set as defined by the extension owner.

ThreeDSRequestorAuthenticationInfo

Description Comment
threeDSReqAuthData
Type: string
Max length: 2048
Optional
Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. For example, for method: 02—field can carry generic 3DS Requestor authentication information 03—data element can carry information about the provider of the federated ID and related information 04—data element can carry the FIDO attestation data (including the signature) In future versions of the specification, these details are expected to be included
threeDSReqAuthMethod
Type: string
Regexp: ^(0[1-6])|([89][0-9])$
Optional
Mechanism used by the Cardholder to authenticate to the 3DS Requestor.

Interpretation of values:

01
No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)
02
Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials
03
Login to the cardholder account at the 3DS Requestor system using federated ID
04
Login to the cardholder account at the 3DS Requestor system using issuer credentials
05
Login to the cardholder account at the 3DS Requestor system using third-party authentication
06
Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
threeDSReqAuthTimestamp
Type: string
Optional
Date and time in UTC of the cardholder authentication.

ThreeDSRequestorPriorAuthenticationInfo

Description Comment
threeDSReqPriorAuthData
Type: string
Max length: 2048
Optional
Data that documents and supports a specific authentication process. In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included.
threeDSReqPriorAuthMethod
Type: string
Regexp: ^(0[1-4])|([89][1-10])$
Optional
Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.

Interpretation of values:

01
Frictionless authentication occurred by ACS
02
Cardholder challenge occurred by ACS
03
AVS verified
04
Other issuer methods
threeDSReqPriorAuthTimestamp
Type: string
Optional
Date and time in UTC of the prior cardholder authentication.
threeDSReqPriorRef
Type: string
Max length: 36
Optional
This data element provides additional information to the ACS to determine the best approach for handing a request.

ACSRenderingType

Description Comment
acsInterface
Type: string
One of: 01 02
Required
This the ACS interface that the challenge will present to the cardholder.

Interpretation of values:

01
Native UI
02
HTML UI
acsUiTemplate
Type: string
One of: 01 02 03 04 05
Required
Identifies the UI Template format that the ACS first presents to the consumer.

Interpretation of values:

01
Text
02
Single Select
03
Multi Select
04
OOB
05
HTML Other

5.7. Formats

uuid

UUID version 4.

ip

IPv4 or IPv6 address.

yymm

2-digit year and month.

yyyymmdd

4-digit year, 2-digit month and day-of-month.

yyyymmddhhmm

4-digit year, 2-digit month, day-of-month, hour and minute.

yyyymmddhhmmss

4-digit year, 2-digit month, day-of-month, hour, minute and second.

email

Email Address

url

Fully qualified URL

country

3-digit ISO 3166-1 country code string, for Denmark e.g.

{
  "billAddrCountry": "208"
}

for France e.g.

{
  "billAddrCountry": "250"
}

Country codes 901999 are not valid.

currency

3-digit ISO 4217 currency code string, for DKK e.g.

{
  "purchaseCurrency": "208"
}

or EUR

{
  "purchaseCurrency": "978"
}

The following codes cannot be used:

  • 955

  • 956

  • 957

  • 958

  • 959

  • 960

  • 961

  • 962

  • 963

  • 964

  • 999