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:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on 3DS Server. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on 3DS Server. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | Fixed value application/json. | = 15 AN | YES |
carat_merchant_id | Carat merchant code must be sent only if the token field is sent in the request | < 15 AN | COND. |
carat_merchant_key | The authentication key of the Carat merchant must be sent only if the token field is sent in the request | < 80 AN | COND. |
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
Response:
Request with token:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Challenge Flow#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Request parameters#
The table below describes the request parameters of the authentication service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
device_channel | Indicates the type of channel interface being used to initiate the transaction. Default value: 02corresponds to Browser (BRW). Learn more. | = 2 N | YES |
three_ri_ind | Indicates the type of 3RI request.
device_channel = 03. | = 2 N | COND. |
three_ds_comp_ind | Indicates whether the 3DS Method successfully completed.
device_channel = 02. | = 1 A | COND. |
pay_token_ind | A value of true indicates that the transaction was de-tokenised prior to being received by the ACS. | < 5 AN | NO |
pay_token_source | Indicates where the de-tokenisation occurs.
| = 2 N | NO |
notification_url | Fully qualified URL of the 3DS Requestor to receive the CRes message. Mandatory for device_channel = 02. | < 256 AN | COND. |
trans_type | Identifies the type of transaction being authenticated.
| = 2 N | YES |
broad_info | Unstructured information sent between the 3DS Server, the DS and the ACS. | Object | NO |
| three_ds_requestor | |||
authentication_ind | Indicates the type of Authentication request.
| = 2 N | YES |
challenge_ind | This 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."
| = 2 N | NO |
id | DS assigned 3DS Requestor identifier. | < 35 AN | YES |
name | DS assigned 3DS Requestor name. | < 40 AN | YES |
url | Fully qualified URL of 3DS Requestor website or customer care site. | < 2048 AN | YES |
| three_ds_requestor. authentication_info | Information about how the 3DS Requestor authenticated the cardholder before or during the transaction. | ||
data | Data that documents and supports a specific authentication process. | < 20000 AN | NO |
method | Mechanism used by the Cardholder to authenticate to the 3DS Requestor.
| = 2 N | NO |
timestamp | Date and time in UTC of the cardholder authentication in YYYYMMDDHHMM format. | = 12 N | NO |
| three_ds_requestor. prior_authentication_info | Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction. | ||
data | Data that documents and supports a specific authentication process. | < 2048 AN | NO |
method | Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
| = 2 N | NO |
timestamp | Date and time in UTC of the prior cardholder authentication in YYYYMMDDHHMM format. | = 12 N | NO |
reference | This data element provides additional information to the ACS to determine the best approach for handing a request. | < 36 AN | NO |
| acquirer | |||
bin | Acquiring institution identification code as assigned by the DS receiving the AReq message. | < 11 AN | YES |
merchant_id | Acquirer-assigned Merchant identifier. | < 35 AN | YES |
| browser | These parameters are mandatory if device_channel = 02. | ||
accept_header | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. | < 2048 AN | COND. |
ip | IP address of the browser as returned by the HTTP headers to the 3DS Requestor. | < 45 AN | COND. |
java_enabled | Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. | < 5 AN | COND. |
javascript_enabled | Boolean that represents the ability of the cardholder browser to execute JavaScript. | < 5 AN | COND. |
language | Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. | < 8 AN | COND. |
color_depth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
Example: 30 will be chosen as 24. | < 2 N | COND. |
screen_height | Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. | < 6 N | COND. |
screen_width | Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property. | < 6 AN | COND. |
tz | Time-zone offset in minutes between UTC and the Cardholder browser local time. Value is returned from the getTimezoneOffset() method. | < 5 AN | COND. |
user_agent | Exact content of the HTTP user-agent header. | < 2048 AN | COND. |
| cardholder | |||
card_expiry_date | Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder in YYMM format. | = 4 N | YES |
addr_match | Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
| = 1 AN | NO |
email | While not mandatory, it is advisable to send this field as it aids in risk assessment, increasing the likelihood of obtaining a silent authentication. | < 256 AN | YES |
name | Name of the Cardholder. | < 45 AN | YES |
| cardholder. home_phone | The home phone number provided by the Cardholder. | ||
cc | Country Code | < 3 N | YES |
subscriber | Subscriber | < 15 N | YES |
| cardholder. mobile_phone | It is advisable to send this field, as it aids in risk assessment, increasing the chances of obtaining a silent authentication. | ||
cc | Country Code | < 3 N | YES |
subscriber | Subscriber | < 15 N | YES |
| cardholder. work_phone | The work phone number provided by the Cardholder. | ||
cc | Country Code | < 3 N | YES |
subscriber | Subscriber | < 15 N | YES |
| cardholder. acct | |||
type | Indicates the type of account. For example, for a multi-account card product.
| = 2 N | YES |
number | Customer's card number (PAN), the number or token field must always be sent in the request | < 19 N | COND |
token | HASH of a card stored in Carat, the number or token field must always be sent in the request | = 88 AN | COND |
id | Additional information about the account optionally provided by the 3DS Requestor. | < 64 AN | NO |
| cardholder. acct. info | |||
ch_acc_age_ind | Length of time that the cardholder has had the account with the 3DS Requestor.
| = 2 N | NO |
ch_acc_change | 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, in YYYYMMDD format. | = 8 N | NO |
ch_acc_change_ind | 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.
| = 2 N | NO |
ch_acc_date | Date that the cardholder opened the account with the 3DS Requestor in YYYYMMDD format. | = 8 N | NO |
ch_acc_pw_change | Date that cardholder’s account with the 3DS Requestor had a password change or account reset in YYYYMMDD format. | = 8 N | NO |
ch_acc_pw_change_ind | Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
| = 2 N | NO |
nb_purchase_account | Number of purchases with this cardholder account during the previous six months. | < 4 N | NO |
provision_attempts_day | Number of Add Card attempts in the last 24 hours. | < 3 N | NO |
txn_activity_day | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. | < 3 N | NO |
txn_activity_year | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. | < 3 N | NO |
payment_acc_age | Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor in YYYYMMDD format. | = 8 N | NO |
payment_acc_ind | Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
| = 2 N | NO |
ship_address_usage | Date when the shipping address used for this transaction was first used with the 3DS Requestor in YYYYMMDD format. | = 8 N | NO |
ship_address_usage_ind | Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
| = 2 N | NO |
ship_name_indicator | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
| = 2 N | NO |
suspicious_acc_activity | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
| = 2 N | NO |
| cardholder. bill_addr | |||
city | The city of the Cardholder billing address associated with the card used for this purchase. | < 50 AN | YES |
country | The ISO 3166-1 numeric three-digit country code of the Cardholder billing address associated with the card used for this purchase. | = 3 N | YES |
line1 | First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | < 50 AN | YES |
line2 | Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | < 50 AN | YES |
line3 | Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. | < 50 AN | YES |
post_code | ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. | < 16 AN | YES |
state | The state or province of the Cardholder billing address associated with the card used for this purchase. | < 3 AN | YES |
| cardholder. ship_addr | |||
city | The city of the Cardholder shipping address associated with the card used for this purchase. | < 50 AN | YES |
country | The ISO 3166-1 numeric three-digit country code of the Cardholder shipping address associated with the card used for this purchase. | = 3 N | YES |
line1 | First line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase. | < 50 AN | YES |
line2 | Second line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase. | < 50 AN | YES |
line3 | Third line of the street address or equivalent local portion of the Cardholder shipping address associated with the card used for this purchase. | < 50 AN | YES |
post_code | ZIP or other postal code of the Cardholder shipping address associated with the card used for this purchase. | < 16 AN | YES |
state | The state or province of the Cardholder shipping address associated with the card used for this purchase. | < 3 AN | YES |
| merchant | |||
mcc | DS-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 N | YES |
country_code | ISO 3166-1 numeric three-digit country code of the Merchant. | = 3 N | YES |
name | Merchant name assigned by the Acquirer or Payment System. | < 40 AN | YES |
| 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_address | For Electronic delivery, the email address to which the merchandise was delivered. | < 254 AN | NO |
delivery_timeframe | Indicates the merchandise delivery timeframe.
| = 2 N | NO |
gift_card_amount | For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). | < 15 N | NO |
gift_card_count | For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. | < 2 N | NO |
gift_card_curr | For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card. | = 3 N | NO |
pre_order_date | For a pre-ordered purchase, the expected date that the merchandise will be available in YYYYMMDD format. | = 8 N | NO |
pre_order_purchase_ind | Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
| = 2 N | NO |
reorder_items_ind | Indicates whether the cardholder is reordering previously purchased merchandise.
| = 2 N | NO |
ship_indicator | Indicates shipping method chosen for the transaction.
| = 2 N | NO |
| message | |||
category | Identifies the category of the message for a specific use case.
| = 2 N | YES |
| message. extension[] | Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension. | ||
criticality_indicator | A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message. | < 5 AN | NO |
data | The data carried in the extension. | Object | NO |
id | A unique identifier for the extension. | < 64 AN | NO |
name | The name of the extension data set as defined by the extension owner. | < 64 AN | NO |
| purchase | |||
amount | Purchase amount in minor units of currency with all punctuation removed. | < 48 N | YES |
currency | ISO 4217 three-digit currency code in which purchase amount is expressed. | = 3 N | YES |
exponent | Minor units of currency as specified in the ISO 4217 currency exponent. | = 1 N | YES |
date | Date and time of the purchase expressed in UTC in YYYYMMDDHHMMSS format. | = 12 N | YES |
instal_data | Indicates the maximum number of authorizations permitted for instalment payments. Value shall be greater than 1. | < 3 N | NO |
| recurring | |||
expiry | Date after which no further authorizations shall be performed in YYYYMMDD format. Mandatory when three_ds_requestor. authentication_ind = 02 or 03. | = 8 N | COND. |
frequency | Indicates the minimum number of days between authorizations. Mandatory when three_ds_requestor. authentication_ind = 02 or 03. | < 4 N | COND. |
| sdk | These fields are mandatory for 3DS SDKs (device_channel = 01). | ||
app_id | Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation. | = 36 AN | COND. |
enc_data | JWE Object (represented as a string) containing data encrypted by the SDK for the DS to decrypt. | < 64000 AN | COND. |
ephem_pub_key | Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. | Object | COND. |
max_timeout | Indicates maximum amount of time (in minutes) for all exchanges. | < 2 N | COND. |
trans_id | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. | = 36 AN | COND. |
iface | Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
| = 2 N | COND. |
ui_type[] | Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.
| = 2 N[] | COND. |
| white_list | |||
status | Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.
| = 1 AN | NO |
status_source | This data element will be populated by the system setting Whitelist Status.
| = 2 N | NO |
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:
| Parameter | Description | Format |
|---|---|---|
eci | Electronic Commerce Indicator | = 2 N |
broad_info | Unstructured information sent between the 3DS Server, the DS and the ACS. | Object |
device_channel | Indicates the type of channel interface being used to initiate the transaction. Default value: 02. Learn more. | = 2 N |
message_version | Transaction Version (This version must be used on CRes request) | < 8 AN |
| three_ds_server | ||
trans_id | 3DS Server Transaction ID | = 36 AN |
status | 3DS Server transaction status. Learn more. | = 3 AN |
| acs | ||
challenge_mandated | Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.
| = 1 AN |
operator_id | DS assigned ACS identifier. | < 32 AN |
reference_number | Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. | < 32 AN |
trans_id | Universally Unique transaction identifier assigned by the ACS to identify a single transaction. | = 36 AN |
url | Fully qualified URL of the ACS to be used for the challenge. | < 2048 AN |
decoupled_confirmation_ind | Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder.
| = 1 AN |
signed_content | Contains the JWS object (represented as a string) created by the ACS for the ARes message. | var. AN |
iface | This the ACS interface that the challenge will present to the cardholder.
| = 2 N |
ui_template | Identifies the UI Template format that the ACS first presents to the consumer.
| = 2 N |
| authentication | ||
type | Indicates the type of authentication method the Issuer will use to challenge the Cardholder.
| = 2 N |
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 (CAVV). | = 28 AN |
| cardholder | ||
info | Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. | < 128 AN |
| ds | ||
reference_number | EMVCo-assigned unique identifier to track approved DS. | < 32 AN |
trans_id | Universally 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_indicator | A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message. | < 5 AN |
data | The data carried in the extension. | Object |
id | A unique identifier for the extension. | < 64 AN |
name | The name of the extension data set as defined by the extension owner. | < 64 AN |
| transaction | ||
status | Indicates whether a transaction qualifies as an authenticated transaction or account verification.
| = 1 AN |
status_reason | Provides information on why the Transaction Status field has the specified value.
| = 2 N |
| white_list | ||
status | Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.
| = 1 AN |
status_source | This data element will be populated by the system setting Whitelist Status.
| = 2 N |
| sdk | ||
trans_id | Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. | = 36 AN |
| error | ||
code | Error code. Learn more. | < 3 N |
component | Indicates which component identified the error.
| = 1 AN |
description | Error description | < 2048 AN |
detail | Error details | < 28 AN |