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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
acctNumber | Account or card number of the cardholder. info_outline note Enter the | Required | 13-19 | String |
threeDSMethodNotificationURL | 3DS 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. info_outline 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. | Optional | NA | String |
doBinLookup | Optional feature to retrieve key characteristics of the card used in the transaction. Unless set to true , the default is false . | Optional | NA | Object |
clientStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
clientEndProtocolVersion | The most recent active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
/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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note In the | Required | 36 | String |
dsStartProtocolVersion | DS Start Protocol Version. The earliest (i.e., oldest) active protocol version that the DS supports. | Optional | 5-8 | String |
dsEndProtocolVersion | DS End Protocol Version. The most recent active protocol version that the DS supports. | Optional | 5-8 | String |
acsStartProtocolVersion | ACS Start Protocol Version The earliest (i.e., oldest) active protocol version that the ACS supports. info_outline note If the ACS Start Protocol Version is not available, this value is the DS Start Protocol Version for that card range. | Optional | 5-8 | String |
acsEndProtocolVersion | ACS End Protocol Version The most recent active protocol version that the ACS URL supports. info_outline note If the ACS End Protocol Version is not available, this value is the DS End Protocol Version for that card range. | Optional | 5-8 | String |
threeDSMethodURL | 3DS Method URL The ACS URL that will be used by the 3DS Method info_outline note The | Optional | 256 | String |
threeDSMethodData | 3DS Method Data Data elements sent in the threeDSMethodData field. info_outline note The | Conditional | NA | String |
acsInfoInd | ACS 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. info_outline note The response returns the
| Optional | 2 | Array of string |
binInfo | Bin Lookup Information Displays additional information related to the card used in the transaction. | Optional | NA | Object |
bin | Issuer 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. | Optional | NA | String |
scheme | Card scheme Displays additional information related to the card used in the transaction.Valid values:
| Optional | NA | String |
brand | Card brand To distinguish different brands of the same card scheme.Valid values:
| Optional | NA | String |
fundingSource | Card funding sourceValid values:
| Optional | NA | String |
issuingBank | Issuing bank of the card. | Optional | NA | String |
issuingCountry | Issuing open_in_newcountry codeLink opens new window as an ISO 3166-1 three-character alpha code. | Optional | NA | String |
issuingCurrency | Issuing country currency as an ISO 4217 three-character alpha code. The cardholder is billed in this currency. | Optional | NA | String |
isDebit | If the card is a debit card.Valid values:
| Optional | NA | String |
isCorporate | Indicates the customer type of the card.Valid values:
| Optional | NA | String |
isDccAllowed | If DCC (dynamic currency conversion) is allowed for the card. info_outline note This parameter will only be true if the card belongs to a Visa or a Mastercard scheme.
| Optional | NA | String |
serverStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the 3DS Server supports.Valid value:
| Optional | NA | String |
serverEndProtocolVersion | The most recent active 3DS protocol version that the 3DS Server supports.Valid values:
| Optional | NA | String |
/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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . To use the 3DS 2.2 features, set it to 2.2.0 . | Optional | 5 - 8 | String |
aReq | Authentication Request Message Object | Required | NA | Object |
threeDSCompInd | 3DS Method Completion Indicator Indicates whether the 3DS Method completed successfully info_outline 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
| Optional | 1 | String |
addrMatch | Address Match Indicator Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.Valid values:
| Optional | 1 | String |
cardExpiryDate | Card/Token Expiry Date Expiry Date of the account number (PAN) or token supplied to the 3DS Requestor by the Cardholder. info_outline note The requirements for the presence of this field are DS specific. YYMM | Conditional | 4 | String |
acctNumber | Cardholder Account Number (PAN or token) Format represented as per ISO 7812. info_outline note Enter the | Required | 13 - 19 | String |
billAddrLine1 | Cardholder 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. info_outline note For | Conditional | Max. 50 | String |
billAddrLine2 | Cardholder 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. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
billAddrLine3 | Cardholder 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. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
billAddrPostCode | Cardholder Billing Address Postal Code ZIP or other postal code of the cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 16 | String |
billAddrCity | Cardholder Billing Address City The city of the cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 50 | String |
billAddrState | Cardholder Billing Address State The state or province of the Cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 3 | String |
billAddrCountry | Cardholder Billing Address Country The country of the cardholder billing address associated with the card used for this purchase. info_outline note Required if Cardholder Billing Address State is present. For | Conditional | 3 | String |
shipAddrLine1 | Cardholder Shipping Address Line 1 First line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrLine2 | Cardholder Shipping Address Line 2 Second line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrLine3 | Cardholder Shipping Address Line 3 Third line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrPostCode | Cardholder Shipping Address Postal Code The ZIP or other postal code of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 16 | String |
shipAddrCity | Cardholder Shipping Address City City portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrState | Cardholder Shipping Address State The state or province of the shipping address associated with the card being used for this purchase. info_outline note Required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country. | Conditional | Max. 3 | String |
shipAddrCountry | Cardholder Shipping Address Country Country of the shipping address requested by the cardholder. info_outline note Required if Cardholder Shipping Address State is present. Required (if available) unless market or regional mandate restricts sending this information. | Conditional | 3 | String |
email | Cardholder Email Address The email address associated with the account that is either entered by the cardholder or is on file with the 3DS Requestor. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 254 | String |
cardholderName | Name of the cardholder. info_outline note Required unless market or regional mandate restricts sending this information. | Conditional | 2 - 45 | String |
homePhone | Cardholder Home Phone Number The home phone number provided by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
subscriber | Home phone number of the subscriber | Conditional | Max. 15 | String |
mobilePhone | Cardholder Mobile Phone Number The mobile phone number provided by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
subscriber | Mobile phone number of the subscriber | Conditional | Max. 15 | String |
workPhone | Cardholder Work Phone Number The work phone number provided by the cardholder. info_outline note Required (if available), unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
subscriber | Mobile phone number of the subscriber | Conditional | Max. 15 | String |
deviceChannel | Device Channel Indicates the type of channel interface being used to initiate the transaction.Valid value:
| Required | 2 | String |
browserAcceptHeader | Browser 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. | Required | Max. 2048 | String |
browserIP | Browser IP Address IP address of the browser as returned by the HTTP headers to the 3DS Requestor. info_outline note Include where regionally acceptable. | Conditional | Max. 45 | String |
browserJavaEnabled | Browser Java Enabled Boolean that represents the ability of the cardholder browser to execute Java. info_outline note Required when
| Conditional | NA | Boolean |
browserJavascriptEnabled | Browser JavaScript Enabled Boolean that represents the ability of the cardholder browser to execute JavaScript.Valid values:
| Required | NA | Boolean |
browserLanguage | Browser Language Language set for the browser as defined in IETF BCP47. | Required | 1 - 8 | String |
browserColorDepth | Browser Screen Color Depth Value representing the bit depth of the color palette for displaying images, in bits per pixel. info_outline note
| Conditional | 1 - 8 | String |
browserScreenHeight | Browser Screen Height Total height of the cardholder’s screen. info_outline note Required when | Conditional | 1 - 6 | String |
browserScreenWidth | Browser Screen Width Total width of the cardholder’s screen. info_outline note Required when | Conditional | 1 - 6 | String |
browserTZ | Browser 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. info_outline note Required when getTimezoneOffset() method.Example time zone offset values in minutes:
| Conditional | 1 - 5 | String |
browserUserAgent | Browser 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. | Required | Max. 2048 | String |
messageCategory | Message Category Identifies the authentication type used in the transaction.Valid values:
| Required | 2 | String |
purchaseAmount | Purchase 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. info_outline note Required for | Required | Max. 48 | String |
purchaseCurrency | Purchase Currency Currency in which purchase amount is expressed. info_outline note Required for | Required | 3 | String |
purchaseExponent | Purchase Currency Exponent Minor units of currency as specified in the ISO 4217 currency exponent. Example:
info_outline note Required for | Required | 1 | String |
purchaseDate | Purchase date and time expressed in UTC info_outline note Required for | Required | 14 | String |
transType | Transaction Type Identifies the type of transaction being authenticated. info_outline note This field is required in some markets. For example, for merchants in Brazil. Otherwise, optional.
| Conditional | 2 | String |
purchaseInstalData | Instalment Payment Data Indicates the maximum number of authorisations permitted for instalment payments.Valid values: Value shall be greater than 1. For example, 2 , 02 , 002 . info_outline note Required if the Merchant and the Cardholder have agreed to instalment payments, i.e. if | Conditional | Max. 3 | String |
threeDSRequestorAuthenticationInd | 3DS 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 values:
| Required | 36 | String |
threeDSRequestorAuthenticationInfo | 3DS Requestor Authentication Information Information about how the 3DS Requestor authenticated the cardholder before or during the transaction. | Optional but recommended to include | NA | Object |
threeDSReqAuthMethod | 3DS Requestor Authentication Method Mechanism used by the cardholder to authenticate to the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
threeDSReqAuthTimestamp | 3DS Requestor Authentication Timestamp Date and time in UTC of the cardholder authentication. | Optional but recommended to include | 12 | String |
threeDSReqAuthData | 3DS Requestor Authentication Data Data that documents and supports a specific authentication process. For each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. For example, if the 3DS Requestor Authentication Method ( threeDSReqAuthMethod ) is:
| Optional but recommended to include | Max. 20,000 | String |
threeDSRequestorChallengeInd | 3DS Requestor Challenge Indicator Indicates whether a challenge is requested for this transaction. info_outline note The response returns the
Default value is | Optional | 2 | String |
threeDSRequestorPriorAuthenticationInfo | 3DS 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 include | NA | Object |
threeDSReqPriorRef | 3DS 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 include | 36 | String |
threeDSReqPriorAuthMethod | 3DS Requestor Prior Transaction Authentication Method Mechanism used by the cardholder to previously authenticate to the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
threeDSReqPriorAuthTimestamp | 3DS Requestor Authentication Timestamp Date and time in UTC of the prior cardholder authentication.Format: YYYYMMDDHHmm | Optional but recommended to include | 12 | String |
threeDSReqPriorAuthData | 3DS Requestor Prior Transaction Authentication Data Data that documents and supports a specific authentication process. | Optional but recommended to include | Max. 2048 | String |
acctType | Account Type Indicates the type of account. For example, for a multi-account card product. info_outline 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.
| Conditional | 2 | String |
acctInfo | Cardholder Account Information Additional information about the cardholder’s account provided by the 3DS Requestor. | Optional but recommended to include | NA | Object |
chAccAgeInd | Cardholder account age indicator. Length of time that the cardholder has had the account with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
chAccDate | Cardholder account opening date Date that the cardholder opened the account with the 3DS Requestor.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
chAccChangeInd | Cardholder 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 values:
| Optional but recommended to include | 2 | String |
chAccChange | Cardholder 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 | Optional but recommended to include | 8 | String |
chAccPwChangeInd | Cardholder 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 values:
| Optional but recommended to include | 2 | String |
chAccPwChange | Cardholder account password change date Date that cardholder’s account with the 3DS Requestor had a password change or account reset.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
shipAddressUsageInd | Shipping address first usage indicator Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
shipAddressUsage | Shipping address first usage date Date when the shipping address used for this transaction was first used with the 3DS Requestor.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
txnActivityDay | Number of Transactions Day Number of transactions for this cardholder in the last 24 hours. | Optional but recommended to include | Max. 3 | String |
txnActivityYear | Number of Transactions Year Number of transactions for this cardholder in the previous 12 months. | Optional but recommended to include | Max. 3 | String |
provisionAttemptsDay | Number of Provisioning Attempts Day Number of Add Card attempts in the last 24 hours. | Optional but recommended to include | Max. 3 | String |
nbPurchaseAccount | Cardholder Account Purchase Count Number of purchases with this cardholder account during the previous six months. | Optional but recommended to include | Max. 4 | String |
suspiciousAccActivity | Suspicious Account Activity Indicator Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.Valid values:
| Optional but recommended to include | 2 | String |
shipNameIndicator | Shipping Name Indicator Indicates if the cardholder Name on the account is identical to the shipping Name used for this transaction.Valid values:
| Optional but recommended to include | 2 | String |
paymentAccInd | Payment Account Age Indicator Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
paymentAccAge | Payment Account Age date Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. | Optional but recommended to include | 8 | String |
acctID | Cardholder Account Identifier Additional information about the account optionally provided by the 3DS Requestor.Format: YYYYMMDD | Optional | Max. 64 | String |
purchaseInstalData | Installment Payment Data Indicates the maximum number of authorizations permitted for installment payments. info_outline note Required if the Merchant and cardholder have agreed to installment payments, i.e., if | Conditional | Max. 3 | String |
merchantRiskIndicator | Merchant 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 include | NA | Object |
shipIndicator | Shipping Indicator Indicates shipping method chosen for the transaction.Valid values:
| Optional but recommended to include | 2 | String |
deliveryTimeframe | Delivery Timeframe Indicates the merchandise delivery timeframe.Valid values:
| Optional but recommended to include | 2 | String |
deliveryEmailAddress | Delivery Email Address For Electronic delivery, the email address to which the merchandise was delivered. | Optional but recommended to include | Max. 254 | String |
reorderItemsInd | Reorder Items Indicator Indicates whether the cardholder is reordering previously purchased merchandise.Valid values:
| Optional but recommended to include | 2 | String |
preOrderPurchaseInd | Pre=Order Purchase Indicator Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.Valid values:
| Optional but recommended to include | 2 | String |
preOrderDate | Pre-Order Date For a pre-ordered purchase, the expected date that the merchandise will be available.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
giftCardAmount | Gift 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 | Optional but recommended to include | Max. 15 | String |
giftCardCurr | Gift Card Currency For prepaid or gift card purchases, the open_in_newcurrency codeLink opens new window of the card as defined in ISO 4217. | Optional but recommended to include | 3 | String |
giftCardCount | Gift Card Count For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased. | Optional but recommended to include | 2 | String |
messageExtension | Message Extension Data necessary to support requirements not otherwise defined in the 3D Secure message are carried in a Message Extension. info_outline note Conditions to be set by each DS. Merchants who operate in the travel industry can send additional travel-related data in the | Conditional | Max. 81920 | Array |
name | The name of the extension data set as defined by the extension owner. | Required | Max. 64 | String |
id | A unique identifier for the messageExtension | Required | Max. 64 | String |
criticalityIndicator | A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.Valid values:
| Required | NA | Boolean |
data | The data carried in the extension. | Required | Max. 8059 | Object |
recurringExpiry | Recurring Expiry Date after which no further authorizations shall be performed. info_outline note Required if | Conditional | 8 | String |
recurringFrequency | Recurring Frequency Indicates the minimum number of days between authorizations. info_outline note Required if | Conditional | Max. 4 | String |
broadInfo | Broadcast Information Unstructured information sent between the 3DS Server, the DS, and the ACS. info_outline note Requirements for the presence of this field are DS specific. | Conditional | 4096 | Object |
message | Broadcast message content. | NA | NA | String |
challengeParameters | Challenge 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. info_outline 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 | Optional | NA | Object |
challengeWindowSize | Dimensions 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 values:
| Optional | 2 | String |
clientStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
clientEndProtocolVersion | The most recent active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
mcc | Merchant 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. | Optional | 4 | String |
merchantCountryCode | Merchant 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 open_in_newcountry codeLink opens new window | Optional | 3 | String |
merchantName | Merchant 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. | Optional | Max 40 | String |
threeDSRequestorDecMaxTime | 3DS Requestor Decoupled Max Time Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). The field value should include leading 0s for values that are smaller than 5-digits.Example: If the maximum time is 24 hours or 1440 minutes, enter the field value as 01440 .Valid value: Numeric values between 1 and 10080 info_outline note
| Conditional | 5 | String |
threeDSRequestorDecReqInd | 3DS Requestor Decoupled Request Indicator Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use. info_outline note
| Optional | 1 | String |
acquirerBIN | Acquirer 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. info_outline 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. | Optional | Max 11 | String |
acquirerMerchantID | Acquirer 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. info_outline 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. | Optional | Max 35 | String |
threeDSRequestorID | 3DS Requestor ID DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis. info_outline 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. | Optional | Max 35 | String |
threeDSRequestorName | 3DS Requestor Name DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis. info_outline 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. | Optional | Max 40 | String |
threeDSRequestorURL | 3DS 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 info_outline 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. | Required | Max 2048 | String |
threeDSServerURL | 3DS 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 info_outline 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. | Required | Max 2048 | String |
threeDSServerOperatorID | 3DS 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. info_outline note Requirements for the presence of this field are DS specific. | Conditional | Max 32 | String |
threeDSServerRefNumber | 3DS 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. | Required | Max 32 | String |
messageType | Message 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 | Required | 4 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline 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 | Required | 36 | String |
notificationURL | Notification 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. info_outline 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 | Required | Max 256 | String |
/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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
aRes | Authentication Response Message | Required | NA | Object |
messageType | Message Type Identifies the type of message that is passed.Valid values:
| Required | 4 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Required | 5 - 8 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note The field value must be the same field value you received in the | Required | 36 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
acsReferenceNumber | ACS Reference Number It is the unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. | Required | Max. 32 | String |
acsOperatorID | ACS Operator ID DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis. info_outline note Requirements for the presence of this field are DS specific. | Conditional | Max. 32 | String |
dsReferenceNumber | DS reference number EMVCo-assigned unique identifier to track approved DS. | Required | Max. 32 | String |
transStatus | Transaction Status Indicates whether a transaction qualifies as an authenticated transaction or account verification. info_outline note
| Required | 1 | String |
transStatusReason | Transaction Status Reason info_outline note For
| Conditional | 2 | String |
acsSignedContent | ACS Signed Content. Contains the JWS object created by the ACS for the authentication response message. info_outline note Required if | Conditional | NA | Object |
authenticationType | Authentication 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. info_outline note Required in the authentication response message if the
| Conditional | 2 | String |
acsChallengeMandated | ACS Challenge Mandated Indicator Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables. info_outline note Required if
| Required | 2 | String |
acsURL | ACS 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. info_outline note For browser, required if | Conditional | Max. 2048 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. | Conditional | 2 | String |
creq | Base64 encoded challenge request message | Required | NA | Base64 |
cardholderInfo | Cardholder Information Text Text provided by the ACS/Issuer to Cardholder during a Frictionless ( transStatus is U , N , or R ) or Decoupled (transStatus = D ) 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.” info_outline note
| Conditional | Max. 128 | String |
authenticationValue | Authentication 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. info_outline note For | Conditional | 28 | String |
acsDecConInd | ACS Decoupled Confirmation Indicator Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder. info_outline note
| Conditional | 1 | String |
/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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Required | 5 - 8 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note The field value must be the same field value you received in the | Required | 36 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
authenticationType | 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. info_outline note Required in the result request message if the
| Conditional | 2 | String |
authenticationValue | Authentication 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. info_outline note Required if | Conditional | 28 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated. | Conditional | 2 | String |
interactionCounter | Interaction Counter Indicates the number of authentication cycles (excluding Decoupled Authentication) attempted by the Cardholder. info_outline note Required unless ACS Decoupled Confirmation Indicator ( | Conditional | 2 | String |
messageCategory | Message Category Identifies the category of the message for a specific use case.Valid values:
| Required | 2 | String |
transStatus | Transaction Status Indicates whether a transaction qualifies as an authenticated transaction or account verification.Valid values:
| Required | 1 | String |
challengeCancel | Challenge Cancelation Indicator Indicator informing the ACS and the DS that the authentication has been canceled. info_outline note Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons as indicated. If
| Conditional | 2 | String |
/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 Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note In the | Required | 36 | String |
valid | The /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 values:
| Required | NA | Boolean |
rReq | Result request | Required | NA | Object |
messageType | Message Type Identifies the type of message that is passed.Valid value: rReq | Required | 4 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Optional | 5 - 8 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
authenticationType | 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. info_outline note Required in the result request message if the
| Conditional | 2 | String |
authenticationValue | Authentication 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. info_outline note Required if | Conditional | 28 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated. | Conditional | 2 | String |
interactionCounter | Interaction Counter Indicates the number of authentication cycles (excluding Decoupled Authentication) attempted by the Cardholder. info_outline note Required unless ACS Decoupled Confirmation Indicator ( | Conditional | 2 | String |
messageCategory | Message Category Identifies the category of the message for a specific use case.Valid values:
| Required | 2 | String |
transStatus | Transaction Status Indicates whether a transaction qualifies as an authenticated transaction or account verification.Valid values:
| Required | 1 | String |
challengeCancel | Challenge Cancelation Indicator Indicator informing the ACS and the DS that the authentication has been canceled. info_outline note Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons as indicated. If
| Conditional | 2 | String |
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
Field Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
acctNumber | Account or card number of the cardholder. info_outline note Enter the | Required | 13-19 | String |
doBinLookup | Optional feature to retrieve key characteristics of the card used in the transaction. Unless set to true , the default is false . | Optional | NA | Object |
clientStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
clientEndProtocolVersion | The most recent active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
3RI - /3ds2/lookup Response: parameters description
Field Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageId | Unique message identifier assigned by the client. | Optional | 1-50 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note In the | Required | 36 | String |
dsStartProtocolVersion | DS Start Protocol Version. The earliest (i.e., oldest) active protocol version that the DS supports. | Optional | 5-8 | String |
dsEndProtocolVersion | DS End Protocol Version. The most recent active protocol version that the DS supports. | Optional | 5-8 | String |
acsStartProtocolVersion | ACS Start Protocol Version The earliest (i.e., oldest) active protocol version that the ACS supports. info_outline note If the ACS Start Protocol Version is not available, this value is the DS Start Protocol Version for that card range. | Optional | 5-8 | String |
acsEndProtocolVersion | ACS End Protocol Version The most recent active protocol version that the ACS URL supports. info_outline note If the ACS End Protocol Version is not available, this value is the DS End Protocol Version for that card range. | Optional | 5-8 | String |
threeDSMethodURL | 3DS Method URL The ACS URL that will be used by the 3DS Method info_outline note The | Optional | 256 | String |
threeDSMethodData | 3DS Method Data Data elements sent in the threeDSMethodData field. info_outline note The | Conditional | NA | String |
acsInfoInd | ACS 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. info_outline note The response returns the
| Optional | 2 | Array of string |
binInfo | Bin Lookup Information Displays additional information related to the card used in the transaction. | Optional | NA | Object |
bin | Issuer 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. | Optional | NA | String |
scheme | Card scheme Displays additional information related to the card used in the transaction.Valid values:
| Optional | NA | String |
brand | Card brand To distinguish different brands of the same card scheme.Valid values:
| Optional | NA | String |
fundingSource | Card funding sourceValid values:
| Optional | NA | String |
issuingBank | Issuing bank of the card. | Optional | NA | String |
issuingCountry | Issuing open_in_newcountry codeLink opens new window as an ISO 3166-1 three-character alpha code. | Optional | NA | String |
issuingCurrency | Issuing country currency as an ISO 4217 three-character alpha code. The cardholder is billed in this currency. | Optional | NA | String |
isDebit | If the card is a debit card.Valid values:
| Optional | NA | String |
isCorporate | Indicates the customer type of the card.Valid values:
| Optional | NA | String |
isDccAllowed | If DCC (dynamic currency conversion) is allowed for the card. info_outline note This parameter will only be true if the card belongs to a Visa or a Mastercard scheme.
| Optional | NA | String |
serverStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the 3DS Server supports.Valid values:2.1.0 | Optional | NA | String |
serverEndProtocolVersion | The most recent active 3DS protocol version that the 3DS Server supports.Valid values:
| Optional | NA | String |
3RI - /3ds2/authenticate Request: parameters description
/3ds2/authenticate - Sample request
Field Name | Description | Required | Length | Data Type |
---|---|---|---|---|
deviceChannel | Device Channel Identifies the inclusion of a data element in a message based on the Device Channel used for a specific transaction.Valid value:
| Required | 2 | String |
messageCategory | Message Category Identifies the authentication type used in the transaction.Valid values:
info_outline note 3D Secure 2.1 supports only scenarios related to a non-payment transaction i.e. the | Required | 2 | String |
threeRIInd | 3RI 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 values:
| Required | 2 | String |
acctNumber | Account or card number of the cardholder. info_outline note Enter the | Required | 13-19 | String |
acctType | Account Type Indicates the type of account. For example, for a multi-account card product. info_outline 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.
| Conditional | 2 | String |
acctInfo | Cardholder Account Information Additional information about the cardholder’s account provided by the 3DS Requestor. | Optional but recommended to include | NA | Object |
purchaseAmount | Purchase 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. info_outline note
| Required | Max. 48 | String |
purchaseCurrency | Purchase Currency Currency in which purchase amount is expressed. info_outline note
| Required | 3 | String |
purchaseExponent | Purchase Currency Exponent Minor units of currency as specified in the ISO 4217 currency exponent. Example:
info_outline note
| Required | 1 | String |
purchaseDate | Purchase date and time expressed in UTC info_outline note
| Required | 14 | String |
recurringExpiry | Recurring Expiry Date after which no further authorizations shall be performed. info_outline note Required if | Conditional | 8 | String |
recurringFrequency | Recurring Frequency Indicates the minimum number of days between authorizations. info_outline note Required if | Conditional | Max. 4 | String |
purchaseInstalData | Instalment Payment Data Indicates the maximum number of authorisations permitted for instalment payments.Valid values: Value shall be greater than 1. For example, 2 , 02 , 002 . info_outline note Required if | Conditional | Max. 3 | String |
chAccAgeInd | Cardholder account age indicator. Length of time that the cardholder has had the account with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
chAccDate | Cardholder account opening date Date that the cardholder opened the account with the 3DS Requestor.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
chAccChangeInd | Cardholder 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 values:
| Optional but recommended to include | 2 | String |
chAccChange | Cardholder 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 | Optional but recommended to include | 8 | String |
chAccPwChangeInd | Cardholder 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 values:
| Optional but recommended to include | 2 | String |
chAccPwChange | Cardholder account password change date Date that cardholder’s account with the 3DS Requestor had a password change or account reset.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
shipAddressUsageInd | Shipping address first usage indicator Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
shipAddressUsage | Shipping address first usage date Date when the shipping address used for this transaction was first used with the 3DS Requestor.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
txnActivityDay | Number of Transactions Day Number of transactions for this cardholder in the last 24 hours. | Optional but recommended to include | Max. 3 | String |
txnActivityYear | Number of Transactions Year Number of transactions for this cardholder in the previous 12 months. | Optional but recommended to include | Max. 3 | String |
provisionAttemptsDay | Number of Provisioning Attempts Day Number of Add Card attempts in the last 24 hours. | Optional but recommended to include | Max. 3 | String |
nbPurchaseAccount | Cardholder Account Purchase Count Number of purchases with this cardholder account during the previous six months. | Optional but recommended to include | Max. 4 | String |
suspiciousAccActivity | Suspicious Account Activity Indicator Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.Valid values:
| Optional but recommended to include | 2 | String |
shipNameIndicator | Shipping Name Indicator Indicates if the cardholder Name on the account is identical to the shipping Name used for this transaction.Valid values:
| Optional but recommended to include | 2 | String |
paymentAccInd | Payment Account Age Indicator Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.Valid values:
| Optional but recommended to include | 2 | String |
paymentAccAge | Payment Account Age date Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
acctID | Cardholder Account Identifier Additional information about the account optionally provided by the 3DS Requestor. | Optional | Max. 64 | String |
merchantRiskIndicator | Merchant 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 include | NA | Object |
shipIndicator | Shipping Indicator Indicates shipping method chosen for the transaction.Valid values:
| Optional but recommended to include | 2 | String |
deliveryTimeframe | Delivery Timeframe Indicates the merchandise delivery time frame.Valid values:
| Optional but recommended to include | 2 | String |
deliveryEmailAddress | Delivery Email Address For Electronic delivery, the email address to which the merchandise was delivered. | Optional but recommended to include | Max. 254 | String |
reorderItemsInd | Reorder Items Indicator Indicates whether the cardholder is reordering previously purchased merchandise.Valid values:
| Optional but recommended to include | 2 | String |
preOrderPurchaseInd | Pre=Order Purchase Indicator Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.Valid values:
| Optional but recommended to include | 2 | String |
preOrderDate | Pre-Order Date For a pre-ordered purchase, the expected date that the merchandise will be available.Format: YYYYMMDD | Optional but recommended to include | 8 | String |
giftCardAmount | Gift 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 | NA | Max. 15 | String |
giftCardCurr | Gift Card Currency For prepaid or gift card purchases, the open_in_newcurrency codeLink opens new window of the card as defined in ISO 4217. | Optional but recommended to include | 3 | String |
giftCardCount | Gift Card Count For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased. | Optional but recommended to include | 2 | String |
cardExpiryDate | Card/Token Expiry Date Expiry Date of the account number (PAN) or token supplied to the 3DS Requestor by the Cardholder. info_outline note The requirements for the presence of this field are DS specific. YYMM | Conditional | 4 | String |
cardholderName | Name of the cardholder. info_outline note Required unless market or regional mandate restricts sending this information. | Conditional | 2 - 45 | String |
email | Cardholder Email Address The email address associated with the account that is either entered by the cardholder or is on file with the 3DS Requestor. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 254 | String |
billAddrLine1 | Cardholder 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. info_outline note For | Conditional | Max. 50 | String |
billAddrLine2 | Cardholder 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. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
billAddrLine3 | Cardholder 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. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
billAddrCity | Cardholder Billing Address City The city of the cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 50 | String |
billAddrPostCode | Cardholder Billing Address Postal Code ZIP or other postal code of the cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 16 | String |
billAddrState | Cardholder Billing Address State The state or province of the Cardholder billing address associated with the card used for this purchase. info_outline note For | Conditional | Max. 3 | String |
billAddrCountry | Cardholder Billing Address Country The country of the cardholder billing address associated with the card used for this purchase. info_outline note Required if Cardholder Billing Address State is present. For | Conditional | 3 | String |
shipAddrLine1 | Cardholder Shipping Address Line 1 First line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrLine2 | Cardholder Shipping Address Line 2 Second line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrLine3 | Cardholder Shipping Address Line 3 Third line of the street address or equivalent local portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrCity | Cardholder Shipping Address City City portion of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 50 | String |
shipAddrPostCode | Cardholder Shipping Address Postal Code The ZIP or other postal code of the shipping address requested by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | Max. 16 | String |
shipAddrState | Cardholder Shipping Address State The state or province of the shipping address associated with the card being used for this purchase. info_outline note Required (if available) unless market or regional mandate restricts sending this information, or State is not applicable for this country. | Conditional | Max. 3 | String |
shipAddrCountry | Cardholder Shipping Address Country Country of the shipping address requested by the cardholder. info_outline note Required if Cardholder Shipping Address State is present. Required (if available) unless market or regional mandate restricts sending this information. | Conditional | 3 | String |
homePhone | Cardholder Home Phone Number The home phone number provided by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
subscriber | Home phone number of the subscriber | Conditional | Max. 15 | String |
mobilePhone | Cardholder Mobile Phone Number The mobile phone number provided by the cardholder. info_outline note Required (if available) unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
subscriber | Mobile phone number of the subscriber | Conditional | Max. 15 | String |
workPhone | Cardholder Work Phone Number The work phone number provided by the cardholder. info_outline note Required (if available), unless market or regional mandate restricts sending this information. | Conditional | NA | Object |
cc | Country code of the phone | Conditional | 1 - 3 | String |
clientStartProtocolVersion | The earliest (i.e., oldest) active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
clientEndProtocolVersion | The most recent active 3DS protocol version that the client supports.Valid values:
| Required | NA | String |
threeDSRequestorDecMaxTime | 3DS Requestor Decoupled Max Time Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). The field value should include leading 0s for values that are smaller than 5-digits.Example: If the maximum time is 24 hours or 1440 minutes, enter the field value as 01440 .Valid value: Numeric values between 1 and 10080 info_outline note
| Conditional | 5 | String |
threeDSRequestorDecReqInd | 3DS Requestor Decoupled Request Indicator Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use. info_outline note
| Optional | 1 | String |
threeDSRequestorURL | 3DS 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 info_outline 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. | Required | Max 2048 | String |
threeDSServerURL | 3DS 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 info_outline 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. | Required | Max 2048 | String |
threeDSServerOperatorID | 3DS 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. info_outline note Requirements for the presence of this field are DS specific. | Conditional | Max 32 | String |
threeDSServerRefNumber | 3DS 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. | Required | Max 32 | String |
threeDSRequestorID | 3DS Requestor ID DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis. info_outline 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. | Optional | Max 35 | String |
threeDSRequestorName | 3DS Requestor Name DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis. info_outline 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. | Optional | Max 40 | String |
acquirerBIN | Acquirer 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. info_outline 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. | Optional | Max 11 | String |
acquirerMerchantID | Acquirer 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. info_outline 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. | Optional | Max 35 | String |
messageType | Message 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:
| Required | 4 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline 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 | Required | 36 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . To use the 3DS 2.2 features such as decoupled authentication, set it to 2.2.0 . | Optional | 5 - 8 | String |
3RI - /3ds2/authenticate Response: parameters description
/3ds2/authenticate - Sample response
Field Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageType | Message Type Identifies the type of message that is passed.Valid values:
| Required | 4 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Required | 5 - 8 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note The field value must be the same field value you received in the | Required | 36 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
acsReferenceNumber | ACS Reference Number It is the unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. | Required | Max. 32 | String |
acsOperatorID | ACS Operator ID DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis. info_outline note Requirements for the presence of this field are DS specific. | Conditional | Max. 32 | String |
dsReferenceNumber | DS reference number EMVCo-assigned unique identifier to track approved DS. | Required | Max. 32 | String |
transStatusReason | Transaction Status Reason info_outline note For
| Conditional | 2 | String |
authenticationValue | Authentication 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. info_outline note For | Conditional | 28 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. | Conditional | 2 | String |
acsDecConInd | ACS Decoupled Confirmation Indicator Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder. info_outline note
| Conditional | 1 | String |
authenticationType | Authentication 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. info_outline note Required in the authentication response message if the
| Conditional | 2 | String |
acsChallengeMandated | ACS Challenge Mandated Indicator Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables. info_outline note Required only if
| Required | 2 | String |
cardholderInfo | Cardholder Information Text Text provided by the ACS/Issuer to Cardholder during a Frictionless ( transStatus is U , N , or R ) or Decoupled (transStatus = D ) 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.” info_outline note
| Conditional | Max. 128 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Required | 5 - 8 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note The field value must be the same field value you received in the | Required | 36 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
authenticationType | 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. [/notice note] Required in the result request message if the transStatus = Y or N in the result request.[/notice]Valid values:
| Conditional | 2 | String |
authenticationValue | Authentication 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. info_outline note Required if | Conditional | 28 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated. | Conditional | 2 | String |
messageType | Message Type Identifies the type of message that is passed.Valid values:
| Required | 4 | String |
messageVersion | Message 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. info_outline note Message version is always consistent across all 3D Secure protocol messages for a specific transaction
2.1.0 . | Required | 5 - 8 | String |
threeDSServerTransID | 3DS Server Transaction ID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. info_outline note The field value must be the same field value you received in the | Required | 36 | String |
dsTransID | DS Transaction ID UUID assigned by the Directory Server to identify a single transaction. | Required | 36 | String |
acsTransID | ACS Transaction ID Universally Unique transaction identifier (UUID) assigned by the ACS to identify a single transaction. | Required | 36 | String |
authenticationType | 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. info_outline note Required in the result request message if the
| Conditional | 2 | String |
authenticationValue | Authentication 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. info_outline note Required if | Conditional | 28 | String |
eci | Electronic Commerce Indicator (ECI) Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. info_outline note The requirements for the presence of this field are DS specific. 05 means successful authentication, 06 means merchant attempted to authenticate the cardholder, and 07 means transaction was not authenticated. | Conditional | 2 | String |
interactionCounter | Interaction Counter Indicates the number of authentication cycles (excluding Decoupled Authentication) attempted by the Cardholder. info_outline note Required unless ACS Decoupled Confirmation Indicator ( | Conditional | 2 | String |
messageCategory | Message Category Identifies the category of the message for a specific use case.Valid values:
| Required | 2 | String |
transStatus | Transaction Status Indicates whether a transaction qualifies as an authenticated transaction or account verification.Valid values:
| Required | 1 | String |