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. |
token | Globally unique identifier for the 3DS authentication. |
created | Date and time when the authentication was created in Lithic’s system. |
card_token | Globally unique identifier for the card on which the 3DS authentication has occurred. |
card_expiry_check | Indicates whether the expiration date provided by the cardholder during checkout matches Lithic’s record of the card’s expiration date. |
channel | Channel in which the authentication occurs. Maps to EMV 3DS field
|
decision_made_by | Entity that made the authentication decision.
|
account_type | Type of account/card that is being used for the transaction. Maps to EMV 3DS field
|
authentication_result | Indicates what the outcome of the 3DS authentication process is.
|
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
|
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
|
message_category | Indicates the category of the 3DS message. Maps to EMV 3DS field
|
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
|
cardholder.name | Name of the cardholder. Maps to EMV 3DS field |
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 |
cardholder.phone_number_home | Home phone number provided by the cardholder. Maps to EMV 3DS fields |
cardholder.phone_number_mobile | Mobile/cell phone number provided by the cardholder. Maps to EMV 3DS fields |
cardholder.phone_number_work | Work phone number provided by the cardholder. Maps to EMV 3DS fields |
cardholder.billing_address (object) | Object containing data on the billing address provided during the transaction. |
cardholder.billing_address. | First line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address. | Second line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address. | Third line of the street address of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address.city | City of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address.country | Country of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address. | Postal code (e.g., ZIP code) of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.billing_address. | State or province of the billing address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address (object) | Object containing data on the shipping address provided during the transaction. |
cardholder.shipping_address. | First line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address. | Second line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address. | Third line of the street address of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address.city | City of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address. | Country of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address. | Postal code (e.g., ZIP code) of the shipping address provided by the cardholder. Maps to EMV 3DS field |
cardholder.shipping_address. | State or province of the billing address provided by the cardholder. Maps to EMV 3DS field |
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.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 |
browser.java_enabled | Indicates whether the cardholder's browser has the ability to execute Java. Maps to EMV 3DS field
|
browser.javascript_enabled | Indicates whether the cardholder's browser has the ability to execute JavaScript. Maps to EMV 3DS field
|
browser.language | Language of the cardholder’s browser as defined in IETF BCP47. Maps to EMV 3DS field |
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 |
browser.user_agent | Content of the HTTP user-agent header. Maps to EMV 3DS field |
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 |
app.device_info | Device information gathered from the cardholder’s device - JSON name/value pairs that is Base64url encoded. Maps to EMV 3DS field |
app.ip | External IP address used by the app generating the 3DS authentication request. Maps to EMV 3DS field |
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 |
merchant.id | Merchant identifier as assigned by the acquirer. Maps to EMV 3DS field |
merchant.mcc | Merchant category code assigned to the merchant that describes its business activity type. Maps to EMV 3DS field |
merchant.name | Name of the merchant. Maps to EMV 3DS field |
merchant.risk_indicator (object) | Object containing additional data indicating additional risk factors related to the e-commerce transaction. |
merchant.risk_indicator. | In transactions with electronic delivery, email address to which merchandise is delivered. Maps to EMV 3DS field |
merchant.risk_indicator. | The delivery time frame for the merchandise. Maps to EMV 3DS field
|
merchant.risk_indicator. | 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 |
merchant.risk_indicator. | In prepaid or gift card purchase transactions, count of individual prepaid or gift cards/codes purchased. Maps to EMV 3DS field |
merchant.risk_indicator. | In prepaid or gift card purchase transactions, currency code of the gift card. Maps to EMV 3DS field |
merchant.risk_indicator. | Indicates whether the purchase is for merchandise that is available now or at a future date. Maps to EMV 3DS field
|
merchant.risk_indicator. | In pre-order purchase transactions, the expected date that the merchandise will be available. Maps to EMV 3DS field |
merchant.risk_indicator. | Indicates whether the cardholder is reordering previously purchased merchandise. Maps to EMV 3DS field
|
merchant.risk_indicator. | 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
|
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 |
transaction.amount | Amount of the purchase in minor units of currency with all punctuation removed. Maps to EMV 3DS field |
transaction.currency | Currency of the purchase. Maps to EMV 3DS field |
transaction.currency_exponent | Minor units of currency, as specified in ISO 4217 currency exponent. Maps to EMV 3DS field |
transaction.date_time | Date and time when the authentication was generated by the merchant/acquirer's 3DS server. Maps to EMV 3DS field |
transaction.type | Type of the transaction for which a 3DS authentication request is occurring. Maps to EMV 3DS field
|
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 |
additional_data.network_risk_score |
|
additional_data.network_decision |
|
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 about 2 months ago