Skip to content

Risk Engine Adapter

About Risk Adapter

When cardholder authentication occurs during a transaction, a challenge may be necessary because the transaction is deemed high-risk, e.g. above certain thresholds.

To assess the risk associated with the transaction and if a challenge to the cardholder is necessary, the ACS sends/receives proper data elements to/from risk assessment systems via middleware, known as Risk Adapters.

How RBA works

ActiveAccess has been developed to support risk through the following models:

  • Internal Risk: Risk rules pre-defined internally within the application by GPayments. This may include samples or rules commonly used by issuers. The rules are configurable on the Administration UI.
  • External Risk via Adapter: You can create your customised rules in the form of JAR files, as per the Risk Adapter Specification. Once the path of the JAR files has been included in the ActiveAccess configuration file (<AA_HOME>/activeaccess.properties), the rules will be configurable on the Administration UI in the same way as the Internal Risk model. Basic or complex rules can be defined based on the issuer's specific requirements
  • Remote Risk via Adapter: Rules are defined on an external server and called by ActiveAccess using a URL configured on the Administration UI.

The RBA adapters are also designed to have a configurable scoring system. Scoring is fully configurable and each score range can be linked with an authentication method: frictionless, static password, device or OOB.

The following diagram provides an overview of the risk evaluation process.

risk-evaluation-process-flow

Each Risk Adapter has one Parameter and one or more Conditions. Risk assessment systems perform tasks based on values received for these attributes. Risk Adapters can be either Native APIs or REST APIs. These Risk Adapter APIs are explained in further detail in the following sections.

The following diagram shows how risk chains are setup and risk adapters are registered on the Administration UI.

risk-chain-setup

Risk Adapter Specification

Native API Risk Adapter

The Native API Risk Adapter is a JAR file that implements an ACS specified adapter interface, known as Adapter, in a JAR file named rba.adapter. Note that you can rename your Risk Adapters as appropriate for your use.

Adapter development considerations

The following steps must be considered in Risk Adapter development:

  1. Use the correct version of risk.adapter-x for your ACS version (where x represents the risk adapter API version) in your Risk Adapter project.

  2. The Adapter interface in the risk.adapter-x JAR file must be implemented in your Risk Adapter project. This implementation is known as the risk adapter provider. The ACS loads this class at startup and uses it for transaction risk assessment. The ACS enforces the requirement for the provider class to have a public zero-argument constructor so that it can be instantiated during ACS loading.

  3. A risk adapter provider is identified by placing a provider-configuration file in the resource directory META-INF/services. The file's name is the fully-qualified binary name of the service's type, e.g. com.gpayments.rba.api.v1.Adapter. The file contains a list of fully-qualified binary names of concrete provider classes, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#' ('\u0023', NUMBER SIGN); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

Adapter interface methods

The Adapter interface has four methods, which must be implemented in Risk Adapter:

  • Method Name: getAdapterId

    • Description: Returns the ACS assigned UUID to Risk Adapter
    • Input: This method takes no arguments.
    • Output: The output of this method has the following properties:
      • Description: Risk Adapter ID.
      • Length: 36 characters
      • Format: String
      • Accepted Value: Canonical format as defined in IETF RFC 4122
      • Message Inclusion: Required

  • Method Name: getAdapterInfo

    • Description: Returns some information about Risk Adapter
    • Input: This method takes no arguments
    • Output: An instance of AdapterInfo class that contains some information about Risk Adapter AdapterInfo is described in AdapterInfo Data Elements

  • Method Name: getParameter

    • Description: Returns the used Parameter in the Risk Adapter.
    • Input: This method takes no arguments.
    • Output: An instance of Parameter class that contains some information about the used Parameter in Adapter conditions The Parameter class is Described in Parameter Data Elements

  • Method Name: getConditions

    • Description: Returns a list of Risk Adapter conditions
    • Input: This method takes no arguments.
    • Output: List of available Conditions in Risk Adapter. The Condition class is described in Condition Data Elements

RESTful API Risk Adapter

For the RESTful API Risk Adapter, you should provide REST API endpoints that are accessible to the ACS. Note that Adapter-URL refers to the fully qualified RESTful Risk Adapter URL that will be used in transaction risk assessment.

Note

We also provide a Swagger API for the sample REST RBA server that is included in the release package. To use it, run RBA Server and open https://localhost:8446/swagger-ui.html#/ in your browser.

Get Risk Adapter Information

The ACS sends an HTTP request to retrieve information about Risk Adapter, as follows:

  • URL: Adapter-URL
  • Request Method: GET
  • Request Parameters: there is no request parameter for this REST API
  • Response:
    • Name: restfulRBAAdapterInfo
    • Format JSON object of RestfulRBAAdapterInfo type.
    • Description RestfulRBAAdapterInfo. Described in RestfulRBAAdapterInfo Data Elements
    • Inclusion: Required

Transaction Risk Assessment

To estimate the risk for the transaction, the ACS calls an HTTP API of RESTful Risk Adapter, as follows:

  • URL: Adapter-URL
  • Request Method: POST

  • Request Body:

  • Response:

Authentication mechanism for the RESTful API

Certificate based mutual authentication is used as the authentication mechanism for the RESTful API, using the following steps:

  • ACS publishes a CA for adapter communication, in this instance named Adapter CA
  • ACS also issues a server certificate for the adapter. The server certificate should have a serial number attribute set to the AA generated Adapter ID or something to identify the RESTful adapter.
  • ACS uses a client generated certificate issued by the same Adapter CA.
  • the Adapter server implementation must be setup with the CA provided and mutual authentication.
  • ACS will try to connect to the Adapter Server and, if the connection can be established and the serial number matches the record in the database for this adapter, ACS will continue with the adapter otherwise it will throw an error.

AdapterInfo Data Elements

  • Field Name: id

    • Description: The ACS assigned UUID to the Risk Adapter
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122
    • Message Inclusion: Required

  • Field Name: name

    • Description: The ACS assigned name to the Risk Adapter
    • Length: Variable, maximum 100 Characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: version

    • Description: The number that indicates the Risk Adapter version
    • Length: Variable
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: signature

    • Description: Signature to validate Risk Adapter integrity, currently not used, will be introduced in a future version
    • Length: Variable
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

Parameter Data Elements

  • Field Name: name

    • Description: The Risk Adapter name assigned to this parameter
    • Length: 50 characters
    • Format: String
    • Accepted Value: any
    • Message Inclusion: Required

  • Field Name: displayName

    • Description: The Risk Adapter assigned name for displaying this parameter
    • Length: 50 characters
    • Format: String
    • Accepted Value: any
    • Message Inclusion: Required

  • Field Name: paramType

    • Description: The type of Risk Adapter Parameter.
    • Length:
    • Format: ValueType
    • Accepted Value: NULL, NUMERIC, STRING, RANGE, LIST_OF_NUMERIC and LIST_OF_STRING
    • Message Inclusion: Required

  • Field Name: validator

    • Description: A validator for this Parameter. This validator is an instance of a class that implements the ParameterValidator interface. The ParameterValidator interface has a method named isParameterDataValid and returns the boolean result of parameter validation. This method, accepts two arguments;
      The first argument of this method, is an instance of type AReq, described in AReq Data Elements. The second is an instance of a callback class that implements TxCallback. The TxCallback interface has one method named onPreviousTXRequiredByCountOrDays that has two integer arguments and returns a list of AReqWithTransStatus objects. The first parameter is the number of last transactions that should be returned and the second one is the number of days, which we should return the transactions occurred therein. The maximum transactions according to these parameter will be returned as result.
    • Length:
    • Format: An instance of ParameterValidator interface implementor. This field should be ignored in mapping the Parameter object to the JSON object
    • Accepted Value:
    • Message Inclusion:

Condition Data Elements

  • Field Name: adapter

    • Description: The Adapter that the current Condition belongs to; a reference to the current adapter
    • Length:
    • Format: An instance of type Adapter. This field should be ignored in mapping Condition object to JSON object
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: boundParameter

    • Description: The Parameter that is used in this adapter. The current Condition uses it in the risk assessment process; a reference to the current Risk Adapter Parameter
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: name

    • Description: The Risk Adapter name assigned to this condition
    • Length: 50 characters
    • Format: String
    • Accepted Value: any
    • Message Inclusion: Required

  • Field Name: displayName

    • Description: The Risk Adapter name assigned for displaying this condition
    • Length: 50 characters
    • Format: String
    • Accepted Value: any
    • Message Inclusion: Required

  • Field Name: valueType

    • Description: The value types that should be set for Condition values
    • Length:
    • Format: ValueType
    • Accepted Value: NULL, NUMERIC, STRING, RANGE, LIST_OF_NUMERIC and LIST_OF_STRING
    • Message Inclusion: Required

  • Field Name: assessor

    • Description: The condition assessor that is assigned to the adapter Condition and is responsible for getting the condition assessment result
    • Length:
    • Format: An instance of ConditionAssessor interface implementor.
      The interface ConditionAssessor has one method, named assess. This method accepts five parameters of type AReq, AdditionalInfo, TxCallback, Condition and ConditionValue and returns the assessment result as AssessmentResult. AssessmentResult and AdditionalInfo are described in AssessmentResult Data Elements and AdditionalInfo Data Elements.
      This field should be ignored in mapping the Condition object to the JSON object.
    • Accepted Value:
    • Message Inclusion: Required

AssessmentResult Data Elements

  • Field Name: score

    • Description: Risk assessment as a number
    • Length:
    • Format: Integer
    • Accepted Value: 0-100
    • Message Inclusion: Required

  • Field Name: whatToDoNext

    • Description: The behavior that should be done about the remained risk-chain assessments
    • Length:
    • Format: JSON object of behaviour.
    • Accepted Value: CONTINUE, FINISH
    • Message Inclusion: Required

RestfulRBAAdapterInfo Data Elements

  • Field Name: adapterInfo

    • Description: Some information about Risk Adapter
    • Length:
    • Format: JSON format of the AdapterInfo object, described in AdapterInfo Data Elements
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: parameter

    • Description: The Parameter used in the Risk Adapter
    • Length:
    • Format: JSON format of theParameter object, described in Parameter Data Elements
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: conditions

    • Description: List of available conditions (RemoteCondition) in the current adapters
    • Length:
    • Format: List of RemoteCondition objects in JSON format, described in RemoteCondition Data Elements
    • Accepted Value:
    • Message Inclusion: Required

RemoteCondition Data Elements

In addition to the aforementioned Condition properties, RemoteCondition has two additional fields that may be necessary for historic data

  • Field Name: previousTx

    • Description: Indicates the number of previous transactions required for risk assessment
    • Length:
    • Format: Integer
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: previousTxInDays

    • Description: Indicates the number of days of previous transactions required for risk assessment
    • Length:
    • Format: Integer
    • Accepted Value:
    • Message Inclusion: Optional

RemoteAssessmentRequest Data Elements

  • Field Name: aReq

    • Description: The AReq message of the current transaction.
    • Length:
    • Format: JSON object of AReq type, described in AReq Data Elements
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: additionalInfo

    • Description: Some additional Info for risk assessment
    • Length:
    • Format: JSON object of AdditionalInfo type. AdditionalInfo is explained in AdditionalInfo Data Elements section.
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: previousData

    • Description: The historic data required for risk assessment
    • Length:
    • Format: List of AReqWithTransStatus in JSON format. AReqWithTransStatus is explained in AReqWithTransStatus Data Elements section.
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: conditionName

    • Description: Name of Condition to be processed
    • Length: 50 characters
    • Format: String
    • Accepted Value: Any
    • Message Inclusion: Required

  • Field Name: conditionValue

    • Description: Some settings for Condition, such as condition value, default behaviour and the output score
    • Length:
    • Format: JSON object of ConditionValue type, described in ConditionValue Data Elements
    • Accepted Value:
    • Message Inclusion: Required

ConditionValue Data Elements

  • Field Name: condition

    • Description: Condition that the condition value is assigned to
    • Length:
    • Format: JSON object of Condition, described in Condition Data Elements
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: numeric

    • Description: The condition value passed to the Risk Adapter if, and only if, ValueType of Condition is NUMERIC
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: range

    • Description: The condition value that should be passed to the Risk Adapter, if and only if ValueType of Condition be equal to RANGE type
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: string

    • Description: The condition value to be passed to the Risk Adapter if, and only if, ValueType of Condition is STRING
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: listOfNumeric

    • Description: The condition value to be passed to the Risk Adapter if, and only if, ValueType of Condition is LIST_OF_NUMERIC
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: listOfString

    • Description: The condition value to be passed to the Risk Adapter if, and only if, ValueType of Condition is LIST_OF_STRING
    • Length:
    • Format:
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: whenMatches

    • Description: The default behaviour when the condition matches
    • Length:
    • Format: behaviour
    • Accepted Value: CONTINUE, FINISH
    • Message Inclusion: Required

  • Field Name: whenMismatch

    • Description: The default behaviour when the condition mismatches
    • Length:
    • Format: behaviour
    • Accepted Value: CONTINUE, FINISH
    • Message Inclusion: Required

  • Field Name: scoreWhenMatches

    • Description: The output score when the condition matches
    • Length:
    • Format: Integer
    • Accepted Value: 0-100
    • Message Inclusion: Required

AReq Data Elements

  • Field Name: threeDSCompInd

    • Description: Indicates whether the 3DS Method was successfully completed
    • Length: 1 character
    • Format: String
    • Accepted Value:
      • Y = Successfully completed
      • N = Did not successfully complete
      • U = Unavailable
    • Message Inclusion: Optional

  • Field Name: threeDSRequestorAuthenticationInd

    • Description: Indicates the type of authentication request. This data element provides additional information to the ACS to determine the best approach for handling the authentication request
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Cardholder selected “Cancel”
      • 02 = 3DS Requestor cancelled Authentication.
      • 03 = Transaction Abandoned
      • 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–79 = Reserved for future EMVCo use(values invalid until defined by EMVCo)
      • 80-99 = Reserved for future DS use
    • Message Inclusion: Optional

  • Field Name: threeDSRequestorAuthenticationInfo

    • Description: 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 will carry the data that the ACS will use to verify the authentication process, described in threeDSRequestorAuthenticationInfo Data Elements
    • Length: Variable
    • Format: Object
    • Accepted Value:
    • Message Inclusion: Optional
    • Conditional Inclusion: Optional but inclusion recommended

  • Field Name: threeDSRequestorChallengeInd

    • Description: Indicates whether a challenge is to be requested for the transaction
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = No preference
      • 02 = No challenge requested
      • 03 = Challenge requested: 3DS Requestor Preference
      • 04 = Challenge requested: Mandate
      • 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
      • 80-99 = Reserved for DS use
    • Message Inclusion: Optional

  • Field Name: threeDSRequestorID

    • Description: DS assigned 3DS Requestor identifier.
    • Length: Variable, maximum 35 characters
    • Format: String
    • Accepted Value: Any individual DS may impose specific formatting and character requirements on the contents of this field
    • Message Inclusion: Required

  • Field Name: threeDSRequestorName

    • Description: DS assigned 3DS Requestor name.
    • Length: Variable, maximum 40 characters
    • Format: String
    • Accepted Value: Any individual DS may impose specific formatting and character requirements on the contents of this field
    • Message Inclusion: Required

  • Field Name: threeDSRequestorPriorAuthenticationInfo

    • Description: Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction, described in threeDSRequestorPriorAuthenticationInfo Data Elements
    • Length: Variable
    • Format: Object
    • Accepted Value:
    • Message Inclusion: Optional
    • Conditional Inclusion: Optional but inclusion recommended

  • Field Name: threeDSRequestorURL

    • Description: Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3-D Secure system for when a problem arises, and should provide contact information.
    • Length: Variable, maximum 2048 characters
    • Format: String
    • Accepted Value: Fully qualified URL
    • Message Inclusion: Required

  • Field Name: threeDSServerRefNumber

    • Description: Unique identifier assigned by the EMVCo Secretariat upon testing and approval
    • Length: Variable, maximum 32 characters
    • Format: String
    • Accepted Value: Set by the EMVCo Secretariat
    • Message Inclusion: Required

  • Field Name: threeDSServerOperatorID

    • Description: DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS Server
    • Length: Variable, maximum 32 characters
    • Format: String
    • Accepted Value: Any individual DS may impose specific formatting and character requirements on the contents of this field
    • Message Inclusion: Conditional
    • Conditional Inclusion: Requirements for the presence of this field are DS specific

  • Field Name: threeDSServerTransID

    • Description: Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements
    • Message Inclusion: Required

  • Field Name: threeDSServerURL

    • Description: 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.
    • Length: Variable, maximum 2048 characters
    • Format: String
    • Accepted Value: Fully qualified URL
    • Message Inclusion: Required

  • Field Name: threeRIInd

    • Description: Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handling the 3RI request
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Recurring transaction
      • 02 = Instalment transaction
      • 03 = Add card
      • 04 = Maintain card information
      • 05 = Account verification
      • 06–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
      • 80-99 = Reserved for DS use
    • Message Inclusion: Required

  • Field Name: acctType

    • Description: Indicates the type of account. For example, for a multi-account card product
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Not Applicable
      • 02 = Credit
      • 03 = Debit
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required if 3DS Requestor is asking cardholder which Account Type they are using before making the purchase Required in some markets (for example, for Merchants in Brazil). Otherwise, it is optional.

  • Field Name: acquirerBIN

    • Description: Acquiring institution identification code as assigned by the DS receiving the AReq message
    • Length: Variable, maximum 11 characters
    • Format: String
    • Accepted Value: This value correlates to the Acquirer BIN as defined by each Payment System or DS.
    • Message Inclusion: 01-PA: Required, 02-NPA: Optional

  • Field Name: acquirerMerchantID

    • Description: 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
    • Length: Variable, maximum 35 characters
    • Format: String
    • Accepted Value: Individual DS may impose specific formatting and character requirements on the contents of this field
    • Message Inclusion: 01-PA: Required, 02-NPA: Optional

  • Field Name: addrMatch

    • Description: Indicates whether the cardholder Shipping Address and cardholder Billing Address are the same
    • Length: 1 characters
    • Format: String
    • Accepted Value:
      • Y = Shipping Address matches Billing Address
      • N = Shipping Address does not match Billing Address
    • Message Inclusion: Optional

  • Field Name: broadInfo

    • Description: Unstructured information sent between the 3DS Server, the DS and the ACS
    • Length: 4096
    • Format: String (JSON object)
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Requirements for the presence of this field are DS specific

  • Field Name: browserAcceptHeader

    • Description: Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser
    • Length: Variable, maximum 2048 characters
    • Format: String
    • Accepted Value: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion
    • Message Inclusion: Required

  • Field Name: browserIP

    • Description: IP address of the browser as returned by the HTTP headers to the 3DS Requestor
    • Length: Variable, maximum 45 characters
    • Format: String
    • Accepted Value:
      • IPv4 address is represented in the decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 to 255. Example IPv4 address: 1.12.123.255
      • IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example IPv6 address: 2011:0db8:85 a3:0101:0101:8a2e:03 70:7334
    • Message Inclusion: Conditional
    • Conditional Inclusion: Include this field where regionally acceptable.

  • Field Name: browserJavaEnabled

    • Description: Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator. javaEnabled property.
    • Length:
    • Format: Boolean
    • Accepted Value: true, false
    • Message Inclusion: Required

  • Field Name: browserLanguage

    • Description: Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property
    • Length: Variable, 1-8 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: browserColorDepth

    • Description: Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from the cardholder's browser using the screen.colorDepth property.
    • Length: Variable, 1-2 characters
    • Format: String
    • Accepted Value:
      • 1 = 1 bit
      • 4 = 4 bits
      • 8 = 8 bits
      • 15 = 15 bits
      • 16 = 16 bits
      • 24 = 24 bits
      • 32 = 32 bits
      • 48 = 48 bits
    • Message Inclusion: Required

  • Field Name: browserScreenHeight

    • Description: Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property
    • Length: Variable, 1-6 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: browserScreenWidth

    • Description: Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property
    • Length: Variable, 1-6 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: browserTZ

    • Description: Time difference between UTC time and the cardholder's browser local time, in minutes
    • Length: Variable, 1-5 characters
    • Format: String
    • Accepted Value: Value is returned from the getTimezoneOffset() method
    • Message Inclusion: Required

  • Field Name: browserUserAgent

    • Description: Exact content of the HTTP user-agent header
    • Length: Variable, maximum 2048 characters
    • Format: String
    • Accepted Value: If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion
    • Message Inclusion: Required

  • Field Name: cardExpiryDate

    • Description: Expiry date of the PAN or token supplied to the 3DS Requestor by the cardholder
    • Length: 4 characters
    • Format: String (accepted format: YYMM)
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: The requirements for the presence of this field are DS specific

  • Field Name: acctInfo

    • Description: Additional information about the cardholder’s account provided by the 3DS Requestor, described in acctInfo Data Elements
    • Length: Variable
    • Format: Object
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: acctNumber

    • Description: Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, token.
    • Length: Variable, 13-19 characters
    • Format: String
    • Accepted Value: Format represented in ISO 7812.
    • Message Inclusion: Required

  • Field Name: acctID

    • Description: Additional information about the account optionally provided by the 3DS Requestor
    • Length: Variable, maximum 64 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: billAddrCity

    • Description: The city of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrCountry

    • Description: The country of the cardholder billing address associated with the card used for this transaction
    • Length: 3 characters
    • Format: String
    • Accepted Value: ISO 3166-1 numeric three-digit country code, other than exceptions listed in Table A.5.
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required if cardholder billing address state is present. 01-PA: Required unless market or regional mandate restricts sending this information. 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrLine1

    • Description: First line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrLine2

    • Description: Second line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrLine3

    • Description: Third line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrPostCode

    • Description: ZIP or other postal code of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 16 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, 02-NPA: Required (if available) unless market or regional mandate restricts sending this information.

  • Field Name: billAddrState

    • Description: The state or province of the cardholder billing address associated with the card used for this transaction
    • Length: Variable, maximum 16 characters
    • Format: String
    • Accepted Value: Country subdivision code defined in ISO 3166-2
    • Message Inclusion: Conditional
    • Conditional Inclusion: 01-PA: Required unless market or regional mandate restricts sending this information, or state is not applicable for this country. 02-NPA: Required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country.

  • Field Name: email

    • Description: The email address associated with the account that is either entered by the cardholder or is on file with the 3DS Requestor
    • Length: Variable, maximum 254 characters
    • Format: String
    • Accepted Value: To meet the requirements of Section 3.4 of IETF RFC 5322.
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: homePhone

    • Description: The home phone number provided by the cardholder, described in homePhone Data Elements
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: mobilePhone

    • Description: The mobile phone number provided by the cardholder, described in mobilePhone Data Elements
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: cardholderName

    • Description: Name of the cardholder
    • Length: Variable, 2-45 characters
    • Format: String
    • Accepted Value: Alphanumeric special characters, listed in EMV Book 4, “Appendix B”.
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrCity

    • Description: City portion of the shipping address requested by the cardholder
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrCountry

    • Description: Country of the shipping address requested by the cardholder
    • Length: 3 characters
    • Format: String
    • Accepted Value: ISO 3166-1 three-digit country code
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required if cardholder shipping address state is present. Required, if available, unless market or regional mandate restricts sending this information.

  • Field Name: shipAddrLine1

    • Description: First line of the street address or equivalent local portion of the shipping address requested by the cardholder
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrLine2

    • Description: Second line of the street address or equivalent local portion of the shipping address requested by the cardholder
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrLine3

    • Description: Third line of the street address or equivalent local portion of the shipping address requested by the cardholder
    • Length: Variable, maximum 50 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrPostCode

    • Description: The ZIP or other postal code of the shipping address requested by the cardholder
    • Length: Variable, maximum 16 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: shipAddrState

    • Description: The state or province of the shipping address associated with the card being used for this transaction
    • Length: Variable, maximum 3 characters
    • Format: String
    • Accepted Value: Country subdivision code defined in ISO 3166-2
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information or state is not applicable for this country.

  • Field Name: workPhone

    • Description: The work phone number provided by the cardholder. Described in workPhone Data Elements
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information

  • Field Name: deviceChannel

    • Description: Indicates the type of channel interface being used to initiate the transaction
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = App-based (APP)
      • 02 = Browser (BRW)
      • 03 = 3DS Requestor Initiated (3RI)
      • 04–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
      • 80–99 = Reserved for DS use
    • Message Inclusion: Required

  • Field Name: deviceInfo

    • Description: Device information gathered by the 3DS SDK from a consumer device as Base64url encoded JSON name/value pairs. This will be obtained from the SDK as encrypted data and populated by the DS, as unencrypted data, to the ACS.
    • Length: Variable, maximum 64000 characters
    • Format: Object
    • Accepted Value: Base64url encoded JSON object
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required between the DS and ACS but will not be present from 3DS Server to DS

  • Field Name: deviceRenderOptions

    • Description: Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK, described in deviceRenderOptions Data Elements
    • Length: Variable, maximum 64000 characters
    • Format: JSON object
    • Message Inclusion: Required

  • Field Name: dsReferenceNumber

    • Description: EMVCo assigned unique identifier to track approved DS
    • Length: Variable, maximum 32 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: The DS will populate the AReq with this data element prior to passing it to the ACS

  • Field Name: dsTransID

    • Description: Universally unique transaction identifier assigned by the DS to identify a single transaction
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions as long as the output meets specified requirements
    • Message Inclusion: Conditional
    • Conditional Inclusion: The DS will populate the AReq with this data element prior to passing to the ACS. Required in error messages if available (e.g. can be obtained from a message or is generated).

  • Field Name: dsURL

    • Description: URL of the DS to which the ACS will send the RReq if a challenge occurs. The ACS is responsible for storing this value for later use in the transaction for sending the RReq to the DS.
    • Length: Variable, maximum 2048 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required between the DS and ACS but will not be present between the 3DS Server and DS

  • Field Name: payTokenInd

    • Description: A value of true indicates that the transaction was detokenised 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 detokenisation 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.
    • Length:
    • Format: Boolean
    • Accepted Value: true
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required if there is detokenisation of an account number

  • Field Name: purchaseInstalData

    • Description: Indicates the maximum number of authorisations permitted for instalment payments
    • Length: Variable, maximum 3 characters
    • Format: String
    • Accepted Value: Value greater than 1
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required if the merchant and cardholder have agreed to instalment payments, i.e. if 3DS Requestor Authentication Indicator = 03. Omitted if not an instalment payment authentication.

  • Field Name: mcc

    • Description: DS specific code describing the merchant’s type of business, product or service
    • Length: 4 characters
    • Format: String
    • Accepted Value: This value correlates to the merchant category code as defined by each payment system or DS
    • Message Inclusion: 1-PA: Required, 02-NPA: Optional

  • Field Name: merchantCountryCode

    • Description: Country code of the merchant. This value correlates to the merchant country code as defined by each payment system or DS
    • Length: 3 characters
    • Format: String
    • Accepted Value: ISO 3166-1 numeric three-digit country code. The same value must be used in the authorisation request.
    • Message Inclusion: 1-PA: Required, 02-NPA: Optional

  • Field Name: merchantName

    • Description: Merchant name assigned by the acquirer or payment system
    • Length: Variable, maximum 40 characters
    • Format: String
    • Accepted Value: Same name used in the authorisation message as defined in ISO 8583
    • Message Inclusion: 1-PA: Required, 02-NPA: Optional

  • Field Name: merchantRiskIndicator

    • Description: Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted, described in merchantRiskIndicator Data Elements
    • Length: Variable
    • Format: Object
    • Accepted Value: Data will be formatted into a JSON object prior to being placed into the device merchant risk indicator field of the message.
    • Message Inclusion: Optional

  • Field Name: messageCategory

    • Description: Identifies the category of the message for a specific use case
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01-PA
      • 02-NPA
    • Message Inclusion: Required

  • Field Name: messageExtension

    • Description: Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a message extension, described in messageExtension Data Elements
    • Length: Variable, maximum 81920 bytes
    • Format: Array
    • Accepted Value:
    • Message Inclusion: Conditional
    • Conditional Inclusion: Conditions to be set by each DS.

  • Field Name: messageVersion

    • Description: Protocol version identifier. This is version of the protocol specification utilised by the system creating this message. The message version number is set by the protocol version of the 3DS Server from which AReq message originates. The message version number does not change during a 3DS transaction.
    • Length: Variable, 5-8 characters
    • Format: String
    • Accepted Value:
      • 2.0.0 (deprecated)
      • 2.1.0 (active)
    • Message Inclusion: Required

  • Field Name: notificationURL

    • Description: 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 on receipt of the RRes message.
    • Length: Variable, maximum 256 characters
    • Format: String
    • Accepted Value: Fully qualified URL
    • Message Inclusion: Required

  • Field Name: purchaseAmount

    • Description: Purchase amount in minor units of currency with all punctuation removed. When used in conjunction with the purchase currency exponent field, proper punctuation can be calculated.
    • Length: Variable, 48 characters
    • Format: String
    • Accepted Value: Example: If the purchase amount is USD 123.45, element will contain the value 12345
    • Message Inclusion: 1-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02-NPA if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: purchaseCurrency

    • Description: Currency in which the purchase amount is expressed.
    • Length: 3 characters
    • Format: String
    • Accepted Value: ISO 4217 three-digit currency code
    • Message Inclusion: 1-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02-NPA if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: purchaseExponent

    • Description: Minor units of currency as specified in the ISO 4217 currency exponent
    • Length: 1 character
    • Format: String
    • Accepted Value:
    • Message Inclusion: 1-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02-NPA if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: purchaseDate

    • Description: Date and time of the purchase, expressed in UTC.
    • Length: 14 characters
    • Format: String (Date Format: YYYYMMDDHHMMSS)
    • Accepted Value:
    • Message Inclusion: 1-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02-NPA if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: recurringExpiry

    • Description: Date after which no further authorisations shall be performed
    • Length: 8 characters
    • Format: String (Date Format: YYYYMMDDHH)
    • Accepted Value:
    • Message Inclusion: 1-PA: Conditional, 02-NPA: Conditional
    • Conditional Inclusion: Required if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: recurringFrequency

    • Description: Indicates the minimum number of days between authorisations.
    • Length: Variable, 4 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: 1-PA: Conditional, 02-NPA: Conditional
    • Conditional Inclusion: Required if 3DS Requestor Authentication Indicator = 02 or 03

  • Field Name: sdkAppID

    • Description: Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation or update
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions as long as the output meets specified requirements.
    • Message Inclusion: Required

  • Field Name: sdkEphemPubKey

    • Description: 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
    • Length: Variable, 256 characters
    • Format: Object, JWK
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: sdkMaxTimeout

    • Description: Indicates maximum amount of time, in minutes, for all exchanges.
    • Length: 2 characters
    • Format: String
    • Accepted Value: Greater than or = 5
    • Message Inclusion: Required

  • Field Name: sdkReferenceNumber

    • Description: 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
    • Length: Variable, 32 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: sdkTransID

    • Description: Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions as long as the output meets specified requirements
    • Message Inclusion: Required

  • Field Name: transType

    • Description: Identifies the type of transaction being authenticated.
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Goods/ Service Purchase
      • 03 = Check Acceptance
      • 10 = Account Funding
      • 11 = Quasi-Cash Transaction
      • 28 = Prepaid Activation and Load. Note: Values derived from the 8583 ISO Standard.
    • Message Inclusion: Conditional
    • Conditional Inclusion: This field is required in some markets (e.g. for merchants in Brazil), otherwise, optional

threeDSRequestorAuthenticationInfo Data Elements

  • Field Name: threeDSReqAuthData

    • Description: 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 will carry the data for the ACS to 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
    • Length: Variable, maximum 2048 bytes
    • Format: String
    • Accepted Value: Any
    • Message Inclusion:

  • Field Name: threeDSReqAuthMethod

    • Description: Mechanism used by the cardholder to authenticate to the 3DS Requestor
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 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 a 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 a FIDO Authenticator
      • 07–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
      • 80–99 = Reserved for DS use

  • Field Name: threeDSReqAuthTimestamp

    • Description: Date and time in UTC of the cardholder authentication
    • Length: 12 characters
    • Format: String (Date Format: YYYYMMDDHHMM)
    • Accepted Value:

threeDSRequestorPriorAuthenticationInfo Data Elements

  • Field Name: threeDSReqPriorAuthData

    • Description: 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.
    • Length: Maximum 2048 bytes
    • Format: Any
    • Accepted Value:

  • Field Name: threeDSReqPriorAuthMethod

    • Description: Mechanism used by the cardholder to previously authenticate to the 3DS Requestor
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Frictionless authentication by ACS
      • 02 = Cardholder challenge by ACS
      • 03 = AVS verified 04 = Other issuer methods
      • 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
      • 80–99 = Reserved for DS use

  • Field Name: threeDSReqPriorAuthTimestamp

    • Description: Date and time in UTC of the prior cardholder authentication
    • Length: 12 characters
    • Format: String (Date Format: YYYYMMDDHHMM)
    • Accepted Value:

  • Field Name: threeDSReqPriorRef

    • Description: This data element provides additional information to the ACS to determine the best approach for handling a request
    • Length: 36 characters
    • Format: String
    • Accepted Value: This data element contains an ACS transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder)

acctInfo Data Elements

  • Field Name: chAccAgeInd

    • Description: Length of time that the cardholder has had the account with the 3DS Requestor
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 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

  • Field Name: chAccChange

    • Description: Date that the cardholder’s account information with the 3DS Requestor was last changed. Information includes billing or shipping address, new payment account, or new user/s added
    • Length: 8 characters
    • Format: String (Date Format: YYYYMMDD)
    • Accepted Value:

  • Field Name: chAccChangeInd

    • Description: Length of time since the cardholder’s account information with the 3DS Requestor was last changed. Information includes billing or shipping address, new payment account, or new user/s added.
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Changed during this transaction
      • 02 = Less than 30 days
      • 03 = 30−60 days
      • 04 = More than 60 days

  • Field Name: chAccDate

    • Description: Date that the cardholder opened the account with the 3DS Requestor
    • Length: 8 characters
    • Format: String (Date Format: YYYYMMDD)
    • Accepted Value:

  • Field Name: chAccPwChange

    • Description: Date that cardholder’s account with the 3DS Requestor had a password change or account reset
    • Length: 8 characters
    • Format: String (Date Format: YYYYMMDD)
    • Accepted Value:

  • Field Name: chAccPwChangeInd

    • Description: Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = No change
      • 02 = Changed during this transaction
      • 03 = Less than 30 days
      • 04 = 30−60 days
      • 05 = More than 60 days

  • Field Name: nbPurchaseAccount

    • Description: Number of purchases using this cardholder account during the last six months
    • Length: Maximum 4 characters
    • Format: String
    • Accepted Value:

  • Field Name: provisionAttemptsDay

    • Description: Number of attempts made to add a card in the last 24 hours
    • Length: Maximum 3 characters
    • Format: String
    • Accepted Value:

  • Field Name: txnActivityDay

    • Description: Number of transactions (successful and abandoned), in the last 24 hours, for this cardholder's account with the 3DS Requestor, across all payment accounts
    • Length: Maximum 3 characters
    • Format: String
    • Accepted Value:

  • Field Name: txnActivityYear

    • Description: Number of transactions (successful and abandoned), in the last year, for this cardholder account with the 3DS Requestor, across all payment accounts
    • Length: Maximum 3 characters
    • Format: String
    • Accepted Value:

  • Field Name: paymentAccAge

    • Description: Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor
    • Length: 8 characters
    • Format: String (Date Format: YYYYMMDD)
    • Accepted Value:

  • Field Name: paymentAccInd

    • Description: Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = No account (guest check-out)
      • 02 = During this transaction
      • 03 = Less than 30 days
      • 04 = 30−60 days
      • 05 = More than 60 days

  • Field Name: shipAddressUsage

    • Description: Date when the shipping address used for this transaction was first used with the 3DS Requestor
    • Length: 8 characters
    • Format: String (Date format = YYYYMMDD)
    • Accepted Value:

  • Field Name: shipAddressUsageInd

    • Description: Indicates when the shipping address used for this transaction was first used with the 3DS Requestor
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = This transaction
      • 02 = Less than 30 days
      • 03 = 30−60 days
      • 04 = More than 60 days

  • Field Name: shipNameIndicator

    • Description: Indicates if the cardholder name on the account is identical to the shipping name used for this transaction
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Account name identical to shipping name
      • 02 = Account name different to shipping name

  • Field Name: suspiciousAccActivity

    • Description: Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = No suspicious activity has been observed
      • 02 = Suspicious activity has been observed

homePhone Data Elements

  • Field Name: cc

    • Description: Country code section of the number
    • Length: 1-3 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information

  • Field Name: subscriber

    • Description: Subscriber section of the number
    • Length: Variable, maximum 15 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information

mobilePhone Data Elements

  • Field Name: cc

    • Description: Country code section of the number
    • Length: 1-3 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information

  • Field Name: subscriber

    • Description: Subscriber section of the number
    • Length: Variable, maximum 15 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information

workPhone Data Elements

  • Field Name: cc

    • Description: Country code section of the number
    • Length: 1-3 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available unless market or regional mandate restricts sending this information

  • Field Name: subscriber

    • Description: Subscriber section of the number
    • Length: Variable, maximum 15 characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required, if available, unless market or regional mandate restricts sending this information

deviceRenderOptions Data Elements

  • Field Name: sdkInterface

    • Description: Lists all SDK interface types supported by the device for displaying specific challenge user interfaces within the SDK
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Native
      • 02 = HTML
      • 03 = Both

  • Field Name: sdkUiType

    • Description: Lists all UI types supported by the device for displaying specific challenge user interfaces within the SDK
    • Length: 2 characters
    • Format: Array of String
    • Accepted Value:
      • 01 = Text
      • 02 = Single Select
      • 03 = Multi Select
      • 04 = OOB
      • 05 = HTML Other (valid only for HTML UI)

merchantRiskIndicator Data Elements

  • Field Name: deliveryEmailAddress

    • Description: For electronic delivery, the email address to which the merchandise was delivered
    • Length: Maximum 254 characters
    • Format: String
    • Accepted Value:

  • Field Name: deliveryTimeframe

    • Description: Indicates the merchandise delivery timeframe
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Electronic delivery
      • 02 = Same day shipping
      • 03 = Overnight shipping
      • 04 = Two or more days shipping

  • Field Name: giftCardAmount

    • Description: For prepaid or gift card purchases, the purchase amount total of prepaid or gift cards, in major units (for example, USD 123.45 is 123).
    • Length: Maximum 15 characters
    • Format: String
    • Accepted Value:

  • Field Name: giftCardCount

    • Description: For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased
    • Length: 2 characters
    • Format: String
    • Accepted Value:

  • Field Name: giftCardCurr

    • Description: For prepaid or gift card purchases, the currency code of the cards as defined in ISO 4217, other than those listed in Table A.5
    • Length: 3 characters
    • Format: String
    • Accepted Value:

  • Field Name: preOrderDate

    • Description: For a pre-ordered purchase, the expected date that the merchandise will be available
    • Length: 8 characters
    • Format: String (Date format = YYYYMMDD )
    • Accepted Value:

  • Field Name: preOrderPurchaseInd

    • Description: Indicates whether the cardholder is placing an order for merchandise with a future availability or release date
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Merchandise available
      • 02 = Future availability

  • Field Name: reorderItemsInd

    • Description: Indicates whether the cardholder is reordering previously purchased merchandise
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = First time ordered
      • 02 = Reordered

  • Field Name: shipIndicator

    • Description: Indicates the 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 goods are digital, use the shipping indicator code that describes the most expensive item.
    • Length: 2 characters
    • Format: String
    • Accepted Value:
      • 01 = Ship to cardholder’s billing address
      • 02 = Ship to another verified address on file with merchant
      • 03 = Ship to address that is different to the cardholder’s billing address
      • 04 = “Ship to store” / pick-up at local store (Store address to 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, media subscriptions, etc.)

messageExtension Data Elements

  • Field Name: criticalityIndicator

    • Description: A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message
    • Length:
    • Format: Boolean
    • Accepted Value: true, false

  • Field Name: data

    • Description: The data carried in the extension
    • Length: Variable, maximum 8059 characters
    • Format: Object
    • Accepted Value:

  • Field Name: id

    • Description: A unique identifier for the extension. Note: the payment system registered application provider identifier (RID) is required as a prefix of the ID
    • Length: Variable, maximum 64 characters
    • Format: String
    • Accepted Value:

  • Field Name: name

    • Description: The name of the extension data set as defined by the extension owner
    • Length: Variable, maximum 64 characters
    • Format: String
    • Accepted Value:

AdapterRiskAssessmentOutput Data Elements

  • Field Name: messageType

    • Description: returns type of getAdapterRiskAssessmentOutput output.
    • Length:
    • Format: RiskAssessmentEnum enum
    • Accepted Value:
      • RiskAssessmentEnum.RAO = Successful risk assessment
      • RiskAssessmentEnum.RAE = Unsuccessful risk assessment
    • Message Inclusion: Required

  • Field Name: riskAssessment

    • Description: The result of a transaction risk assessment evaluated by a Risk System. This field is of the type RiskAssessment with the following instance variables:

      • Field Name: riskServerTransId

        • Description: The optional Risk System ID assigned to the transaction
        • Length:
        • Format: String
        • Accepted Value:
        • Message Inclusion: Optional

      • Field Name: policy_score

        • Description: The sum of all risk weights from triggered rules, in the range [-100 .. 100]. 0 is considered neutral. Positive values indicate trusted devices, negative values indicate anomalies. The higher the negative the value, the greater the risk.
        • Length: 2 characters
        • Format: decimal integer
        • Accepted Value: [-100, 100]
        • Message Inclusion: Required

      • Field Name: reason_code

        • Description: The names of the rules fired for this query. The name of each rule is returned as a separate name/value pair (multiple reason_code keys can be returned in a single response).
        • Length: Variable
        • Format: Array of strings
        • Accepted Value:
        • Message Inclusion:

      • Field Name: risk_rating

        • Description: Risk mapped according to policy_score
        • Length: Variable
        • Format: String
        • Accepted Value: high, medium, low, neutral, trusted
        • Message Inclusion: Required

      • Field Name: review_status

        • Description: Status mapped according to policy_score
        • Length: Variable
        • Format: String
        • Accepted Value: reject, review, pass
        • Message Inclusion: Required
      • Message Inclusion: Conditional
      • Conditional Inclusion: Required if messageType equals RiskAssessmentEnum.RAO

  • Field Name: message

    • Description: Any messages required to be returned should be maintained in this attribute
    • Length: Variable
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

AdditionalInfo Data Elements

  • Field Name: clientId
    • Description: Client ID
    • Length: 15 characters
    • Format: String
    • Accepted Value: Decimal numbers