{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/authentication", "title": "3DS Authentication object", "type": "object", "description": "Represents a 3DS authentication", "properties": { "account_type": { "type": [ "string", "null" ], "description": "Type of account/card that is being used for the transaction. Maps to EMV 3DS field `acctType`.", "enum": [ "CREDIT", "DEBIT", "NOT_APPLICABLE", null ] }, "additional_data": { "type": [ "object", "null" ], "description": "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).", "properties": { "network_decision": { "type": [ "string", "null" ], "description": "Mastercard only: Indicates whether the network would have considered the authentication request to be low risk or not.", "enum": [ "LOW_RISK", "NOT_LOW_RISK", null ] }, "network_risk_score": { "type": [ "integer", "null" ], "description": "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." } }, "required": [] }, "app": { "type": [ "object", "null" ], "description": "Object containing data about the app used in the e-commerce transaction. Present if the channel is 'APP_BASED'.", "properties": { "device_info": { "type": [ "string", "null" ], "description": "Raw device information - base64-encoded JSON object. Maps to EMV 3DS field `deviceInfo`." }, "ip": { "type": "string", "description": "IP address of the device.", "x-stainless-naming": { "go": { "property_name": "Ip" } } }, "platform": { "type": [ "string", "null" ], "description": "Device platform: Android, iOS, Windows, etc." }, "device": { "type": [ "string", "null" ], "description": "Device model: e.g. \"Apple iPhone 16\"." }, "os": { "type": [ "string", "null" ], "description": "Operating System: e.g. \"Android 12\", \"iOS 17.1\"." }, "locale": { "type": [ "string", "null" ], "description": "Device locale: e.g. \"en-US\"." }, "time_zone": { "type": [ "string", "null" ], "description": "Time zone offset in minutes between UTC and device local time." }, "screen_width": { "type": [ "integer", "null" ], "description": "Screen width in pixels." }, "screen_height": { "type": [ "integer", "null" ], "description": "Screen height in pixels." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude coordinate of current device location.", "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "description": "Longitude coordinate of current device location.", "minimum": -180, "maximum": 180 } }, "required": [] }, "authentication_request_type": { "type": [ "string", "null" ], "description": "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`.", "enum": [ "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": { "type": [ "string" ], "description": "Indicates the outcome of the 3DS authentication process.", "enum": [ "DECLINE", "SUCCESS", "PENDING_CHALLENGE", "PENDING_DECISION" ] }, "browser": { "type": [ "object", "null" ], "description": "Object containing data about the browser used in the e-commerce transaction. Present if the channel is 'BROWSER'.", "properties": { "accept_header": { "type": [ "string", "null" ], "description": "Content of the HTTP accept headers as sent from the cardholder's browser to the 3DS requestor (e.g., merchant or digital wallet)." }, "ip": { "description": "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`.", "type": "string", "nullable": true, "x-stainless-naming": { "go": { "property_name": "Ip" } } }, "java_enabled": { "type": [ "boolean", "null" ], "description": "Indicates whether the cardholder's browser has the ability to execute Java. Maps to EMV 3DS field `browserJavaEnabled`." }, "javascript_enabled": { "type": [ "boolean", "null" ], "description": "Indicates whether the cardholder's browser has the ability to execute JavaScript. Maps to EMV 3DS field `browserJavascriptEnabled`." }, "language": { "type": [ "string", "null" ], "description": "Language of the cardholder's browser as defined in IETF BCP47. Maps to EMV 3DS field `browserLanguage`." }, "time_zone": { "type": [ "string", "null" ], "description": "Time zone offset in minutes between UTC and browser local time. Maps to EMV 3DS field `browserTz`." }, "user_agent": { "type": [ "string", "null" ], "description": "Content of the HTTP user-agent header. Maps to EMV 3DS field `browserUserAgent`." } }, "required": [] }, "card_expiry_check": { "type": "string", "description": "Indicates whether the expiration date provided by the cardholder during checkout matches Lithic's record of the card's expiration date.", "enum": [ "MATCH", "MISMATCH", "NOT_PRESENT" ] }, "card_token": { "type": "string", "description": "Globally unique identifier for the card on which the 3DS authentication has occurred. Permitted values: 36-digit version 4 UUID (including hyphens).", "format": "uuid" }, "cardholder": { "type": "object", "description": "Object containing data about the cardholder provided during the transaction.", "properties": { "address_match": { "type": [ "boolean", "null" ], "description": "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": { "$ref": "#/components/schemas/address_match_result" }, "billing_address": { "type": "object", "description": "Object containing data on the billing address provided during the transaction.", "properties": { "address1": { "type": [ "string", "null" ], "description": "First line of the street address provided by the cardholder." }, "address2": { "type": [ "string", "null" ], "description": "Second line of the street address provided by the cardholder." }, "address3": { "type": [ "string", "null" ], "description": "Third line of the street address provided by the cardholder." }, "city": { "type": [ "string", "null" ], "description": "City of the address provided by the cardholder." }, "country": { "type": [ "string", "null" ], "description": "Country of the address provided by the cardholder in ISO 3166-1 alpha-3 format (e.g. USA)", "minLength": 3, "maxLength": 3 }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code (e.g., ZIP code) of the address provided by the cardholder" } } }, "email": { "type": [ "string", "null" ], "description": "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`.", "maxLength": 254, "minLength": 1 }, "name": { "type": [ "string", "null" ], "description": "Name of the cardholder. Maps to EMV 3DS field `cardholderName`.", "maxLength": 45, "minLength": 1 }, "phone_number_home": { "type": [ "string", "null" ], "description": "Home phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `homePhone.cc` and `homePhone.subscriber`.", "maxLength": 16, "minLength": 1 }, "phone_number_mobile": { "type": [ "string", "null" ], "description": "Mobile/cell phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `mobilePhone.cc` and `mobilePhone.subscriber`.", "maxLength": 16, "minLength": 1 }, "phone_number_work": { "type": [ "string", "null" ], "description": "Work phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `workPhone.cc` and `workPhone.subscriber`.", "maxLength": 16, "minLength": 1 }, "shipping_address": { "type": "object", "description": "Object containing data on the shipping address provided during the transaction.", "properties": { "address1": { "type": [ "string", "null" ], "description": "First line of the street address provided by the cardholder." }, "address2": { "type": [ "string", "null" ], "description": "Second line of the street address provided by the cardholder." }, "address3": { "type": [ "string", "null" ], "description": "Third line of the street address provided by the cardholder." }, "city": { "type": [ "string", "null" ], "description": "City of the address provided by the cardholder." }, "country": { "type": [ "string", "null" ], "description": "Country of the address provided by the cardholder in ISO 3166-1 alpha-3 format (e.g. USA)", "minLength": 3, "maxLength": 3 }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code (e.g., ZIP code) of the address provided by the cardholder" } } } }, "required": [] }, "challenge_metadata": { "type": [ "object", "null" ], "description": "Metadata about the challenge method and delivery. Only present when a challenge is triggered.", "properties": { "method_type": { "type": "string", "enum": [ "SMS_OTP", "OUT_OF_BAND" ], "description": "The type of challenge method used for authentication." }, "phone_number": { "type": [ "string", "null" ], "description": "The phone number used for delivering the OTP. Relevant only for SMS_OTP method." }, "status": { "type": "string", "enum": [ "SUCCESS", "PENDING", "SMS_DELIVERY_FAILED", "CARDHOLDER_TIMEOUT", "CANCELED_VIA_CHALLENGE_UI", "CANCELED_OOB", "ATTEMPTS_EXCEEDED", "ABORTED", "ERROR" ], "description": "Indicates the status of the challenge\n\n* SUCCESS - Cardholder completed the challenge successfully\n* PENDING - Challenge was issued to the cardholder and was not completed yet\n* SMS_DELIVERY_FAILED - Lithic confirmed undeliverability of the SMS to the provided phone number. Relevant only for SMS_OTP method\n* CARDHOLDER_TIMEOUT - Cardholder failed to complete the challenge within the given challenge TTL\n* CANCELED_VIA_CHALLENGE_UI - Cardholder canceled the challenge by selecting \"cancel\" on the challenge UI\n* CANCELED_OOB - Cardholder canceled the challenge out of band\n* 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\n* ABORTED - Merchant aborted authentication after a challenge was requested\n* ERROR - The challenge failed for a reason different than those documented" } }, "required": [ "method_type", "status" ] }, "challenge_orchestrated_by": { "type": [ "string", "null" ], "description": "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).", "enum": [ "LITHIC", "CUSTOMER", "NO_CHALLENGE", null ] }, "channel": { "type": "string", "description": "Channel in which the authentication occurs. Maps to EMV 3DS field `deviceChannel`.", "enum": [ "APP_BASED", "BROWSER", "THREE_DS_REQUESTOR_INITIATED" ] }, "created": { "type": "string", "description": "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.", "format": "date-time" }, "decision_made_by": { "type": [ "string", "null" ], "description": "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).", "enum": [ "LITHIC_RULES", "LITHIC_DEFAULT", "CUSTOMER_RULES", "CUSTOMER_ENDPOINT", "NETWORK", "UNKNOWN", null ] }, "merchant": { "type": "object", "description": "Object containing data about the merchant involved in the e-commerce transaction.", "properties": { "country": { "type": [ "string", "null" ], "description": "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.", "minLength": 3, "maxLength": 3 }, "id": { "type": [ "string", "null" ], "description": "Merchant identifier as assigned by the acquirer. Maps to EMV 3DS field `acquirerMerchantId`. May not be present for non-payment authentications." }, "mcc": { "type": [ "string", "null" ], "description": "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.", "minLength": 4, "maxLength": 4 }, "name": { "type": [ "string", "null" ], "description": "Name of the merchant. Maps to EMV 3DS field `merchantName`. May not be present for non-payment authentications." }, "risk_indicator": { "type": "object", "description": "Object containing additional data indicating additional risk factors related to the e-commerce transaction.", "properties": { "delivery_email_address": { "type": [ "string", "null" ], "description": "In transactions with electronic delivery, email address to which merchandise is delivered. Maps to EMV 3DS field `deliveryEmailAddress`." }, "delivery_time_frame": { "type": [ "string", "null" ], "description": "The delivery time frame for the merchandise. Maps to EMV 3DS field `deliveryTimeframe`.", "enum": [ "ELECTRONIC_DELIVERY", "OVERNIGHT_SHIPPING", "SAME_DAY_SHIPPING", "TWO_DAY_OR_MORE_SHIPPING", null ] }, "gift_card_amount": { "type": [ "integer", "null" ], "description": "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`." }, "gift_card_count": { "type": [ "integer", "null" ], "description": "In prepaid or gift card purchase transactions, count of individual prepaid or gift cards/codes purchased. Maps to EMV 3DS field `giftCardCount`." }, "gift_card_currency": { "type": [ "string", "null" ], "description": "In prepaid or gift card purchase transactions, currency code of the gift card. Maps to EMV 3DS field `giftCardCurr`. Permitted values: ISO 4217 three-character currency code (e.g., USD).", "minLength": 3, "maxLength": 3 }, "order_availability": { "type": [ "string", "null" ], "description": "Indicates whether the purchase is for merchandise that is available now or at a future date. Maps to EMV 3DS field `preOrderPurchaseInd`.", "enum": [ "FUTURE_AVAILABILITY", "MERCHANDISE_AVAILABLE", null ] }, "pre_order_available_date": { "type": [ "string", "null" ], "description": "In pre-order purchase transactions, the expected date that the merchandise will be available. Maps to EMV 3DS field `preOrderDate`. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd'T'hh:mm:ssZ", "format": "date-time" }, "reorder_items": { "type": [ "string", "null" ], "description": "Indicates whether the cardholder is reordering previously purchased merchandise. Maps to EMV 3DS field `reorderItemsInd`.", "enum": [ "FIRST_TIME_ORDERED", "REORDERED", null ] }, "shipping_method": { "type": [ "string", "null" ], "description": "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`.", "enum": [ "DIGITAL_GOODS", "LOCKER_DELIVERY", "OTHER", "PICK_UP_AND_GO_DELIVERY", "SHIP_TO_BILLING_ADDRESS", "SHIP_TO_NON_BILLING_ADDRESS", "SHIP_TO_OTHER_VERIFIED_ADDRESS", "SHIP_TO_STORE", "TRAVEL_AND_EVENT_TICKETS", null ] } }, "required": [] } }, "required": [ "risk_indicator" ] }, "message_category": { "type": "string", "description": "Either PAYMENT_AUTHENTICATION or NON_PAYMENT_AUTHENTICATION. For NON_PAYMENT_AUTHENTICATION, additional_data and transaction fields are not populated.", "enum": [ "NON_PAYMENT_AUTHENTICATION", "PAYMENT_AUTHENTICATION" ] }, "three_ds_requestor_challenge_indicator": { "type": "string", "description": "Indicates whether a challenge is requested for this transaction\n\n* `NO_PREFERENCE` - No Preference\n* `NO_CHALLENGE_REQUESTED` - No Challenge Requested\n* `CHALLENGE_PREFERENCE` - Challenge requested (3DS Requestor preference)\n* `CHALLENGE_MANDATE` - Challenge requested (Mandate)\n* `NO_CHALLENGE_RISK_ALREADY_ASSESSED` - No Challenge requested (Transactional risk analysis is already performed)\n* `DATA_SHARE_ONLY` - No Challenge requested (Data Share Only)\n* `OTHER` - Other indicators not captured by above. These are rarely used", "enum": [ "NO_PREFERENCE", "NO_CHALLENGE_REQUESTED", "CHALLENGE_PREFERENCE", "CHALLENGE_MANDATE", "NO_CHALLENGE_RISK_ALREADY_ASSESSED", "DATA_SHARE_ONLY", "OTHER" ] }, "three_ri_request_type": { "type": [ "string", "null" ], "description": "Type of 3DS Requestor Initiated (3RI) request \u2014 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`.", "enum": [ "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": { "type": "string", "description": "Globally unique identifier for the 3DS authentication. Permitted values: 36-digit version 4 UUID (including hyphens).", "format": "uuid" }, "transaction": { "type": [ "object", "null" ], "description": "Object containing data about the e-commerce transaction for which the merchant is requesting authentication.", "properties": { "amount": { "type": "number", "description": "Amount of the purchase in minor units of currency with all punctuation removed. Maps to EMV 3DS field `purchaseAmount`." }, "cardholder_amount": { "type": [ "number", "null" ], "description": "Approximate amount of the purchase in minor units of cardholder currency. Derived from `amount` using a daily conversion rate." }, "currency": { "type": "string", "description": "Currency of the purchase. Maps to EMV 3DS field `purchaseCurrency`. Permitted values: ISO 4217 three-character currency code (e.g., USD).", "minLength": 3, "maxLength": 3 }, "currency_exponent": { "type": "number", "description": "Minor units of currency, as specified in ISO 4217 currency exponent. Maps to EMV 3DS field `purchaseExponent`." }, "date_time": { "type": "string", "description": "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.", "format": "date-time" }, "type": { "type": [ "string", "null" ], "description": "Type of the transaction for which a 3DS authentication request is occurring. Maps to EMV 3DS field `transType`.", "enum": [ "ACCOUNT_FUNDING", "CHECK_ACCEPTANCE", "GOODS_SERVICE_PURCHASE", "PREPAID_ACTIVATION_AND_LOAD", "QUASI_CASH_TRANSACTION", null ] } }, "required": [ "amount", "cardholder_amount", "currency", "currency_exponent", "date_time", "type" ] } }, "required": [ "account_type", "authentication_result", "card_expiry_check", "card_token", "cardholder", "channel", "created", "merchant", "message_category", "three_ds_requestor_challenge_indicator", "token" ] }