API Reference

On this page

Requests and responses for deviceChannel = 02 i.e., browser

The direct integration to the 3DS Server and the integration through the 3DS Web SDK uses deviceChannel = 02.

/3ds2/lookup Request: parameters description

Direct integration to 3DS Server: /3ds2/lookup - Sample request

Integration through the Web SDK in toolkit workflow: /3ds2/lookup - Sample request

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
acctNumberAccount or card number of the cardholder.

note

Enter the acctNumber as digits without any space or special character between the digits.

Required13-19String
threeDSMethodNotificationURL3DS Method Notification URL
The URL that will receive the notification of the 3DS Method completion from the ACS. This is sent in the initial request (/3ds2/lookup) to the ACS from the 3DS Requestor executing the 3DS Method.

note

The default value is the 3DS Server URL. To receive a notification on a custom URL, send the custom URL as the field value.

OptionalNAString
doBinLookupOptional feature to retrieve key characteristics of the card used in the transaction. Unless set to true, the default is false.OptionalNAObject
clientStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
  • 1.0.2 (If set to 1.0.2, the 3DS Server attempts 3DS 1 fallback)
RequiredNAString
clientEndProtocolVersionThe most recent active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
  • 1.0.2 (Set to 1.0.2 only if the client does not support 3DS 2.1.0)
RequiredNAString

/3ds2/lookup Response: parameters description

Direct integration to 3DS Server: /3ds2/lookup - Sample response

Integration through the Web SDK in toolkit workflow: /3ds2/lookup - Sample response

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

In the /3ds2/authenticate request, use the threeDSServerTransID value you received in the /3ds2/lookup response.

Required36String
dsStartProtocolVersionDS Start Protocol Version.
The earliest (i.e., oldest) active protocol version that the DS supports.
Optional5-8String
dsEndProtocolVersionDS End Protocol Version.
The most recent active protocol version that the DS supports.
Optional5-8String
acsStartProtocolVersionACS Start Protocol Version
The earliest (i.e., oldest) active protocol version that the ACS supports.
Optional5-8String
acsEndProtocolVersionACS End Protocol Version
The most recent active protocol version that the ACS URL supports.
Optional5-8String
threeDSMethodURL3DS Method URL
The ACS URL that will be used by the 3DS Method

note

The threeDSMethodURL data element may be omitted if not supported by the ACS for this specific card range.

Optional256String
threeDSMethodData3DS Method Data
Data elements sent in the threeDSMethodData field.

note

The threeDSMethodData data element may be omitted if not supported by the ACS for this specific card range.

ConditionalNAString
acsInfoIndACS Information Indicator
The 3DS Server uses the data in this field to identify the features that the Account Range supports. It lists all applicable values for the card range.

note

The response returns the acsInfoInd field only for card schemes that support 3D Secure 2.2.0 for card ranges cache. At present, this field is returned only if the user is using a VISA card.


Valid value:
  • 01 = Authentication Available at ACS
  • 02 = Attempts Supported by ACS or DS
  • 03 = Decoupled Authentication Supported
  • 04 = Whitelisting Supported
Optional2Array of string
binInfoBin Lookup Information
Displays additional information related to the card used in the transaction.
OptionalNAObject
binIssuer bank identification number
Usually the initial four, six, or more digits that appear on a card. These numbers uniquely identify the institution issuing the card.
OptionalNAString
schemeCard scheme
Displays additional information related to the card used in the transaction.
Valid value:
  • American Express
  • UnionPay
  • Discover
  • JCB
  • MasterCard
  • Visa
  • Unknown
OptionalNAString
brandCard brand
To distinguish different brands of the same card scheme.
Valid value:
  • American Express
  • Diners Club
  • UnionPay
  • Discover
  • JCB
  • Maestro
  • MasterCard
  • MasterCard Credit
  • MasterCard Debit
  • Visa
  • Visa Debit
  • Visa Credit
  • Visa Electron
  • Unknown
OptionalNAString
fundingSourceCard funding source
Valid value:
  • charge
  • credit
  • debit
  • deferredDebit
  • prepaid
  • unknown
OptionalNAString
issuingBankIssuing bank of the card.OptionalNAString
issuingCountryIssuing country codeLink opens new window as an ISO 3166-1 three-character alpha code.OptionalNAString
issuingCurrencyIssuing country currencyLink opens new window as an ISO 4217 three-character alpha code. The cardholder is billed in this currency.OptionalNAString
isDebitIf the card is a debit card.
Valid value:
  • true
  • false
  • unknown
OptionalNAString
isCorporateIndicates the customer type of the card.
Valid value:
  • true
  • false
  • unknown
OptionalNAString
isDccAllowedIf DCC (dynamic currency conversion) is allowed for the card.

note

This parameter will only be true if the card belongs to a Visa or a MasterCard scheme.


Valid value:
  • true
  • false
  • unknown
OptionalNAString
serverStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the 3DS Server supports.
Valid value:
  • 1.0.2
OptionalNAString
serverEndProtocolVersionThe most recent active 3DS protocol version that the 3DS Server supports.
Valid value:
  • 2.1.0
OptionalNAString

/3ds2/authenticate Request: parameters description

Direct integration to the 3DS Server: /3ds2/authenticate - Sample request

Integration through the Web SDK in the toolkit workflow: /3ds2/authenticate - Sample request

Integration through the Web SDK in the all-in-one workflow: /3ds2/authenticate - Sample request

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
  • 1.0.2
The default value is 2.1.0. To force the 3DS Server to use the 3DS 1 authentication protocol, set it to 1.0.2.
Optional5 - 8String
aReqAuthentication Request Message ObjectRequiredNAObject
threeDSCompInd3DS Method Completion Indicator
Indicates whether the 3DS Method completed successfully

note

The 3DS Server auto-populates this field value based on whether the 3DS Method step (browser and device information collection) was successful or not. If the merchant did not perform the 3DS Method step, the 3DS Server will set the field to N. If the ACS does not support the 3DS Method i.e., the /lookup response does not have the threeDSMethodURL field, the 3DS Server sets this field to U. For details on how to perform the 3DS Method, see Step 3 (scenario 3) in theDirect integration to the 3DS Server topic.


Valid value:
  • Y = Successfully completed
  • N = Did not successfully complete
  • U = Unavailable. 3DS Method URL was not present in the /lookup response for the card range associated with the Cardholder Account Number.
Optional1String
addrMatchAddress Match Indicator
Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
Valid value:
  • Y = Shipping Address matches Billing Address
  • N = Shipping Address does not match Billing Address
Optional1String
cardExpiryDateCard/Token Expiry Date
Expiry Date of the account number (PAN) or token supplied to the 3DS Requestor by the Cardholder.

note

The requirements for the presence of this field are DS specific.


Format:YYMM
Conditional4String
acctNumberCardholder Account Number (PAN or token) Format represented as per ISO 7812.

note

Enter the acctNumber as digits without any space or special character between the digits.

Required13 - 19String
billAddrLine1Cardholder Billing Address Line 1
First line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 01, required unless market or regional mandate restricts sending this information. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrLine2Cardholder Billing Address Line 2
Second line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrLine3Cardholder Billing Address Line 3
Third line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrPostCodeCardholder Billing Address Postal Code
ZIP or other postal code of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 01, required unless market or regional mandate restricts sending this information. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 16String
billAddrCityCardholder Billing Address City
The city of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 01, required unless market or regional mandate restricts sending this information. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrStateCardholder Billing Address State
The state or province of the Cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 01, required unless market or regional mandate restricts sending this information, or State is not applicable for this country. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country.


Valid value: Should be the country subdivision code defined in ISO 3166-2Link opens new window
ConditionalMax. 3String
billAddrCountryCardholder Billing Address Country
The country of the cardholder billing address associated with the card used for this purchase.

note

Required if Cardholder Billing Address State is present. For messageCategory = 01, required unless market or regional mandate restricts sending this information. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.


Valid value: ISO 3166-1 numeric three-digit country codeLink opens new window
Conditional3String
shipAddrLine1Cardholder Shipping Address Line 1
First line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrLine2Cardholder Shipping Address Line 2
Second line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrLine3Cardholder Shipping Address Line 3
Third line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrPostCodeCardholder Shipping Address Postal Code
The ZIP or other postal code of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 16String
shipAddrCityCardholder Shipping Address City
City portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrStateCardholder Shipping Address State
The state or province of the shipping address associated with the card being used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country.


Valid value: Should be the country subdivision code defined in ISO 3166-2Link opens new window
ConditionalMax. 3String
shipAddrCountryCardholder Shipping Address Country
Country of the shipping address requested by the cardholder.

note

Required if Cardholder Shipping Address State is present. Required (if available) unless market or regional mandate restricts sending this information.


Valid value: ISO 3166-1 three-digit numeric country codeLink opens new window
Conditional3String
emailCardholder Email Address
The email address associated with the account that is either entered by the cardholder or is on file with the 3DS Requestor.

note

Required unless market or regional mandate restricts sending this information.

ConditionalMax. 254String
cardholderNameName of the cardholder.

note

Required unless market or regional mandate restricts sending this information.

Conditional2 - 45String
homePhoneCardholder Home Phone Number
The home phone number provided by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
subscriberHome phone number of the subscriberConditionalMax. 15String
mobilePhoneCardholder Mobile Phone Number
The mobile phone number provided by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
subscriberMobile phone number of the subscriberConditionalMax. 15String
workPhoneCardholder Work Phone Number
The work phone number provided by the cardholder.

note

Required (if available), unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
subscriberMobile phone number of the subscriberConditionalMax. 15String
deviceChannelDevice Channel
Indicates the type of channel interface being used to initiate the transaction.
Valid value:02 = Browser-based (Direct integration to 3DS Server)/ WebSDK
Required2String
browserAcceptHeaderBrowser Accept Headers
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser.
If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
RequiredMax. 2048String
browserIPBrowser IP Address
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.

note

Include where regionally acceptable.

ConditionalMax. 45String
browserJavaEnabledBrowser Java Enabled
Boolean that represents the ability of the cardholder browser to execute Java.
Valid value:
  • true
  • false
ConditionalNABoolean
browserLanguageBrowser Language
Language set for the browser as defined in IETF BCP47.
Required1 - 8String
browserColorDepthBrowser Screen Color Depth
Value representing the bit depth of the color palette for displaying images, in bits per pixel.

note

Some OS/Browser combinations return a colorDepth value that is not accepted by the EMV 3D Secure 2.1 specifications. In such cases, we recommend that you send the closest value listed in the ‘Valid values’ column that is smaller than the colorDepth returned by the cardholder’s browser. For example, if the Chrome browser running on a Mac OS reports a colorDepth of 30 for some screens, send the browserColorDepth value as 24 because 30 is not a valid value according to the EMVco specification.


Valid 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
Conditional1 - 8String
browserScreenHeightBrowser Screen Height
Total height of the cardholder’s screen.
Conditional1 - 6String
browserScreenWidthBrowser Screen Width
Total width of the cardholder’s screen.
Conditional1 - 6String
browserTZBrowser Time Zone
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.
Valid value: Value is returned from the getTimezoneOffset() method.

Example time zone offset values in minutes:

  • If UTC -5 hours:
    • 300
    • +300
  • If UTC +5 hours:
    • -300
Conditional1 - 5String
browserUserAgentBrowser User-Agent
Exact content of the HTTP user-agent header.
Valid value: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
RequiredMax. 2048String
messageCategoryMessage Category
Identifies the authentication type used in the transaction.
Valid value:
  • 01 – Payment authentication
  • 02 – Non-payment authentication
Required2String
purchaseAmountPurchase Amount
Purchase amount in minor units of currency with all punctuation removed.
Example: If the purchase amount is USD 123.45, the element will contain the value as 12345.

note

Required for messageCategory = 01. Required for messageCategory = 02 if 3DS Requestor Authentication Indicator = 02 or 03.

RequiredMax. 48String
purchaseCurrencyPurchase Currency
Currency in which purchase amount is expressed.

note

Required for messageCategory = 01. Required for messageCategory = 02 if 3DS Requestor Authentication Indicator = 02 or 03.


Valid value: ISO 4217 three-digit currency codeLink opens new window
Required3String
purchaseExponentPurchase Currency Exponent
Minor units of currency as specified in the ISO 4217 currency exponent.
Example:
  • USD - 2
  • Yen - 0

note

Required for messageCategory = 01. Required for messageCategory = 02 if 3DS Requestor Authentication Indicator = 02 or 03.

Required1String
purchaseDatePurchase date and time expressed in UTC

note

Required for messageCategory = 01. Required for messageCategory = 02 if 3DS Requestor Authentication Indicator = 02 or 03.


Format: YYYYMMDDHHmmss
Required14String
transTypeTransaction Type
Identifies the type of transaction being authenticated.

note

This field is required in some markets. For example, for merchants in Brazil. Otherwise, optional.


Valid value:
  • 01 = Goods/ Service Purchase
  • 03 = Check Acceptance
  • 10 = Account Funding
  • 11 = Quasi-Cash Transaction
  • 28 = Prepaid Activation and Load
Conditional2String
threeDSRequestorAuthenticationInd3DS Requestor Authentication Indicator
Indicates the type of authentication request
This data element provides additional information to the ACS to determine the best approach for handling an authentication request.
Valid value:
  • 01 = Payment transaction
  • 02 = Recurring transaction
  • 03 = Installment transaction
  • 04 = Add card
  • 05 - Maintain card
  • 06 = Cardholder verification as part of EMV token ID&V
Required36String
threeDSRequestorAuthenticationInfo3DS Requestor Authentication Information
Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.
Optional but recommended to includeNAObject
threeDSReqAuthMethod3DS Requestor Authentication Method
Mechanism used by the cardholder to authenticate to the 3DS Requestor.
Valid value:
  • 01 = No 3DS Requestor authentication occurred. The cardholder “logged in” as a 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
NA2String
threeDSReqAuthTimestamp3DS Requestor Authentication Timestamp
Date and time in UTC of the cardholder authentication.
NA12String
threeDSReqAuthData3DS Requestor Authentication Data
Data that documents and supports a specific authentication process.
NAMax. 20,000String
threeDSRequestorChallengeInd3DS Requestor Challenge Indicator
Indicates whether a challenge is requested for this transaction.
Valid value:
  • 01 = No preference
  • 02 = No challenge requested
  • 03 = Challenge requested: 3DS Requestor Preference
  • 04 = Challenge requested: Mandate

Default value is 01.

Optional2String
threeDSRequestorPriorAuthenticationInfo3DS Requestor Prior Transaction Authentication Information
Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
Optional but recommended to includeNAObject
threeDSReqPriorRef3DS Requestor Prior Transaction Reference.
This data element provides additional information to the ACS to determine the best approach for handling a request.
Valid value: An ACS Transaction ID for a prior authenticated transaction.
Optional but recommended to include36String
threeDSReqPriorAuthMethod3DS Requestor Prior Transaction Authentication Method
Mechanism used by the cardholder to previously authenticate to the 3DS Requestor.
Valid value:
  • 01 = Frictionless authentication occurred by ACS
  • 02 = Cardholder challenge occurred by ACS
  • 03 = AVS verified
  • 04 = Other issuer methods
NA2String
threeDSReqPriorAuthTimestamp3DS Requestor Authentication Timestamp
Date and time in UTC of the prior cardholder authentication.
Format: YYYYMMDDHHmm
NA12String
threeDSReqPriorAuthData3DS Requestor Prior Transaction Authentication Data
Data that documents and supports a specific authentication process.
NAMax. 2048String
acctTypeAccount Type
Indicates the type of account. For example, for a multi-account card product.

note

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, Optional.


Valid value:
  • 01 - Not Applicable
  • 02 - Credit
  • 03 - Debit
Conditional2String
acctInfoCardholder Account Information
Additional information about the cardholder’s account provided by the 3DS Requestor.
Optional but recommended to includeNAObject
chAccAgeIndCardholder account age indicator.
Length of time that the cardholder has had the account with the 3DS Requestor.
Valid value:
  • 01 = No account (guest check-out)
  • 02 = Created during this transaction
  • 03 = Less than 30 days
  • 04 = 30 to 60 days
  • 05 = More than 60 days
NA2String
mccMerchant Category Code
DS-specific code describing the Merchant’s type of business, product, or service. The 3DS Server populates the value of this field when it passes the authentication request to the issuer via the DS.
Optional4String
merchantCountryCodeMerchant Country Code
Country Code of the Merchant. This value correlates to the Merchant Country Code as defined by each Payment System or DS. The 3DS Server populates the value of this field when it passes the authentication request to the issuer via the DS.
Format: ISO 3166-1 numeric three-digit country codeLink opens new window
Optional3String
merchantNameMerchant name
Merchant name assigned by the Acquirer or Payment System. The 3DS Server populates the value of this field when it passes the authentication request to the issuer via the DS.
OptionalMax 40String
chAccDateCardholder account opening date
Date that the cardholder opened the account with the 3DS Requestor.
Format: YYYYMMDD
NA8String
chAccChangeIndCardholder account change indicator
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.
Valid value:
  • 01 = Changed during this transaction
  • 02 = Less than 30 days
  • 03 = 30 to 60 days
  • 04 = More than 60 day
Optional2String
chAccChangeCardholder account change date
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.
Format: YYYYMMDD
NA8String
chAccPwChangeIndCardholder account password change indicator
Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
Valid value:
  • 01 = No change
  • 02 = Changed during this transaction
  • 03 = Less than 30 days
  • 04 = 30 to 60 days
  • 05 = More than 60 days
NA2String
chAccPwChangeCardholder account password change date
Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
Format: YYYYMMDD
NA8String
shipAddressUsageIndShipping address first usage indicator
Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
Valid value:
  • 01 - This transaction
  • 02 = Less than 30 days
  • 03 = 30 to 60 days
  • 04 = More than 60 day
NA2String
shipAddressUsageShipping address first usage date
Date when the shipping address used for this transaction was first used with the 3DS Requestor.
Format: YYYYMMDD
NA8String
txnActivityDayNumber of Transactions Day
Number of transactions for this cardholder in the last 24 hours.
NAMax. 3String
txnActivityYearNumber of Transactions Year
Number of transactions for this cardholder in the previous 12 months.
NAMax. 3String
provisionAttemptsDayNumber of Provisioning Attempts Day
Number of Add Card attempts in the last 24 hours.
NAMax. 3String
nbPurchaseAccountCardholder Account Purchase Count
Number of purchases with this cardholder account during the previous six months.
NAMax. 4String
suspiciousAccActivitySuspicious Account Activity Indicator
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
Valid value:
  • 01 = No suspicious activity has been observed
  • 02 = Suspicious activity has been observed
NA2String
shipNameIndicatorShipping Name Indicator
Indicates if the cardholder Name on the account is identical to the shipping Name used for this transaction.
Valid value:
  • 01 - Account Name identical to shipping Name
  • 02 = Account Name different than shipping Name
NA2String
paymentAccIndPayment Account Age Indicator
Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Valid value:
  • 01 = No account (guest check-out)
  • 02= During this transaction
  • 03 = Less than 30 days
  • 04 = 30 to 60 days
  • 05 = More than 60 day
NA2String
paymentAccAgePayment Account Age date
Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
NA8String
acctIDCardholder Account Identifier
Additional information about the account optionally provided by the 3DS Requestor.
Format: YYYYMMDD
OptionalMax. 64String
purchaseInstalDataInstallment Payment Data
Indicates the maximum number of authorizations permitted for installment payments.

note

Required if the Merchant and cardholder have agreed to installment payments, i.e., if 3DS Requestor Authentication Indicator = 03. Omitted, if not an instalment payment authentication.


Valid value: Value shall be greater than 1
ConditionalMax. 3String
merchantRiskIndicatorMerchant Risk Indicator
Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
Optional but recommended to includeNAObject
shipIndicatorShipping Indicator
Indicates shipping method chosen for the transaction.
Valid 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 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, media subscriptions, etc.)
NA2String
deliveryTimeframeDelivery Timeframe
Indicates the merchandise delivery timeframe.
Valid value:
  • 01 = Electronic Delivery
  • 02 = Same day shipping
  • 03 = Overnight shipping
  • 04 = Two-day or more shipping
NA2String
deliveryEmailAddressDelivery Email Address
For Electronic delivery, the email address to which the merchandise was delivered.
NAMax. 254String
reorderItemsIndReorder Items Indicator
Indicates whether the cardholder is reordering previously purchased merchandise.
Valid value:
  • 01 = First time ordered
  • 02 = Reordered
NA2String
preOrderPurchaseIndPre-Order Purchase Indicator
Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.
Valid value:
  • 01 = Merchandise available
  • 02 = Future availability
NA2String
preOrderDatePre-Order Date
For a pre-ordered purchase, the expected date that the merchandise will be available.
Format: YYYYMMDD
NA8String
giftCardAmountGift Card Amount in major units
For prepaid or gift card purchases, the purchase amount total of prepaid or gift card(s) in major units.
Example: USD123.45 is 123
NAMax. 15String
giftCardCurrGift Card Currency
For prepaid or gift card purchases, the currency codeLink opens new window of the card as defined in ISO 4217.
NA3String
giftCardCountGift Card Count
For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased.
NA2String
messageExtensionMessage Extension
Data necessary to support requirements not otherwise defined in the 3D Secure message are carried in a Message Extension.

note

Conditions to be set by each DS.
Merchants who operate in the travel industry can send additional travel-related data in the messageExtension object of the /authenticate request. For a sample of the messageExtension object and field details, see the message extension elements for the travel industry topic.

ConditionalMax. 81920Array
nameThe name of the extension data set as defined by the extension owner.RequiredMax. 64String
idA unique identifier for the messageExtensionRequiredMax. 64String
criticalityIndicatorA Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.
Valid value:
  • true
  • false
RequiredNABoolean
dataThe data carried in the extension.RequiredMax. 8059Object
recurringExpiryRecurring Expiry
Date after which no further authorizations shall be performed.

note

Required if 3DS Requestor Authentication Indicator = 02 or 03.


Format: YYYYMMDD
Conditional8String
recurringFrequencyRecurring Frequency
Indicates the minimum number of days between authorizations.

note

Required if 3DS Requestor Authentication Indicator = 02 or 03.

ConditionalMax. 4String
broadInfoBroadcast Information
Unstructured information sent between the 3DS Server, the DS, and the ACS.

note

Requirements for the presence of this field are DS specific.

Conditional4096Object
messageBroadcast message content.NANAString
challengeParametersChallenge parameters
Object that contains the details of any challenge parameter. These parameters can affect the display of the challenge window on the user’s browser.

note

This field is required only if you are integrating with the 3DS Server directly or through the Web SDK. If you do not specify a value in the request, the 3DS server will set the value of the challengeWindowSize to 05 (which means ‘Full screen’) in the challenge request it sends to the ACS (issuer).

OptionalNAObject
challengeWindowSizeDimensions of the challenge window that will be displayed to the cardholder in case of a challenge. 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.
Valid value:
  • 01 = 250 X 400
  • 02 = 390 X 400
  • 03 = 500 X 600
  • 04 = 600 X 400
  • 05 = Full screen
NA2String
clientStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
  • 1.0.2 (If set to 1.0.2, the 3DS Server attempts 3DS 1 fallback)
RequiredNAString
clientEndProtocolVersionThe most recent active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
  • 1.0.2 (Set to 1.0.2 only if the client does not support 3DS 2.1.0)
RequiredNAString
acquirerBINAcquirer BIN
Acquiring institution identification code as assigned by the DS receiving the AReq message. This value correlates to the Acquirer BIN as defined by each Payment System or DS.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 11String
acquirerMerchantIDAcquirer Merchant ID
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.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 35String
threeDSRequestorID3DS Requestor ID
DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 35String
threeDSRequestorName3DS Requestor Name
DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 40String
threeDSRequestorURL3DS Requestor URL
Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3D Secure system if a problem arises and should provide contact information.
Example: http://server.domainname.com

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.


Valid value: A fully qualified URL
RequiredMax 2048String
threeDSServerURL3DS Server URL
Fully qualified URL of the 3DS Server to which the DS will send the RReq message after the challenge has been completed.
Example: http://server.domainname.com

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.


Valid value: A fully qualified URL
RequiredMax 2048String
threeDSServerOperatorID3DS Server Operator ID
DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS Server on an individual basis. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.

note

Requirements for the presence of this field are DS specific.

ConditionalMax 32String
threeDSServerRefNumber3DS Server Reference Number
Unique identifier assigned by the EMVCo secretariat upon testing and approval. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
RequiredMax 32String
messageTypeMessage Type
Identifies the type of message that is passed. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
Valid value:AReq
Required4String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send. However, if you are manually entering this field value, use the threeDSServerTransID value you received in the /3ds2/lookup response.

Required36String
notificationURLNotification URL
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.

note

By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback capability and implement your own challenge response landing page, set the value of this field to a custom URL, where you can receive and monitor notifications. In such cases, you are responsible for handling notifications and continuing with the 3DS flow. In case the authentication response returns the transStatus = C, then to fetch the challenge result data from the ACS, send the /3ds2/validate request instead of the /3ds2/challenge_result request.

RequiredMax 256String

/3ds2/authenticate Response: parameters description

Direct integration to the 3DS Server: /3ds2/authenticate - Sample response

Integration through the Web SDK in the toolkit workflow: /3ds2/authenticate - Sample response

Integration through the Web SDK in the all-in-one workflow: /3ds2/authenticate - Sample response

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
aResAuthentication Response MessageRequiredNAObject
messageTypeMessage Type
Identifies the type of message that is passed.
Valid value:
  • ARes
  • Erro
Required4String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
  • 1.0.2
The default value is 2.1.0.
Required5 - 8String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

The field value must be the same field value you received in  the /3ds2/lookup response.

Required36String
dsTransIDDS Transaction ID
UUID assigned by the Directory Server to identify a single transaction.
Required36String
acsTransIDACS Transaction ID
Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction.
Required36String
acsReferenceNumberACS Reference Number
It is the unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.
RequiredMax. 32String
acsOperatorIDACS Operator ID
DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis.

note

Requirements for the presence of this field are DS specific.

ConditionalMax. 32String
dsReferenceNumberDS reference number
EMVCo-assigned unique identifier to track approved DS.
RequiredMax. 32String
transStatusTransaction Status
Indicates whether a transaction qualifies as an authenticated transaction or account verification.

note

  • transStatus = C is not valid if the authenticate request has 3DS Requestor Challenge Indicator = 06 (No challenge requested; Data share only)
  • For messageCategory = 02, conditional as defined by the DS.

Valid value:
  • 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 authentication request
  • 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 challenge request or challenge response
  • R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted
Required1String
transStatusReasonTransaction Status Reason

note

For messageCategory = 01, required if transStatus is N, U, or R. For messageCategory = 02, conditional as defined by the DS.


Valid value:
  • 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
Conditional2String
acsSignedContentACS Signed Content.
Contains the JWS object created by the ACS for the authentication response message.

note

Required if transStatus = C.

ConditionalNAObject
authenticationTypeAuthentication Type
Indicates the type of authentication method the Issuer will use to challenge the cardholder, whether in the authentication response message or what was used by the ACS when in the result request message.

note

Required in the authentication response message if the transStatus = C in the authentication response.


Valid value:
  • 01 = Static
  • 02 = Dynamic
  • 03 = OOB
Conditional2String
acsChallengeMandatedACS Challenge Mandated Indicator
Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables.

note

Required if transStatus = C.


Valid value:
  • Y = Challenge is mandated
  • N = Challenge is not mandated
Required2String
acsURLACS URL
Fully qualified URL of the ACS to be used for the challenge. For browser (deviceChannel = 2), 3DS Requestor will post the challenge request to this URL via the challenge window.

note

For browser, required if transStatus = C.

ConditionalMax. 2048String
eciElectronic Commerce Indicator (ECI)
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

note

The requirements for the presence of this field are DS specific.

Conditional2String
creqBase64 encoded challenge request messageRequiredNABase64
cardholderInfoCardholder Information Text
Text provided by the ACS/Issuer to Cardholder during a Frictionless (transStatus is U, N, or R) transaction. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”

note

If this field is populated, the merchant must convey the information in this field to the cardholder.

ConditionalMax. 128String
authenticationValueAuthentication Value
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.

note

For messageCategory = 01, required if transStatus = Y or A. For messageCategory = 02, conditional based on DS rules.


Valid value: A 20-byte value that has been base64 encoded, giving a 28-byte result.
Conditional28String

/3ds2/challenge_result Response: parameters description

Direct integration to 3DS Server: /3ds2/challenge_result - Sample response

Integration through the Web SDK in toolkit workflow: /3ds2/challenge_result - Sample response

Field NameDescriptionRequiredLengthData Type
messageTypeMessage Type
Identifies the type of message that is passed.
Valid value:
  • RReq
  • Erro
Required4String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
Required5 - 8String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

The field value must be the same field value you received in  the /3ds2/authenticate response.

Required36String
dsTransIDDS Transaction ID
UUID assigned by the Directory Server to identify a single transaction.
Required36String
acsTransIDACS Transaction ID
Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction.
Required36String
authenticationTypeIndicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the authentication response message or what was used by the ACS when in the result request message.

note

Required in the result request message if the transStatus = Y or N in the result request.


Valid value:
  • 01 - Static
  • 02 - Dynamic
  • 03 - OOB
Conditional2String
authenticationValueAuthentication Value
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.

note

Required if transStatus = Y or A. Omitted from the result request message when sent as an abandonment notification.


Valid value: A 20-byte value that has been base64 encoded, giving a 28-byte result.
Conditional28String
eciElectronic Commerce Indicator (ECI)
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

note

The requirements for the presence of this field are DS specific.

Example: For Visa, 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated.
Conditional2String
interactionCounterInteraction Counter
Indicates the number of authentication cycles attempted by the Cardholder.
Required2String
messageCategoryMessage Category
Identifies the category of the message for a specific use case.
Valid value:
  • 01 - Payment Authentication (PA)
  • 02 - Non Payment Authentication (NPA)
Required2String
transStatusTransaction Status
Indicates whether a transaction qualifies as an authenticated transaction or account verification.
Valid value:
  • Y - Authentication/ Account Verification Successful
  • N - Not Authenticated /Account Not Verified; Transaction denied
Required1String
challengeCancelChallenge Cancelation Indicator
Indicator informing the ACS and the DS that the authentication has been canceled.

note

Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons as indicated. If Transaction Status Reason = 14, the value must be either 04 or 05.


Valid value:
  • 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
Conditional2String

/3ds2/validate Request: parameters description

Direct integration to 3DS Server: /3ds2/validate - Sample request

Integration through the Web SDK in toolkit workflow: /3ds2/validate - Sample request

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
cresChallenge result
cres is the ACS response sent via an HTTP POST to the notificationURL specified in the authenticate request. It indicates the result of the authentication and is a base64-encoded message.
RequiredNABase64-encoded

/3ds2/validate Response: parameters description

Direct integration to 3DS Server: /3ds2/validate - Sample response

Integration through the Web SDK in toolkit workflow: /3ds2/validate - Sample response

Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

In the /3ds2/authenticate request, use the threeDSServerTransID value you received in the /3ds2/lookup response.

Required36String
validThe /validate method validates cres body sent in the request before retrieving the result data (rReq). If the cres validation fails, the field value is false and error details are returned in an error message.
Valid value:
  • true
  • false
RequiredNABoolean
rReqResult requestRequiredNAObject
messageTypeMessage Type
Identifies the type of message that is passed.
Valid value:rReq
Required4String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
Optional5 - 8String
dsTransIDDS Transaction ID
UUID assigned by the Directory Server to identify a single transaction.
Required36String
acsTransIDACS Transaction ID
Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction.
Required36String
authenticationTypeIndicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the authentication response message or what was used by the ACS when in the result request message.

note

Required in the result request message if the transStatus = Y or N in the result request.


Valid value:
  • 01 - Static
  • 02 - Dynamic
  • 03 - OOB
Conditional2String
authenticationValueAuthentication Value
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.

note

Required if transStatus = Y or A. Omitted from the result request message when sent as an abandonment notification.


Valid value: A 20-byte value that has been base64 encoded, giving a 28-byte result.
Conditional28String
eciElectronic Commerce Indicator (ECI)
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

note

The requirements for the presence of this field are DS specific.

Example: For Visa, 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated.
Conditional2String
interactionCounterInteraction Counter
Indicates the number of authentication cycles attempted by the Cardholder.
Required2String
messageCategoryMessage Category
Identifies the category of the message for a specific use case.
Valid value:
  • 01 - Payment Authentication (PA)
  • 02 - Non Payment Authentication (NPA)
Required2String
transStatusTransaction Status
Indicates whether a transaction qualifies as an authenticated transaction or account verification.
Valid value:
  • Y - Authentication/ Account Verification Successful
  • N - Not Authenticated /Account Not Verified; Transaction denied
Required1String
challengeCancelChallenge Cancelation Indicator
Indicator informing the ACS and the DS that the authentication has been canceled.

note

Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons as indicated. If Transaction Status Reason = 14, the value must be either 04 or 05.


Valid value:
  • 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
Conditional2String

Requests and responses for deviceChannel = 03 i.e., 3RI

The requests initiated directly by the merchant’s server are called Merchant initiated or 3RI. Such requests uses deviceChannel = 03.

3RI - /3ds2/lookup Request: parameters description

/3ds2/lookup - Sample request
Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
acctNumberAccount or card number of the cardholder.

note

Enter the acctNumber as digits without any space or special character between the digits.

Required13-19String
doBinLookupOptional feature to retrieve key characteristics of the card used in the transaction. Unless set to true, the default is false.OptionalNAObject
clientStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
RequiredNAString
clientEndProtocolVersionThe most recent active 3DS protocol version that the client supports.
Valid value:
  • 2.1.0
RequiredNAString

3RI - /3ds2/lookup Response: parameters description

/3ds2/lookup - Sample request
Field NameDescriptionRequiredLengthData Type
messageIdUnique message identifier assigned by the client.Optional1-50String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

In the /3ds2/authenticate request, use the threeDSServerTransID value you received in the /3ds2/lookup response.

Required36String
dsStartProtocolVersionDS Start Protocol Version.
The earliest (i.e., oldest) active protocol version that the DS supports.
Optional5-8String
dsEndProtocolVersionDS End Protocol Version.
The most recent active protocol version that the DS supports.
Optional5-8String
acsStartProtocolVersionACS Start Protocol Version
The earliest (i.e., oldest) active protocol version that the ACS supports.
Optional5-8String
acsEndProtocolVersionACS End Protocol Version
The most recent active protocol version that the ACS URL supports.
Optional5-8String
threeDSMethodURL3DS Method URL
The ACS URL that will be used by the 3DS Method

note

The threeDSMethodURL data element may be omitted if not supported by the ACS for this specific card range.
Ignore this field value if the subsequent /authenticate request is for a merchant-initiated i.e., a 3RI transaction.

Optional256String
threeDSMethodData3DS Method Data
Data elements sent in the threeDSMethodData field.

note

The threeDSMethodData data element may be omitted if not supported by the ACS for this specific card range.
Ignore this field value if the subsequent /authenticate request is for a merchant-initiated i.e., a 3RI transaction.

ConditionalNAString
acsInfoIndACS Information Indicator
The 3DS Server uses the data in this field to identify the features that the Account Range supports. It lists all applicable values for the card range.

note

The response returns the acsInfoInd field only for card schemes that support 3D Secure 2.2.0 for card ranges cache. At present, this field is returned only if the user is using a VISA card.


Valid value:
  • 01 = Authentication Available at ACS
  • 02 = Attempts Supported by ACS or DS
  • 03 = Decoupled Authentication Supported
  • 04 = Whitelisting Supported
Optional2Array of string
binInfoBin Lookup Information
Displays additional information related to the card used in the transaction.
OptionalNAObject
binIssuer bank identification number
Usually the initial four, six, or more digits that appear on a card. These numbers uniquely identify the institution issuing the card.
OptionalNAString
schemeCard scheme
Displays additional information related to the card used in the transaction.
Valid value:
  • American Express
  • UnionPay
  • Discover
  • JCB
  • MasterCard
  • Visa
  • Unknown
OptionalNAString
brandCard brand
To distinguish different brands of the same card scheme.
Valid value:
  • American Express
  • Diners Club
  • UnionPay
  • Discover
  • JCB
  • Maestro
  • MasterCard
  • MasterCard Credit
  • MasterCard Debit
  • Visa
  • Visa Debit
  • Visa Credit
  • Visa Electron
  • Unknown
OptionalNAString
fundingSourceCard funding source
Valid value:
  • charge
  • credit
  • debit
  • deferredDebit
  • prepaid
  • unknown
OptionalNAString
issuingBankIssuing bank of the card.OptionalNAString
issuingCountryIssuing country codeLink opens new window as an ISO 3166-1 three-character alpha code.OptionalNAString
issuingCurrencyIssuing country currencyLink opens new window as an ISO 4217 three-character alpha code. The cardholder is billed in this currency.OptionalNAString
isDebitIf the card is a debit card.
Valid value:
  • true
  • false
  • unknown
OptionalNAString
isCorporateIndicates the customer type of the card.
Valid value:
  • true
  • false
  • unknown
OptionalNAString
isDccAllowedIf DCC (dynamic currency conversion) is allowed for the card.

note

This parameter will only be true if the card belongs to a Visa or a MasterCard scheme.


Valid value:
  • true
  • false
  • unknown
OptionalNAString
serverStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the 3DS Server supports.
Valid value:
  • 1.0.2
OptionalNAString
serverEndProtocolVersionThe most recent active 3DS protocol version that the 3DS Server supports.
Valid value:
  • 2.1.0
OptionalNAString

3RI - /3ds2/authenticate Request: parameters description

/3ds2/authenticate - Sample request
Field NameDescriptionRequiredLengthData Type
deviceChannelDevice Channel
Identifies the inclusion of a data element in a message based on the Device Channel used for a specific transaction.
Valid value:03
Required2String
messageCategoryMessage Category
Identifies the authentication type used in the transaction.
Valid value:
  • 02 – Non-payment authentication
Required2String
threeRIInd3RI Indicator
Indicates the type of 3RI request. This field value provides additional information to the ACS to determine the best approach for handling a 3RI request.
Valid value:
  • 01 - Recurring transaction
  • 02 - Installment transaction
  • 03 - Add card
  • 04 - Maintain card information
  • 05 - Account verification
Required2String
acctNumberAccount or card number of the cardholder.

note

Enter the acctNumber as digits without any space or special character between the digits.

Required13-19String
acctTypeAccount Type
Indicates the type of account. For example, for a multi-account card product.

note

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, Optional.


Valid value:
  • 01 - Not Applicable
  • 02 - Credit
  • 03 - Debit
Conditional2String
acctInfoCardholder Account Information
Additional information about the cardholder’s account provided by the 3DS Requestor.
Optional but recommended to includeNAObject
chAccAgeIndCardholder account age indicator.
Length of time that the cardholder has had the account with the 3DS Requestor.
Valid value:
  • 01 - No account (guest check-out)
  • 02 - Created during this transaction
  • 03 - Less than 30 days
  • 04 - 30 to 60 days
  • 05 - More than 60 days
NA2String
chAccDateCardholder account opening date
Date that the cardholder opened the account with the 3DS Requestor.
Format: YYYYMMDD
NA8String
chAccChangeIndCardholder account change indicator
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.
Valid value:
  • 01 - Changed during this transaction
  • 02 - Less than 30 days
  • 03 - 30 to 60 days
  • 04 - More than 60 day
Optional2String
chAccChangeCardholder account change date
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.
Format: YYYYMMDD
NA8String
chAccPwChangeIndCardholder account password change indicator
Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
Valid value:
  • 01 - No change
  • 02 - Changed during this transaction
  • 03 - Less than 30 days
  • 04 - 30 to 60 days
  • 05 - More than 60 days
NA2String
chAccPwChangeCardholder account password change date
Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
Format: YYYYMMDD
NA8String
shipAddressUsageIndShipping address first usage indicator
Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
Valid value:
  • 01 - This transaction
  • 02 - Less than 30 days
  • 03 - 30 to 60 days
  • 04 - More than 60 day
NA2String
shipAddressUsageShipping address first usage date
Date when the shipping address used for this transaction was first used with the 3DS Requestor.
Format: YYYYMMDD
NA8String
txnActivityDayNumber of Transactions Day
Number of transactions for this cardholder in the last 24 hours.
NAMax. 3String
txnActivityYearNumber of Transactions Year
Number of transactions for this cardholder in the previous 12 months.
NAMax. 3String
provisionAttemptsDayNumber of Provisioning Attempts Day
Number of Add Card attempts in the last 24 hours.
NAMax. 3String
nbPurchaseAccountCardholder Account Purchase Count
Number of purchases with this cardholder account during the previous six months.
NAMax. 4String
suspiciousAccActivitySuspicious Account Activity Indicator
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
Valid value:
  • 01 - No suspicious activity has been observed
  • 02 - Suspicious activity has been observed
NA2String
shipNameIndicatorShipping Name Indicator
Indicates if the cardholder Name on the account is identical to the shipping Name used for this transaction.
Valid value:
  • 01 - Account Name identical to shipping Name
  • 02 - Account Name different than shipping Name
NA2String
paymentAccIndPayment Account Age Indicator
Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Valid value:
  • 01 - No account (guest check-out)
  • 02 - During this transaction
  • 03 - Less than 30 days
  • 04 - 30 to 60 days
  • 05 - More than 60 day
NA2String
paymentAccAgePayment Account Age date
Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Format: YYYYMMDD
NA8String
acctIDCardholder Account Identifier
Additional information about the account optionally provided by the 3DS Requestor.
OptionalMax. 64String
merchantRiskIndicatorMerchant Risk Indicator
Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
Optional but recommended to includeNAObject
shipIndicatorShipping Indicator
Indicates shipping method chosen for the transaction.
Valid 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 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, media subscriptions, etc.)
NA2String
deliveryTimeframeDelivery Timeframe
Indicates the merchandise delivery time frame.
Valid value:
  • 01 - Electronic Delivery
  • 02 - Same day shipping
  • 03 - Overnight shipping
  • 04 - Two-day or more shipping
NA2String
deliveryEmailAddressDelivery Email Address
For Electronic delivery, the email address to which the merchandise was delivered.
NAMax. 254String
reorderItemsIndReorder Items Indicator
Indicates whether the cardholder is reordering previously purchased merchandise.
Valid value:
  • 01 - First time ordered
  • 02 - Reordered
NA2String
preOrderPurchaseIndPre-Order Purchase Indicator
Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.
Valid value:
  • 01 - Merchandise available
  • 02 - Future availability
NA2String
preOrderDatePre-Order Date
For a pre-ordered purchase, the expected date that the merchandise will be available.
Format: YYYYMMDD
NA8String
giftCardAmountGift Card Amount in major units
For prepaid or gift card purchases, the purchase amount total of prepaid or gift card(s) in major units.
Example: USD123.45 is 123
NAMax. 15String
giftCardCurrGift Card Currency
For prepaid or gift card purchases, the currency codeLink opens new window of the card as defined in ISO 4217.
NA3String
giftCardCountGift Card Count
For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased.
NA2String
cardExpiryDateCard/Token Expiry Date
Expiry Date of the account number (PAN) or token supplied to the 3DS Requestor by the Cardholder.

note

The requirements for the presence of this field are DS specific.


Format:YYMM
Conditional4String
cardholderNameName of the cardholder.

note

Required unless market or regional mandate restricts sending this information.

Conditional2 - 45String
emailCardholder Email Address
The email address associated with the account that is either entered by the cardholder or is on file with the 3DS Requestor.

note

Required unless market or regional mandate restricts sending this information.

ConditionalMax. 254String
billAddrLine1Cardholder Billing Address Line 1
First line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrLine2Cardholder Billing Address Line 2
Second line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrLine3Cardholder Billing Address Line 3
Third line of the street address or equivalent local portion of the cardholder billing address associated with the card used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrCityCardholder Billing Address City
The city of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
billAddrPostCodeCardholder Billing Address Postal Code
ZIP or other postal code of the cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 16String
billAddrStateCardholder Billing Address State
The state or province of the Cardholder billing address associated with the card used for this purchase.

note

For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country.


Valid value: Should be the country subdivision codeLink opens new window defined in ISO 3166-2
ConditionalMax. 3String
billAddrCountryCardholder Billing Address Country
The country of the cardholder billing address associated with the card used for this purchase.

note

Required if Cardholder Billing Address State is present. For messageCategory = 02, required (if available) unless market or regional mandate restricts sending this information.


Valid value: ISO 3166-1 numeric three-digit country codeLink opens new window
Conditional3String
shipAddrLine1Cardholder Shipping Address Line 1
First line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrLine2Cardholder Shipping Address Line 2
Second line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrLine3Cardholder Shipping Address Line 3
Third line of the street address or equivalent local portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrCityCardholder Shipping Address City
City portion of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 50String
shipAddrPostCodeCardholder Shipping Address Postal Code
The ZIP or other postal code of the shipping address requested by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalMax. 16String
shipAddrStateCardholder Shipping Address State
The state or province of the shipping address associated with the card being used for this purchase.

note

Required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country.


Valid value: Should be the country subdivision codeLink opens new window defined in ISO 3166-2
ConditionalMax. 3String
shipAddrCountryCardholder Shipping Address Country
Country of the shipping address requested by the cardholder.

note

Required if Cardholder Shipping Address State is present. Required (if available) unless market or regional mandate restricts sending this information.


Valid value: ISO 3166-1 three-digit numeric country codeLink opens new window
Conditional3String
homePhoneCardholder Home Phone Number
The home phone number provided by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
subscriberHome phone number of the subscriberConditionalMax. 15String
mobilePhoneCardholder Mobile Phone Number
The mobile phone number provided by the cardholder.

note

Required (if available) unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
subscriberMobile phone number of the subscriberConditionalMax. 15String
workPhoneCardholder Work Phone Number
The work phone number provided by the cardholder.

note

Required (if available), unless market or regional mandate restricts sending this information.

ConditionalNAObject
ccCountry code of the phoneConditional1 - 3String
clientStartProtocolVersionThe earliest (i.e., oldest) active 3DS protocol version that the client supports.

note

The 3DS Server will return an error message if you set the value to 1.0.2 to enable 3DS 1 fallback. It is not a supported scenario for 3RI transactions.


Valid value:
  • 2.1.0
RequiredNAString
clientEndProtocolVersionThe most recent active 3DS protocol version that the client supports.

note

The 3DS Server will return an error message if you set the value to 1.0.2 to enable 3DS 1 fallback. It is not a supported scenario for 3RI transactions.


Valid value:
  • 2.1.0
RequiredNAString
threeDSRequestorURL3DS Requestor URL
Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3D Secure system if a problem arises and should provide contact information.
Example: http://server.domainname.com

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.


Valid value: A fully qualified URL
RequiredMax 2048String
threeDSServerURL3DS Server URL
Fully qualified URL of the 3DS Server to which the DS will send the RReq message after the challenge has been completed.
Example: http://server.domainname.com

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.


Valid value: A fully qualified URL
RequiredMax 2048String
threeDSServerOperatorID3DS Server Operator ID
DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS Server on an individual basis. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.

note

Requirements for the presence of this field are DS specific.

ConditionalMax 32String
threeDSServerRefNumber3DS Server Reference Number
Unique identifier assigned by the EMVCo secretariat upon testing and approval. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
RequiredMax 32String
threeDSRequestorID3DS Requestor ID
DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 35String
threeDSRequestorName3DS Requestor Name
DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 40String
acquirerBINAcquirer BIN
Acquiring institution identification code as assigned by the DS receiving the AReq message. This value correlates to the Acquirer BIN as defined by each Payment System or DS.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 11String
acquirerMerchantIDAcquirer Merchant ID
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.

note

For merchants who process payment with Elavon, the 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
For a service provider merchant (a merchant who does not process with Elavon), you must include this field. The 3DS Server returns an error if this field is missing in the request.

OptionalMax 35String
messageTypeMessage Type
Identifies the type of message that is passed. The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send.
Valid value:AReq
Required4String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

The 3DS Server auto-populates and appends this field value in the authentication request it sends to the ACS (issuer) in addition to the data you send. However, if you are manually entering this field value, use the threeDSServerTransID value you received in the /3ds2/lookup response.

Required36String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
Optional5 - 8String

3RI - /3ds2/authenticate Response: parameters description

/3ds2/authenticate - Sample response
Field NameDescriptionRequiredLengthData Type
messageTypeMessage Type
Identifies the type of message that is passed.
Valid value:
  • ARes
  • Erro
Required4String
messageVersionMessage Version Number
The protocol version that will be used by all components to process the 3D Secure transaction. Set by the 3DS Server which originates the protocol with the authentication request message if not specified by the requestor.

note

Message version is always consistent across all 3D Secure protocol messages for a specific transaction


Valid value:
  • 2.1.0
Required5 - 8String
threeDSServerTransID3DS Server Transaction ID
Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

note

The field value must be the same field value you received in  the /3ds2/lookup response.

Required36String
dsTransIDDS Transaction ID
UUID assigned by the Directory Server to identify a single transaction.
Required36String
acsTransIDACS Transaction ID
Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction.
Required36String
acsReferenceNumberACS Reference Number
It is the unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.
RequiredMax. 32String
acsOperatorIDACS Operator ID
DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis.

note

Requirements for the presence of this field are DS specific.

ConditionalMax. 32String
dsReferenceNumberDS reference number
EMVCo-assigned unique identifier to track approved DS.
RequiredMax. 32String
transStatusTransaction Status
Indicates whether a transaction qualifies as an authenticated transaction or account verification.

note

  • For messageCategory = 02, conditional as defined by the DS.

Valid value:
  • 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 authentication request
  • A - Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided
  • R - Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted
Required1String
transStatusReasonTransaction Status Reason

note

For messageCategory = 02, conditional as defined by the DS.


Valid value:
  • 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
Conditional2String
authenticationValueAuthentication Value
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.

note

For messageCategory = 02, conditional based on DS rules.


Valid value: A 20-byte value that has been base64 encoded, giving a 28-byte result.
Conditional28String
eciElectronic Commerce Indicator (ECI)
Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

note

The requirements for the presence of this field are DS specific.

Conditional2String
cardholderInfoCardholder Information Text
Text provided by the ACS/Issuer to Cardholder during a Frictionless (transStatus is U, N, or R) 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.”

note

  • If this field is populated, the merchant must convey the information in this field to the cardholder.
  • ConditionalMax. 128String

    Related topics