three_ds_authentication_token

token

uuid

required

Globally unique identifier for the 3DS authentication.

200 OK

object

Represents a 3DS authentication

account_type

string | null

enum

required

Type of account/card that is being used for the transaction. Maps to EMV 3DS field acctType.

CREDIT``DEBIT``NOT_APPLICABLE``null

additional_data

object | null

Object containing additional data about the 3DS request that is beyond the EMV 3DS standard spec (e.g., specific fields that only certain card networks send but are not required across all 3DS requests).

network_decision

string | null

enum

Mastercard only: Indicates whether the network would have considered the authentication request to be low risk or not.

LOW_RISK``NOT_LOW_RISK``null

network_risk_score

integer | null

Mastercard only: Assessment by the network of the authentication risk level, with a higher value indicating a higher amount of risk. Permitted values: Integer between 0-950, in increments of 50.

app

object | null

Object containing data about the app used in the e-commerce transaction. Present if the channel is 'APP_BASED'.

device_info

string | null

Raw device information - base64-encoded JSON object. Maps to EMV 3DS field deviceInfo.

ip

string | null

IP address of the device.

platform

string | null

Device platform: Android, iOS, Windows, etc.

device

string | null

Device model: e.g. "Apple iPhone 16".

os

string | null

Operating System: e.g. "Android 12", "iOS 17.1".

locale

string | null

Device locale: e.g. "en-US".

time_zone

string | null

Time zone offset in minutes between UTC and device local time.

screen_width

integer | null

Screen width in pixels.

screen_height

integer | null

Screen height in pixels.

latitude

number | null

-90 to 90

Latitude coordinate of current device location.

longitude

number | null

-180 to 180

Longitude coordinate of current device location.

authentication_request_type

string | null

enum

Type of authentication request - i.e., the type of transaction or interaction is causing the merchant to request an authentication. Maps to EMV 3DS field threeDSRequestorAuthenticationInd.

ADD_CARD``BILLING_AGREEMENT``DELAYED_SHIPMENT``EMV_TOKEN_CARDHOLDER_VERIFICATION``INSTALLMENT_TRANSACTION``MAINTAIN_CARD``PAYMENT_TRANSACTION``RECURRING_TRANSACTION``SPLIT_PAYMENT``SPLIT_SHIPMENT``null

authentication_result

string

enum

required

Indicates the outcome of the 3DS authentication process.

DECLINE``SUCCESS``PENDING_CHALLENGE``PENDING_DECISION

browser

object | null

Object containing data about the browser used in the e-commerce transaction. Present if the channel is 'BROWSER'.

accept_header

string | null

Content of the HTTP accept headers as sent from the cardholder's browser to the 3DS requestor (e.g., merchant or digital wallet).

ipString

string | null

IP address of the browser as returned by the HTTP headers to the 3DS requestor (e.g., merchant or digital wallet). Maps to EMV 3DS field browserIP.

java_enabled

boolean | null

Indicates whether the cardholder's browser has the ability to execute Java. Maps to EMV 3DS field browserJavaEnabled.

javascript_enabled

boolean | null

Indicates whether the cardholder's browser has the ability to execute JavaScript. Maps to EMV 3DS field browserJavascriptEnabled.

language

string | null

Language of the cardholder's browser as defined in IETF BCP47. Maps to EMV 3DS field browserLanguage.

time_zone

string | null

Time zone offset in minutes between UTC and browser local time. Maps to EMV 3DS field browserTz.

user_agent

string | null

Content of the HTTP user-agent header. Maps to EMV 3DS field browserUserAgent.

card_expiry_check

string

enum

required

Indicates whether the expiration date provided by the cardholder during checkout matches Lithic's record of the card's expiration date.

MATCH``MISMATCH``NOT_PRESENT

card_token

uuid

required

Globally unique identifier for the card on which the 3DS authentication has occurred. Permitted values: 36-digit version 4 UUID (including hyphens).

cardholder

object

required

Object containing data about the cardholder provided during the transaction.

address_match

boolean | null

Indicates whether the shipping address and billing address provided by the cardholder are the same. This value - and assessment of whether the addresses match - is provided directly in the 3DS request and is not determined by Lithic. Maps to EMV 3DS field addrMatch.

address_on_file_match

string

enum

Lithic's evaluation result comparing the transaction's address data with the cardholder KYC data if it exists. In the event Lithic does not have any Cardholder KYC data, or the transaction does not contain any address data, NOT_PRESENT will be returned

MATCH``MATCH_ADDRESS_ONLY``MATCH_ZIP_ONLY``MISMATCH``NOT_PRESENT

billing_address

object

Object containing data on the billing address provided during the transaction.

billing_address object

email

string | null

Email address that is either provided by the cardholder or is on file with the merchant in a 3RI request. Maps to EMV 3DS field email.

name

string | null

Name of the cardholder. Maps to EMV 3DS field cardholderName.

phone_number_home

string | null

Home phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields homePhone.cc and homePhone.subscriber.

phone_number_mobile

string | null

Mobile/cell phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields mobilePhone.cc and mobilePhone.subscriber.

phone_number_work

string | null

Work phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields workPhone.cc and workPhone.subscriber.

shipping_address

object

Object containing data on the shipping address provided during the transaction.

shipping_address object

challenge_metadata

object | null

Metadata about the challenge method and delivery. Only present when a challenge is triggered.

method_type

string

enum

required

The type of challenge method used for authentication.

SMS_OTP``OUT_OF_BAND

phone_number

string | null

The phone number used for delivering the OTP. Relevant only for SMS_OTP method.

status

string

enum

required

Indicates the status of the challenge

• SUCCESS - Cardholder completed the challenge successfully
• PENDING - Challenge was issued to the cardholder and was not completed yet
• SMS_DELIVERY_FAILED - Lithic confirmed undeliverability of the SMS to the provided phone number. Relevant only for SMS_OTP method
• CARDHOLDER_TIMEOUT - Cardholder failed to complete the challenge within the given challenge TTL
• CANCELED_VIA_CHALLENGE_UI - Cardholder canceled the challenge by selecting "cancel" on the challenge UI
• CANCELED_OOB - Cardholder canceled the challenge out of band
• ATTEMPTS_EXCEEDED - Cardholder failed the challenge by either entering an incorrect OTP more than the allowed number of times or requesting a new OTP more than the allowed number of times
• ABORTED - Merchant aborted authentication after a challenge was requested
• ERROR - The challenge failed for a reason different than those documented

SUCCESS``PENDING``SMS_DELIVERY_FAILED``CARDHOLDER_TIMEOUT``CANCELED_VIA_CHALLENGE_UI``CANCELED_OOB``ATTEMPTS_EXCEEDED``ABORTED``ERROR

challenge_orchestrated_by

string | null

enum

Entity that orchestrates the challenge. This won't be set for authentications for which a decision has not yet been made (e.g. in-flight customer decisioning request).

LITHIC``CUSTOMER``NO_CHALLENGE``null

channel

string

enum

required

Channel in which the authentication occurs. Maps to EMV 3DS field deviceChannel.

APP_BASED``BROWSER``THREE_DS_REQUESTOR_INITIATED

created

date-time

required

Date and time when the authentication was created in Lithic's system. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd'T'hh:mm:ssZ.

decision_made_by

string | null

enum

Entity that made the authentication decision. This won't be set for authentications for which a decision has not yet been made (e.g. in-flight customer decisioning request).

LITHIC_RULES``LITHIC_DEFAULT``CUSTOMER_RULES``CUSTOMER_ENDPOINT``NETWORK``UNKNOWN``null

merchant

object

required

Object containing data about the merchant involved in the e-commerce transaction.

country

string | null

Country code of the merchant requesting 3DS authentication. Maps to EMV 3DS field merchantCountryCode. Permitted values: ISO 3166-1 alpha-3 country code (e.g., USA). May not be present for non-payment authentications.

id

string | null

Merchant identifier as assigned by the acquirer. Maps to EMV 3DS field acquirerMerchantId. May not be present for non-payment authentications.

mcc

string | null

Merchant category code assigned to the merchant that describes its business activity type. Maps to EMV 3DS field mcc. May not be present for non-payment authentications.

name

string | null

Name of the merchant. Maps to EMV 3DS field merchantName. May not be present for non-payment authentications.

risk_indicator

object

required

Object containing additional data indicating additional risk factors related to the e-commerce transaction.

risk_indicator object

message_category

string

enum

required

Either PAYMENT_AUTHENTICATION or NON_PAYMENT_AUTHENTICATION. For NON_PAYMENT_AUTHENTICATION, additional_data and transaction fields are not populated.

NON_PAYMENT_AUTHENTICATION``PAYMENT_AUTHENTICATION

three_ds_requestor_challenge_indicator

string

enum

required

Indicates whether a challenge is requested for this transaction

• NO_PREFERENCE - No Preference
• NO_CHALLENGE_REQUESTED - No Challenge Requested
• CHALLENGE_PREFERENCE - Challenge requested (3DS Requestor preference)
• CHALLENGE_MANDATE - Challenge requested (Mandate)
• NO_CHALLENGE_RISK_ALREADY_ASSESSED - No Challenge requested (Transactional risk analysis is already performed)
• DATA_SHARE_ONLY - No Challenge requested (Data Share Only)
• OTHER - Other indicators not captured by above. These are rarely used

NO_PREFERENCE``NO_CHALLENGE_REQUESTED``CHALLENGE_PREFERENCE``CHALLENGE_MANDATE``NO_CHALLENGE_RISK_ALREADY_ASSESSED``DATA_SHARE_ONLY``OTHER

three_ri_request_type

string | null

enum

Type of 3DS Requestor Initiated (3RI) request — i.e., a 3DS authentication that takes place at the initiation of the merchant rather than the cardholder. The most common example of this is where a merchant is authenticating before billing for a recurring transaction such as a pay TV subscription or a utility bill. Maps to EMV 3DS field threeRIInd.

ACCOUNT_VERIFICATION``ADD_CARD``BILLING_AGREEMENT``CARD_SECURITY_CODE_STATUS_CHECK``DELAYED_SHIPMENT``DEVICE_BINDING_STATUS_CHECK``INSTALLMENT_TRANSACTION``MAIL_ORDER``MAINTAIN_CARD_INFO``OTHER_PAYMENT``RECURRING_TRANSACTION``SPLIT_PAYMENT``SPLIT_SHIPMENT``TELEPHONE_ORDER``TOP_UP``TRUST_LIST_STATUS_CHECK``null

token

uuid

required

Globally unique identifier for the 3DS authentication. Permitted values: 36-digit version 4 UUID (including hyphens).

transaction

object | null

Object containing data about the e-commerce transaction for which the merchant is requesting authentication.

amount

number

required

Amount of the purchase in minor units of currency with all punctuation removed. Maps to EMV 3DS field purchaseAmount.

cardholder_amount

number | null

required

Approximate amount of the purchase in minor units of cardholder currency. Derived from amount using a daily conversion rate.

currency

string

required

length between 3 and 3

Currency of the purchase. Maps to EMV 3DS field purchaseCurrency. Permitted values: ISO 4217 three-character currency code (e.g., USD).

currency_exponent

number

required

Minor units of currency, as specified in ISO 4217 currency exponent. Maps to EMV 3DS field purchaseExponent.

date_time

date-time

required

Date and time when the authentication was generated by the merchant/acquirer's 3DS server. Maps to EMV 3DS field purchaseDate. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd'T'hh:mm:ssZ.

type

string | null

enum

required

Type of the transaction for which a 3DS authentication request is occurring. Maps to EMV 3DS field transType.

ACCOUNT_FUNDING``CHECK_ACCEPTANCE``GOODS_SERVICE_PURCHASE``PREPAID_ACTIVATION_AND_LOAD``QUASI_CASH_TRANSACTION``null