Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
3DS

3DS Decisioning Request

Webhook for Card Programs to decision on 3DS Authentication Request. See https://docs.lithic.com/docs/3ds-decisioning for more details.

postWebhookthree_ds_authentication.approval_request

Payload

event_type'three_ds_authentication.approval_request' required
account_type'CREDIT' | 'DEBIT' | 'NOT_APPLICABLE' | 'null' nullable required

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

authentication_request_type'ADD_CARD' | 'BILLING_AGREEMENT' | 'DELAYED_SHIPMENT' | 'EMV_TOKEN_CARDHOLDER_VERIFICATION' | 'INSTALLMENT_TRANSACTION' | 'MAINTAIN_CARD' | 'PAYMENT_TRANSACTION' | 'RECURRING_TRANSACTION' | 'SPLIT_PAYMENT' | 'SPLIT_SHIPMENT' | 'null' nullable

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.

authentication_result'DECLINE' | 'SUCCESS' | 'PENDING_CHALLENGE' | 'PENDING_DECISION' required

Indicates the outcome of the 3DS authentication process.

card_expiry_check'MATCH' | 'MISMATCH' | 'NOT_PRESENT' required

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

card_tokenstring uuid required

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

challenge_orchestrated_by'LITHIC' | 'CUSTOMER' | 'NO_CHALLENGE' | 'null' nullable

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

channel'APP_BASED' | 'BROWSER' | 'THREE_DS_REQUESTOR_INITIATED' required

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

createdstring 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'LITHIC_RULES' | 'LITHIC_DEFAULT' | 'CUSTOMER_RULES' | 'CUSTOMER_ENDPOINT' | 'NETWORK' | 'UNKNOWN' | 'null' nullable

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

message_category'NON_PAYMENT_AUTHENTICATION' | 'PAYMENT_AUTHENTICATION' required

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

three_ds_requestor_challenge_indicator'NO_PREFERENCE' | 'NO_CHALLENGE_REQUESTED' | 'CHALLENGE_PREFERENCE' | 'CHALLENGE_MANDATE' | 'NO_CHALLENGE_RISK_ALREADY_ASSESSED' | 'DATA_SHARE_ONLY' | 'OTHER' 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
three_ri_request_type'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' nullable

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.

tokenstring uuid required

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

Example payload

{
  "event_type": "three_ds_authentication.approval_request"
}

Response

Information on whether the Request was Approved/Declined and if a Challenge should be created.

three_ds_authentication_decision'APPROVE' | 'DECLINE' | 'CHALLENGE_REQUESTED' required
  • APPROVE - Approve the 3DS Transaction and proceed to Authorization
  • DECLINE - Decline the 3DS Transaction ending the transaction
  • CHALLENGE_REQUESTED - Conditional Approval for the 3DS Transaction where a follow-up Challenge will be triggered to further authenticate the Cardholder
oob_urlstring

URL which may be used in the presentation of a 3DS Challenge UI to the cardholder. This value will be used by the ACS as the OOB App URL. When applicable, this URL may be used for automatic app switching or rendered directly as an element in the Challenge UI. This field is only used with CHALLENGE_REQUESTED decision and when customer orchestrates the 3DS challenge on their own.