3DS Authentication Object
Learn about the 3DS authentication object.
Each time a 3DS authentication takes place, Lithic will send a webhook to your registered Events webhook URL(s) subscribing to events of type three_ds_authentication.created
with the below payload. Most data fields can be mapped to the EMV 3DS spec, except in cases of fields generated by Lithic (e.g., token associated with an authentication). Note that not all 3DS authentications will have every field populated.
{
"event_type": String,
"token": String,
"created": String,
"card_token": String,
"card_expiry_check": String,
"channel": String,
"decision_made_by": String,
"account_type": String,
"authentication_result": String,
"authentication_request_type": String,
"three_ri_request_type": String,
"message_category": String,
"cardholder": {
"address_match": Boolean,
"name": String,
"email": String,
"phone_number_home": String,
"phone_number_mobile": String,
"phone_number_work": String,
"billing_address": {
"address1": String,
"address2": String,
"address3": String,
"city": String,
"country": String,
"postal_code": String,
"state": String
},
"shipping_address": {
"address1": String,
"address2": String,
"address3": String,
"city": String,
"country": String,
"postal_code": String,
"string": String
}
},
"browser": {
"ip": String,
"java_enabled": Boolean,
"javascript_enabled": Boolean,
"language": String,
"time_zone": String,
"user_agent": String
},
"app": {
"device_info": String,
"ip": String
},
"merchant": {
"country": String,
"id": String,
"mcc": String,
"name": String,
"risk_indicator": {
"delivery_email_address": String,
"delivery_time_frame": String,
"gift_card_amount": Integer,
"gift_card_count": Integer,
"gift_card_currency": String,
"order_availability": String,
"pre_order_available_date": String,
"reorder_items": String,
"shipping_method": String
}
},
"transaction": {
"amount": Integer,
"currency": String,
"currency_exponent": Integer,
"date_time": String,
"type": String
},
"additional_data": {
"network_risk_score": Integer,
"network_decision": String
}
}
event_type | Indicates the type of event that has taken place. Always present. String. Permitted values: three_ds_authentication.created . |
token | Globally unique identifier for the 3DS authentication. Always present. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
created | Date and time when the authentication was created in Lithic’s system. Always present. String. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd’T’hh:mm:ssZ. |
card_token | Globally unique identifier for the card on which the 3DS authentication has occurred. Always present. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
card_expiry_check | Indicates whether the expiration date provided by the cardholder during checkout matches Lithic’s record of the card’s expiration date. Always present. String. Permitted values: MATCH , MISMATCH , NOT_PRESENT . |
channel | Channel in which the authentication occurs. Maps to EMV 3DS field deviceChannel .Always present. String. Permitted values: - APP_BASED : The e-commerce transaction is taking place via an app (e.g., a merchant’s app) on the cardholder’s device- BROWSER : The e-commerce transaction is taking place via a browser (e.g., a merchant’s website) on the cardholder’s device- THREE_DS_REQUESTER_INITIATED : The merchant is requesting authentication without the cardholder present (e.g., a subscription-based merchant confirming the card is still valid). Also known as a "3RI" request. |
decision_made_by | Entity that made the authentication decision. Always present. String. Permitted values: - LITHIC_RULES : 3DS decisioning was made my Lithic based on a set of risk-based rules- CUSTOMER_ENDPOINT : 3DS decisioning was made by the customer’s responder endpoint |
account_type | Type of account/card that is being used for the transaction. Maps to EMV 3DS field acctType .Conditionally present if merchant asks cardholder the account type before the transaction. String. Permitted values: - NOT_APPLICABLE : Not applicable- CREDIT : Credit- DEBIT : Debit |
authentication_result | Indicates what the outcome of the 3DS authentication process is. Always present. String. Permitted values: - SUCCESS : The cardholder is considered authenticated by the issuer- DECLINE : The cardholder is not considered authenticated by the issuer |
authentication_request_type | 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 .Always present. String. Permitted values: - PAYMENT_TRANSACTION - RECURRING_TRANSACTION - INSTALLMENT_TRANSACTION - ADD_CARD - MAINTAIN_CARD - EMV_TOKEN_CARDHOLDER_VERIFICATION - BILLING_AGREEMENT - SPLIT_SHIPMENT - DELAYED_SHIPMENT - SPLIT_PAYMENT |
three_ri_request_type | Type of 3DS Requester 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 .Always present. String. Permitted values: - RECURRING_TRANSACTION - INSTALLMENT_TRANSACTION - ADD_CARD - MAINTAIN_CARD_INFO - ACCOUNT_VERIFICATION - SPLIT_SHIPMENT - TOP_UP - MAIL_ORDER - TELEPHONE_ORDER - TRUST_LIST_STATUS_CHECK - OTHER_PAYMENT - BILLING_AGREEMENT - DEVICE_BINDING_STATUS_CHECK - CARD_SECURITY_CODE_STATUS_CHECK - DELAYED_SHIPMENT - SPLIT_PAYMENT |
message_category | Indicates the category of the 3DS message. Maps to EMV 3DS field messageCategory .Always present. String. Permitted values: - PAYMENT_AUTHENTICATION : Cardholder authentication during an e-commerce transaction- NON_PAYMENT_AUTHENTICATION : Identity verification and account confirmation |
cardholder (object) | Object containing data about the cardholder provided during the transaction. |
cardholder.address_match | 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 .Optionally present. Boolean. Permitted values: - true - false |
cardholder.name | Name of the cardholder. Maps to EMV 3DS field cardholderName .Conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: 1 to 45-character string. |
cardholder.email | 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 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 254-character string. |
cardholder.phone_number_home | Home phone number provided by the cardholder. Maps to EMV 3DS fields homePhone.cc and homePhone.subscriber .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: 1 to 18-character string. |
cardholder.phone_number_mobile | Mobile/cell phone number provided by the cardholder. Maps to EMV 3DS fields mobilePhone.cc and mobilePhone.subscriber .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: 1 to 18-character string. |
cardholder.phone_number_work | Work phone number provided by the cardholder. Maps to EMV 3DS fields workPhone.cc and workPhone.subscriber .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: 1 to 18-character string. |
cardholder.billing_address (object) | Object containing data on the billing address provided during the transaction. |
cardholder.billing_address. address1 | First line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrLine1 .For payment authentications (see message_category field), conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. For non-payment authentications, conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.billing_address. address2 | Second line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrLine2 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.billing_address. address3 | Third line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrLine3 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.billing_address.city | City of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrCity .For payment authentications (see message_category field), conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. For non-payment authentications, conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.billing_address.country | Country of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrCountry .Conditionally present if cardholder.billing_address.country is present. String. Permitted values: ISO 3166-1 alpha-3 three-character abbreviation (e.g., USA). |
cardholder.billing_address. postal_code | Postal code (e.g., ZIP code) of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrPostCode .For payment authentications (see message_category field), conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. For non-payment authentications, conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 16-character string. |
cardholder.billing_address. state | State or province of the billing address provided by the cardholder. Maps to EMV 3DS field billAddrState .For payment authentications (see message_category field), conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. For non-payment authentications, conditionally present if data is available, transaction is occurring in a geography that does not restrict transmission of this information, and state data is applicable for the country. String. Permitted values: Max 3-character string of country subdivision code defined in ISO 3166-2 (e.g., CA for California). |
cardholder.shipping_address (object) | Object containing data on the shipping address provided during the transaction. |
cardholder.shipping_address. address1 | First line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrLine1 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.shipping_address. address2 | Second line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrLine2 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.shipping_address. address3 | Third line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrLine3 .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.shipping_address.city | City of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrCity .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 50-character string. |
cardholder.shipping_address. country | Country of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrCountry .Conditionally present if cardholder.billing_address.country is present. String. Permitted values: ISO 3166-1 alpha-3 three-character abbreviation (e.g., USA). |
cardholder.shipping_address. postal_code | Postal code (e.g., ZIP code) of the shipping address provided by the cardholder. Maps to EMV 3DS field shipAddrPostCode .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 16-character string. |
cardholder.shipping_address. state | State or province of the billing address provided by the cardholder. Maps to EMV 3DS field shipAddrState .For payment authentications (see message_category field), conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. For non-payment authentications, conditionally present if data is available, transaction is occurring in a geography that does not restrict transmission of this information, and state data is applicable for the country. String. Permitted values: Max 3-character string of country subdivision code defined in ISO 3166-2 (e.g., CA for California). |
browser (object) | Object containing data about the browser used in the e-commerce transaction. Since each authentication takes place either via an app or a browser, only one of the browser or the app object will be populated, while the other is set to null . |
browser.ip | IP address of the browser as returned by the HTTP headers to the 3DS requester (e.g., merchant or digital wallet). Maps to EMV 3DS field browserIP .Conditionally present if data is available and transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 45-character string. |
browser.java_enabled | Indicates whether the cardholder's browser has the ability to execute Java. Maps to EMV 3DS field browserJavaEnabled .Conditionally present if browser.javascript_enabled is true ; otherwise optionally present. Boolean. Permitted values:- true - false |
browser.javascript_enabled | Indicates whether the cardholder's browser has the ability to execute JavaScript. Maps to EMV 3DS field browserJavascriptEnabled .Always present. Boolean. Permitted values: - true - false |
browser.language | Language of the cardholder’s browser as defined in IETF BCP47. Maps to EMV 3DS field browserLanguage .Conditionally present if browser.javascript_enabled is true ; otherwise optionally present. String. Permitted values: Max 35 character string (e.g., en-US). |
browser.time_zone | Time zone of the cardholder’s browser offset in minutes between UTC and the cardholder browser’s local time. The offset is positive if the local time is behind UTC and negative if it is ahead. Maps to EMV 3DS field browserTz .Conditionally present if browser.javascript_enabled is true ; otherwise optionally present. String. Permitted values: 1 to 5-character string (e.g., 300 for UTC -5 hours, -300 for UTC +5 hours). |
browser.user_agent | Content of the HTTP user-agent header. Maps to EMV 3DS field browserUserAgent .Always present. String. Permitted values: Max 2048-character string. |
app (object) | Object containing data about the app used in the e-commerce transaction. Since each authentication takes place either via an app or a browser, only one of the browser or the app object will be populated, while the other is set to null . |
app.device_info | Device information gathered from the cardholder’s device - JSON name/value pairs that is Base64url encoded. Maps to EMV 3DS field deviceInfo .Always present. String. Permitted values: Max 64000-character string. |
app.ip | External IP address used by the app generating the 3DS authentication request. Maps to EMV 3DS field appIp .Conditionally present if transaction is occurring in a geography that does not restrict transmission of this information. String. Permitted values: Max 45-character string. |
merchant (object) | Object containing data about the merchant involved in the e-commerce transaction. |
merchant.country | Country code of the merchant requesting 3DS authentication. Maps to EMV 3DS field merchantCountryCode .For payment authentications (see message_category field), always present. For non-payment authentications, optionally present. String. Permitted values: ISO 3166-1 alpha-3 country code (e.g., USA). |
merchant.id | Merchant identifier as assigned by the acquirer. Maps to EMV 3DS field acquirerMerchantId .For payment authentications (see message_category field), always present. For non-payment authentications, optionally present. String. Permitted values: Max 35-character string. |
merchant.mcc | Merchant category code assigned to the merchant that describes its business activity type. Maps to EMV 3DS field mcc .For payment authentications (see message_category field), always present. For non-payment authentications, optionally present. String. Permitted values: 4-character string. See here for possible MCCs. |
merchant.name | Name of the merchant. Maps to EMV 3DS field merchantName .For payment authentications (see message_category field), always present. For non-payment authentications, optionally present. String. Permitted values: Max 40-character string. |
merchant.risk_indicator (object) | Object containing additional data indicating additional risk factors related to the e-commerce transaction. |
merchant.risk_indicator. delivery_email_address | In transactions with electronic delivery, email address to which merchandise is delivered. Maps to EMV 3DS field deliveryEmailAddress .Optionally present. String. Permitted values: Max 254-character string. |
merchant.risk_indicator. delivery_time_frame | The delivery time frame for the merchandise. Maps to EMV 3DS field deliveryTimeframe .Optionally present. String. Permitted values: - ELECTRONIC_DELIVERY - SAME_DAY_SHIPPING - OVERNIGHT_SHIPPING - TWO_DAY_OR_MORE_SHIPPING |
merchant.risk_indicator. gift_card_amount | In prepaid or gift card purchase transactions, purchase amount total in major units (e.g., a purchase of USD $205.10 would be 205). Maps to EMV 3DS field giftCardAmount .Optionally present. Integer. Permitted values: Max 15-character integer. |
merchant.risk_indicator. gift_card_count | In prepaid or gift card purchase transactions, count of individual prepaid or gift cards/codes purchased. Maps to EMV 3DS field giftCardCount .Optionally present. Integer. Permitted values: 2-character integer. |
merchant.risk_indicator. gift_card_currency | In prepaid or gift card purchase transactions, currency code of the gift card. Maps to EMV 3DS field giftCardCurr .Optionally present. String. Permitted values: ISO 4217 three-character currency code (e.g., USD). |
merchant.risk_indicator. order_availability | Indicates whether the purchase is for merchandise that is available now or at a future date. Maps to EMV 3DS field preOrderPurchaseInd .Optionally present. String. Permitted values: - MERCHANDISE_AVAILABLE - FUTURE_AVAILABILITY |
merchant.risk_indicator. pre_order_available_date | In pre-order purchase transactions, the expected date that the merchandise will be available. Maps to EMV 3DS field preOrderDate .Optionally present. String. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd’T’hh:mm:ssZ. |
merchant.risk_indicator. reorder_items | Indicates whether the cardholder is reordering previously purchased merchandise. Maps to EMV 3DS field reorderItemsInd .Optionally present. String. Permitted values: - FIRST_TIME_ORDERED - REORDERED |
merchant.risk_indicator. shipping_method | Shipping method that the cardholder chose for the transaction. If purchase includes one or more item, this indicator is used for the physical goods; if the purchase only includes digital goods, this indicator is used to describe the most expensive item purchased. Maps to EMV 3DS field shipIndicator .Optionally present. String. Permitted values: - SHIP_TO_BILLING_ADDRESS : Ship to the cardholder’s billing address- SHIP_TO_OTHER_VERIFIED_ADDRESS : Ship to another verified address on file with the merchant- SHIP_TO_NON_BILLING_ADDRESS : Ship to an address that is different than the billing address- SHIP_TO_STORE : Ship to and then pick up at the merchant’s store (shipping address field will indicate store’s address)- DIGITAL_GOODS : Digital goods including online services, electronic gift cards, and redemption codes- TRAVEL_AND_EVENT_TICKETS : Travel and event tickets that are not shipped (e.g., pick up at event venue)- OTHER : Other shipping method including gaming purchases, digital services that are not shipped, digital media purchases, etc.- PICK_UP_AND_GO_DELIVERY : Pick-up goods and services- LOCKER_DELIVERY : Locker delivery or other automated pick-ups |
transaction (object) | Object containing data about the e-commerce transaction for which the merchant is requesting authentication. Note that this object will be set to null for non-payment authentications (see message_category field). |
transaction.amount | Amount of the purchase in minor units of currency with all punctuation removed. Maps to EMV 3DS field purchaseAmount .For payment authentications (see message_category field), always present. For non-payment authentications, conditionally present if authentication_request_type is one of: RECURRING_TRANSACTION , INSTALLMENT_TRANSACTION , BILLING_AGREEMENT , SPLIT_SHIPMENT , DELAYED_SHIPMENT . Integer. Permitted values: Max 48-character integer (e.g., 12345 for USD $123.45 purchase). |
transaction.currency | Currency of the purchase. Maps to EMV 3DS field purchaseCurrency .For payment authentications (see message_category field), always present. For non-payment authentications, conditionally present if authentication_request_type is one of: RECURRING_TRANSACTION , INSTALLMENT_TRANSACTION , BILLING_AGREEMENT , SPLIT_SHIPMENT , DELAYED_SHIPMENT . String. Permitted values: ISO 4217 three-character currency code (e.g., USD). |
transaction.currency_exponent | Minor units of currency, as specified in ISO 4217 currency exponent. Maps to EMV 3DS field purchaseExponent .For payment authentications (see message_category field), always present. For non-payment authentications, conditionally present if authentication_request_type is one of: RECURRING_TRANSACTION , INSTALLMENT_TRANSACTION , BILLING_AGREEMENT , SPLIT_SHIPMENT , DELAYED_SHIPMENT . Integer. Permitted values: Single-digit integer (e.g., 2 for USD since it is a 2-decimal currency). |
transaction.date_time | Date and time when the authentication was generated by the merchant/acquirer's 3DS server. Maps to EMV 3DS field purchaseDate .For payment authentications (see message_category field), always present. For non-payment authentications, conditionally present if authentication_request_type is one of: RECURRING_TRANSACTION , INSTALLMENT_TRANSACTION , BILLING_AGREEMENT , SPLIT_SHIPMENT , DELAYED_SHIPMENT . String. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd’T’hh:mm:ssZ. |
transaction.type | Type of the transaction for which a 3DS authentication request is occurring. Maps to EMV 3DS field transType .Always present in certain markets and optionally present in others. String. Permitted values: - GOODS_SERVICE_PURCHASE - CHECK_ACCEPTANCE - ACCOUNT_FUNDING - QUASI_CASH_TRANSACTION - PREPAID_ACTIVATION_AND_LOAD |
additional_data (object) | 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). Note that this object will be set to null for non-payment authentications (see message_category field). |
additional_data.network_risk_score | Mastercard only: Assessment by the network of the authentication risk level, with a higher value indicating a higher amount of risk. Integer. Permitted values: Integer between 0-950, in increments of 50. |
additional_data.network_decision | Mastercard only: Indicates whether the network would have considered the authentication request to be low risk or not. String. Permitted values: - LOW_RISK - NOT_LOW_RISK |
Retrieve 3DS Authentication Objects
In addition to having three_ds_authentication.created
webhooks sent via the Events API in real-time as they are created, 3DS authentication objects can be retrieved via the Get 3DS Authentication endpoint at any time.
Updated 3 months ago