Authentication service

After creating the transaction, it's necessary to call the authentication service to continue the flow. If the AUC status is returned, a challenge must be initiated. For the AUD status, the "decoupled" flow must be followed. Otherwise, further calls won't be required.

Call details#

  • Resource: /v2/authentication/{3DS Server Transaction ID}
  • HTTP Method: PUT
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
merchant_idMerchant code on 3DS Server. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on 3DS Server. The production and certification keys will be different.< 80 ANYES
Content-TypeFixed value application/json.= 15 ANYES
carat_merchant_idCarat merchant code must be sent only if the token field is sent in the request< 15 ANCOND.
carat_merchant_keyThe authentication key of the Carat merchant must be sent only if the token field is sent in the request< 80 ANCOND.

Example#

Below are some examples of the authentication service call using the cURL tool.

Frictionless Flow#

Request with card number: To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind":"Y",
"pay_token_ind":"false",
"notification_url":"https://www.requestor.com/notification",
"trans_type":"01",
"three_ds_requestor":{
"authentication_ind":"01",
"id":"id",
"name":"Loja de Testes",
"url":"https://www.requestor.com"
},
"acquirer":{
"bin":"2",
"merchant_id":"00000000"
},
"browser":{
"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip":"10.20.30.40",
"javascript_enabled":"true",
"java_enabled":"false",
"language":"pt-BR",
"color_depth":"24",
"screen_height":"864",
"screen_width":"1536",
"tz":"180",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder":{
"card_expiry_date":"2212",
"name":"Joaquim",
"acct":{
"type":"02",
"number":"1234123412341234"
}
},
"merchant":{
"mcc":"1234",
"country_code":"BRA",
"name":"Loja de Teste",
},
"message":{
"category":"01"
},
"purchase":{
"amount":"10000",
"currency":"986",
"exponent":"2",
"date":"date"
}
}
--verbose

Response:

{
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "Y"
},
"message_version": "2.2.0"
}

Request with token: To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind":"Y",
"pay_token_ind":"false",
"notification_url":"https://www.requestor.com/notification",
"trans_type":"01",
"three_ds_requestor":{
"authentication_ind":"01",
"id":"id",
"name":"Loja de Testes",
"url":"https://www.requestor.com"
},
"acquirer":{
"bin":"2",
"merchant_id":"00000000"
},
"browser":{
"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip":"10.20.30.40",
"javascript_enabled":"true",
"java_enabled":"false",
"language":"pt-BR",
"color_depth":"24",
"screen_height":"864",
"screen_width":"1536",
"tz":"180",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder":{
"card_expiry_date":"2212",
"name":"Joaquim",
"acct":{
"type":"02",
"token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"merchant":{
"mcc":"1234",
"country_code":"BRA",
"name":"Loja de Teste",
},
"message":{
"category":"01"
},
"purchase":{
"amount":"10000",
"currency":"986",
"exponent":"2",
"date":"date"
}
}
--verbose

Response:

{
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "Y"
},
"message_version": "2.2.0"
}

Challenge Flow#

Request: To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind":"Y",
"pay_token_ind":"false",
"notification_url":"https://www.requestor.com/notification",
"trans_type":"01",
"three_ds_requestor":{
"authentication_ind":"01",
"id":"id",
"name":"Loja de Testes",
"url":"https://www.requestor.com"
},
"acquirer":{
"bin":"2",
"merchant_id":"00000000"
},
"browser":{
"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip":"10.20.30.40",
"javascript_enabled":"true",
"java_enabled":"false",
"language":"pt-BR",
"color_depth":"24",
"screen_height":"864",
"screen_width":"1536",
"tz":"180",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder":{
"card_expiry_date":"2212",
"name":"Joaquim",
"acct":{
"type":"02",
"number":"1234123412341234"
}
},
"merchant":{
"mcc":"1234",
"country_code":"BRA",
"name":"Loja de Teste",
},
"message":{
"category":"01"
},
"purchase":{
"amount":"10004",
"currency":"986",
"exponent":"2",
"date":"date"
}
}
--verbose

Response:

{
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUC"
},
"acs": {
"challenge_mandated": "Y",
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321",
"url": "https://www.acs.com/challenge"
},
"device_channel": "02",
"authentication": {
"type": "01"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "C"
},
"message_version": "2.2.0"
}

Request parameters#

The table below describes the request parameters of the authentication service:

ParameterDescriptionFormatMandatory
device_channelIndicates the type of channel interface being used to initiate the transaction. Default value: 02corresponds to Browser (BRW). Learn more.= 2 NYES
three_ri_indIndicates the type of 3RI request.
  • 01 = Recurring transaction
  • 02 = Instalment transaction
  • 03 = Add card
  • 04 = Maintain card information
  • 05 = Account verification
  • 06 = Split/delayed shipment
  • 07 = Top-up
  • 08 = Mail Order
  • 09 = Telephone Order
  • 10 = Whitelist status check
  • 11 = Other payment
Mandatory for device_channel = 03.
= 2 NCOND.
three_ds_comp_indIndicates whether the 3DS Method successfully completed.
  • Y = Successfully completed
  • N = Did not successfully complete
  • U = Unavailable— there was no 3DS Method URL related to the card.
Mandatory for device_channel = 02.
= 1 ACOND.
pay_token_indA value of true indicates that the transaction was de-tokenised prior to being received by the ACS.< 5 ANNO
pay_token_sourceIndicates where the de-tokenisation occurs.
  • 01 - 3DS Server
  • 02 - DS
= 2 NNO
notification_urlFully qualified URL of the 3DS Requestor to receive the CRes message. Mandatory for device_channel = 02.< 256 ANCOND.
trans_typeIdentifies the type of transaction being authenticated.
  • 01 = Goods/ Service Purchase
  • 03 = Check Acceptance
  • 10 = Account Funding
  • 11 = Quasi-Cash Transaction
  • 28 = Prepaid Activation and Load
= 2 NYES
broad_infoUnstructured information sent between the 3DS Server, the DS and the ACS.ObjectNO
three_ds_requestor
authentication_indIndicates the type of Authentication request.
  • 01 = Payment transaction
  • 02 = Recurring transaction
  • 03 = Instalment transaction
  • 04 = Add card
  • 05 = Maintain card
  • 06 = Cardholder verification as part of EMV token ID&V
= 2 NYES
challenge_indThis field signals the merchant's preference for the completion (or not) of the challenge, but unless the parties are aligned, the issuer may not comply with this request. If this field is not sent, it will be interpreted as "01 = No preference."
  • 01 = No preference
  • 02 = No challenge requested
  • 03 = Challenge requested (3DS Requestor preference)
  • 04 = Challenge requested (Mandate)
  • 05 = No challenge requested (transactional risk analysis is already performed)
  • 06 = No challenge requested (Data share only)
  • 07 = No challenge requested (strong consumer authentication is already performed)
  • 08 = No challenge requested (utilise whitelist exemption if no challenge required)
  • 09 = Challenge requested (whitelist prompt requested if challenge required)
= 2 NNO
idDS assigned 3DS Requestor identifier.< 35 ANYES
nameDS assigned 3DS Requestor name.< 40 ANYES
urlFully qualified URL of 3DS Requestor website or customer care site.< 2048 ANYES
three_ds_requestor.
authentication_info
Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.
dataData that documents and supports a specific authentication process.< 20000 ANNO
methodMechanism used by the Cardholder to authenticate to the 3DS Requestor.
  • 01 = No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)
  • 02 = Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials
  • 03 = Login to the cardholder account at the 3DS Requestor system using federated ID
  • 04 = Login to the cardholder account at the 3DS Requestor system using issuer credentials
  • 05 = Login to the cardholder account at the 3DS Requestor system using third-party authentication
  • 06 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
  • 07 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed)
  • 08 = SRC Assurance Data
= 2 NNO
timestampDate and time in UTC of the cardholder authentication in YYYYMMDDHHMM format.= 12 NNO
three_ds_requestor.
prior_authentication_info
Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
dataData that documents and supports a specific authentication process.< 2048 ANNO
methodMechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
  • 01 = Frictionless authentication occurred by ACS
  • 02 = Cardholder challenge occurred by ACS
  • 03 = AVS verified
  • 04 = Other issuer methods
= 2 NNO
timestampDate and time in UTC of the prior cardholder authentication in YYYYMMDDHHMM format.= 12 NNO
referenceThis data element provides additional information to the ACS to determine the best approach for handing a request.< 36 ANNO
acquirer
binAcquiring institution identification code as assigned by the DS receiving the AReq message.< 11 ANYES
merchant_idAcquirer-assigned Merchant identifier.< 35 ANYES
browserThese parameters are mandatory if device_channel = 02.
accept_headerExact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.< 2048 ANCOND.
ipIP address of the browser as returned by the HTTP headers to the 3DS Requestor.< 45 ANCOND.
java_enabledBoolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.< 5 ANCOND.
javascript_enabledBoolean that represents the ability of the cardholder browser to execute JavaScript.< 5 ANCOND.
languageValue representing the browser language as defined in IETF BCP47. Returned from navigator.language property.< 8 ANCOND.
color_depthValue representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
  • 1 = 1 bit
  • 4 = 4 bits
  • 8 = 8 bits
  • 15 = 15 bits
  • 16 = 16 bits
  • 24 = 24 bits
  • 32 = 32 bits
  • 48 = 48 bits
Note: If the value in the request differs from the ones specified above, the nearest value will be selected, always favoring the smaller one.
Example: 30 will be chosen as 24.
< 2 NCOND.
screen_heightTotal height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.< 6 NCOND.
screen_widthTotal width of the cardholder’s screen in pixels. Value is returned from the screen.width property.< 6 ANCOND.
tzTime-zone offset in minutes between UTC and the Cardholder browser local time. Value is returned from the getTimezoneOffset() method.< 5 ANCOND.
user_agentExact content of the HTTP user-agent header.< 2048 ANCOND.
cardholder
card_expiry_dateExpiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder in YYMM format.= 4 NYES
addr_matchIndicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
  • Y = Shipping Address matches Billing Address
  • N = Shipping Address does not match Billing Address
= 1 ANNO
emailWhile not mandatory, it is advisable to send this field as it aids in risk assessment, increasing the likelihood of obtaining a silent authentication.< 256 ANYES
nameName of the Cardholder.< 45 ANYES
cardholder.
home_phone
The home phone number provided by the Cardholder.
ccCountry Code< 3 NYES
subscriberSubscriber< 15 NYES
cardholder.
mobile_phone
It is advisable to send this field, as it aids in risk assessment, increasing the chances of obtaining a silent authentication.
ccCountry Code< 3 NYES
subscriberSubscriber< 15 NYES
cardholder.
work_phone
The work phone number provided by the Cardholder.
ccCountry Code< 3 NYES
subscriberSubscriber< 15 NYES
cardholder.
acct
typeIndicates the type of account. For example, for a multi-account card product.
  • 01 = Not Applicable
  • 02 = Credit
  • 03 = Debit
= 2 NYES
numberCustomer's card number (PAN), the number or token field must always be sent in the request< 19 NCOND
tokenHASH of a card stored in Carat, the number or token field must always be sent in the request= 88 ANCOND
idAdditional information about the account optionally provided by the 3DS Requestor.< 64 ANNO
cardholder.
acct.
info
ch_acc_age_indLength of time that the cardholder has had the account with the 3DS Requestor.
  • 01 = No account (guest check-out)
  • 02 = Created during this transaction
  • 03 = Less than 30 days
  • 04 = 30−60 days
  • 05 = More than 60 days
= 2 NNO
ch_acc_changeDate 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, in YYYYMMDD format.= 8 NNO
ch_acc_change_indLength 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.
  • 01 = Changed during this transaction
  • 02 = Less than 30 days
  • 03 = 30−60 days
  • 04 = More than 60 days
= 2 NNO
ch_acc_dateDate that the cardholder opened the account with the 3DS Requestor in YYYYMMDD format.= 8 NNO
ch_acc_pw_changeDate that cardholder’s account with the 3DS Requestor had a password change or account reset in YYYYMMDD format.= 8 NNO
ch_acc_pw_change_indIndicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
  • 01 = No change
  • 02 = Changed during this transaction
  • 03 = Less than 30 days
  • 04 = 30−60 days
  • 05 = More than 60 days
= 2 NNO
nb_purchase_accountNumber of purchases with this cardholder account during the previous six months.< 4 NNO
provision_attempts_dayNumber of Add Card attempts in the last 24 hours.< 3 NNO
txn_activity_dayNumber of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.< 3 NNO
txn_activity_yearNumber of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.< 3 NNO
payment_acc_ageDate that the payment account was enrolled in the cardholder’s account with the 3DS Requestor in YYYYMMDD format.= 8 NNO
payment_acc_indIndicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
  • 01 = No account (guest check-out)
  • 02 = During this transaction
  • 03 = Less than 30 days
  • 04 = 30−60 days
  • 05 = More than 60 days
= 2 NNO
ship_address_usageDate when the shipping address used for this transaction was first used with the 3DS Requestor in YYYYMMDD format.= 8 NNO
ship_address_usage_indIndicates when the shipping address used for this transaction was first used with the 3DS Requestor.
  • 01 = This transaction
  • 02 = Less than 30 days
  • 03 = 30−60 days
  • 04 = More than 60 days
= 2 NNO
ship_name_indicatorIndicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
  • 01 = Account Name identical to shipping Name
  • 02 = Account Name different than shipping Name
= 2 NNO
suspicious_acc_activityIndicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
  • 01 = No suspicious activity has been observed
  • 02 = Suspicious activity has been observed
= 2 NNO
cardholder.
bill_addr
cityThe city of the Cardholder billing address associated with the card used for this purchase.< 50 ANYES
countryThe ISO 3166-1 numeric three-digit country code of the Cardholder billing address associated with the card used for this purchase.= 3 NYES
line1First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.< 50 ANYES
line2Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.< 50 ANYES
line3Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.< 50 ANYES
post_codeZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.< 16 ANYES
stateThe state or province of the Cardholder billing address associated with the card used for this purchase.< 3 ANYES
cardholder.
ship_addr
cityThe city of the Cardholder shipping address associated with the card used for this purchase.< 50 ANYES
countryThe ISO 3166-1 numeric three-digit country code of the Cardholder shipping address associated with the card used for this purchase.= 3 NYES
line1First line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase.< 50 ANYES
line2Second line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase.< 50 ANYES
line3Third line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase.< 50 ANYES
post_codeZIP or other postal code of the Cardholder shipping address associated with the card used for this purchase.< 16 ANYES
stateThe state or province of the Cardholder shipping address associated with the card used for this purchase.< 3 ANYES
merchant
mccDS-specific code describing the Merchant’s type of business, product or service. Before sending the request to the DS, the 3DS automatically checks the size of the mcc field entered. If the length is less than 4 characters, the 3DS will add leading zeros until the field reaches a total length of 4 characters.= 4 NYES
country_codeISO 3166-1 numeric three-digit country code of the Merchant.= 3 NYES
nameMerchant name assigned by the Acquirer or Payment System.< 40 ANYES
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.
delivery_email_addressFor Electronic delivery, the email address to which the merchandise was delivered.< 254 ANNO
delivery_timeframeIndicates the merchandise delivery timeframe.
  • 01 = Electronic Delivery
  • 02 = Same day shipping
  • 03 = Overnight shipping
  • 04 = Two-day or more shipping
= 2 NNO
gift_card_amountFor prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).< 15 NNO
gift_card_countFor prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.< 2 NNO
gift_card_currFor prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.= 3 NNO
pre_order_dateFor a pre-ordered purchase, the expected date that the merchandise will be available in YYYYMMDD format.= 8 NNO
pre_order_purchase_indIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
  • 01 = Merchandise available
  • 02 = Future availability
= 2 NNO
reorder_items_indIndicates whether the cardholder is reordering previously purchased merchandise.
  • 01 = First time ordered
  • 02 = Reordered
= 2 NNO
ship_indicatorIndicates shipping method chosen for the transaction.
  • 01 = Ship to cardholder’s billing address
  • 02 = Ship to another verified address on file with merchant
  • 03 = Ship to address that is different than the cardholder’s billing address
  • 04 = “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)
  • 05 = Digital goods (includes online services, electronic gift cards and redemption codes)
  • 06 = Travel and Event tickets, not shipped
  • 07 = Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
= 2 NNO
message
categoryIdentifies the category of the message for a specific use case.
  • 01 - Payment Authentication
  • 02 - Non-Payment Authentication
  • 80 - Mastercard Identity Check Insights (Data only) Authentication Lear more
= 2 NYES
message.
extension[]
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
criticality_indicatorA Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.< 5 ANNO
dataThe data carried in the extension.ObjectNO
idA unique identifier for the extension.< 64 ANNO
nameThe name of the extension data set as defined by the extension owner.< 64 ANNO
purchase
amountPurchase amount in minor units of currency with all punctuation removed.< 48 NYES
currencyISO 4217 three-digit currency code in which purchase amount is expressed.= 3 NYES
exponentMinor units of currency as specified in the ISO 4217 currency exponent.= 1 NYES
dateDate and time of the purchase expressed in UTC in YYYYMMDDHHMMSS format.= 12 NYES
instal_dataIndicates the maximum number of authorizations permitted for instalment payments. Value shall be greater than 1.< 3 NNO
recurring
expiryDate after which no further authorizations shall be performed in YYYYMMDD format. Mandatory when three_ds_requestor. authentication_ind = 02 or 03.= 8 NCOND.
frequencyIndicates the minimum number of days between authorizations. Mandatory when three_ds_requestor. authentication_ind = 02 or 03.< 4 NCOND.
sdkThese fields are mandatory for 3DS SDKs (device_channel = 01).
app_idUniversally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.= 36 ANCOND.
enc_dataJWE Object (represented as a string) containing data encrypted by the SDK for the DS to decrypt.< 64000 ANCOND.
ephem_pub_keyPublic key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.ObjectCOND.
max_timeoutIndicates maximum amount of time (in minutes) for all exchanges.< 2 NCOND.
trans_idUniversally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.= 36 ANCOND.
ifaceLists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
  • 01 = Native
  • 02 = HTML
  • 03 = Both
= 2 NCOND.
ui_type[]Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.
  • 01 = Text
  • 02 = Single Select
  • 03 = Multi Select
  • 04 = OOB
  • 05 = HTML Other (valid only for HTML UI)
= 2 N[]COND.
white_list
statusEnables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.
  • Y = 3DS Requestor is whitelisted by cardholder
  • N = 3DS Requestor is not whitelisted by cardholder
  • E = Not eligible as determined by issuer
  • P = Pending confirmation by cardholder
  • R = Cardholder rejected
  • U = Whitelist status unknown, unavailable, or does not apply
= 1 ANNO
status_sourceThis data element will be populated by the system setting Whitelist Status.
  • 01 = 3DS Server
  • 02 = DS
  • 03 = ACS
= 2 NNO

Response parameters#

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the authentication service:

ParameterDescriptionFormat
eciElectronic Commerce Indicator= 2 N
broad_infoUnstructured information sent between the 3DS Server, the DS and the ACS.Object
device_channelIndicates the type of channel interface being used to initiate the transaction. Default value: 02. Learn more.= 2 N
message_versionTransaction Version (This version must be used on CRes request)< 8 AN
three_ds_server
trans_id3DS Server Transaction ID= 36 AN
status3DS Server transaction status. Learn more.= 3 AN
acs
challenge_mandatedIndication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.
  • Y = Challenge is mandated
  • N = Challenge is not mandated
= 1 AN
operator_idDS assigned ACS identifier.< 32 AN
reference_numberUnique identifier assigned by the EMVCo Secretariat upon Testing and Approval.< 32 AN
trans_idUniversally Unique transaction identifier assigned by the ACS to identify a single transaction.= 36 AN
urlFully qualified URL of the ACS to be used for the challenge.< 2048 AN
decoupled_confirmation_indIndicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder.
  • Y = Confirms Decoupled Authentication will be utilised
  • N = Decoupled Authentication will not be utilised
= 1 AN
signed_contentContains the JWS object (represented as a string) created by the ACS for the ARes message.var. AN
ifaceThis the ACS interface that the challenge will present to the cardholder.
  • 01 = Native UI
  • 02 = HTML UI
= 2 N
ui_templateIdentifies the UI Template format that the ACS first presents to the consumer.
  • 01 = Text
  • 02 = Single Select
  • 03 = Multi Select
  • 04 = OOB
  • 05 = HTML Other
= 2 N
authentication
typeIndicates the type of authentication method the Issuer will use to challenge the Cardholder.
  • 01 = Static
  • 02 = Dynamic
  • 03 = OOB
  • 04 = Decoupled
= 2 N
valuePayment 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 (CAVV).= 28 AN
cardholder
infoText provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction.< 128 AN
ds
reference_numberEMVCo-assigned unique identifier to track approved DS.< 32 AN
trans_idUniversally unique transaction identifier assigned by the DS to identify a single transaction.= 36 AN
message.
extension[]
Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.
criticality_indicatorA Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.< 5 AN
dataThe data carried in the extension.Object
idA unique identifier for the extension.< 64 AN
nameThe name of the extension data set as defined by the extension owner.< 64 AN
transaction
statusIndicates whether a transaction qualifies as an authenticated transaction or account verification.
  • Y = Authentication Verification Successful.
  • N = Not Authenticated /Account Not Verified; Transaction denied.
  • U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
  • A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
  • C = Challenge Required; Additional authentication is required using the CReq/CRes.
  • D = Challenge Required; Decoupled Authentication confirmed.
  • R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
= 1 AN
status_reasonProvides information on why the Transaction Status field has the specified 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
  • 22 = ACS technical issue
  • 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor
  • 24 = 3DS Requestor Decoupled Max Expiry Time exceeded
  • 25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
  • 26 = Authentication attempted but not performed by the cardholder
= 2 N
white_list
statusEnables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.
  • Y = 3DS Requestor is whitelisted by cardholder
  • N = 3DS Requestor is not whitelisted by cardholder
  • E = Not eligible as determined by issuer
  • P = Pending confirmation by cardholder
  • R = Cardholder rejected
  • U = Whitelist status unknown, unavailable, or does not apply
= 1 AN
status_sourceThis data element will be populated by the system setting Whitelist Status.
  • 01 = 3DS Server
  • 02 = DS
  • 03 = ACS
= 2 N
sdk
trans_idUniversally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.= 36 AN
error
codeError code. Learn more.< 3 N
componentIndicates which component identified the error.
  • C = 3DS SDK
  • S = 3DS Server
  • D = DS
  • A = ACS
= 1 AN
descriptionError description< 2048 AN
detailError details< 28 AN