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_REQUESTOR_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.