3D Secure Risk Engine Schema

This page contains the available objects and fields that Marqeta’s Three Domain Secure (3D Secure) Risk Engine provides to card programs for writing 3D Secure decisioning rules.

About the 3D Secure Risk Engine

Marqeta’s 3D Secure Risk Engine allows card programs to perform 3D Secure decisioning within Marqeta’s real-time decisioning product. Previously, Marqeta supported Delegated Decisioning for 3D Secure decisioning, in which Marqeta would send a request containing details of a flagged transaction to a card program’s endpoint. The card program would then return a response indicating whether to challenge the transaction with Strong Customer Authentication (SCA) or pass the transaction without a challenge. Marqeta’s new 3D Secure Risk Engine integrates the decisioning workflow into the real-time decisioning product, and uses the same decisioning platform for writing risk rules. The payload previously sent via Delegated Decisioning is now available within the rules engine, allowing you to use a dashboard to write 3D Secure decisioning rules. The following sections detail the event types associated with Marqeta’s 3D Secure Risk Engine.

THREE_DS_DECISION_RT

THREE_DS_DECISION_RT is a real-time 3D Secure decisioning event used to decide whether or not a 3D Secure transaction should be challenged. Use the following actions in the dashboard to trigger an SCA challenge or to exempt the transaction from the challenge flow:

THREE_DS_AUTHENTICATION_CHALLENGE - Go to the Create Rules > Specify Action dropdown and select this action to trigger an SCA challenge.
THREE_DS_AUTHENTICATION_EXEMPT - Go to the Create Rules > Specify Action dropdown and select this action if you prefer to allow for frictionless provisioning and do not want to trigger an SCA challenge.

The THREE_DS_DECISION_RT schema

Fields	Description
acs_transaction_id string Required	Universally unique identifier assigned to a single transaction by the access control server (ACS). Allowable Values: 36 char max
type string Optional	Authentication type that determines which action the recipient of the message must take. Allowable Values: `authentication.decision`
state string Required	Status of the requested authentication. Allowable Values: - `PENDING` - Authentication request is pending processing - `SUCCESS` - Authentication completed successfully - `FAILED` - Authentication failed or was rejected
user_token string Optional	Marqeta-assigned unique identifier of the user. Allowable Values: 36 char max
acting_user_token string Optional	Marqeta-assigned unique identifier of the user performing the transaction. Allowable Values: 36 char max
card_token string Required	Marqeta-assigned unique identifier of the card used in the transaction. Allowable Values: 36 char max
created_time string Required	Authentication request time and date, in UTC, using ISO-8601 format. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ
network string Optional	Card network associated with the authentication/decision request. Allowable Values: - `VISA` - `MASTERCARD`
message_version string Optional	Version of the 3D Secure protocol used by the 3D Secure requester. Allowable Values: minLength: 5 maxLength: 8
message_extension object Optional	3DS message extension component. Allowable Values: `name`, `id`, `criticality_indicator`, `data` See the message_extension object for additional details.
authentication_request_type string Optional	Indicates the type of authentication request. Allowable Values: - `PAYMENT` - Payment transaction authentication - `RECURRING` - Recurring payment setup or processing - `INSTALLMENT` - Installment payment authentication - `ADD_CARD` - Adding a new card to cardholder account - `MAINTAIN_CARD` - Maintaining or updating existing card information - `EMV_CARDHOLDER_VERIFICATION` - EMV cardholder verification method
requester object Optional	Requester details. Allowable Values: `notification_url`, `challenge_preference`, `decoupled_challenge_preference`, `name`, `customer_care_url`, `request_type`, `cardholder_authentication_by_merchant`, `prior_cardholder_authentication`, `sdk` See the requester object for additional details.
server object Optional	Server details. Allowable Values: `reference_number`, `operator_id` See the server object for additional details.
client_browser object Optional	Client browser details. Allowable Values: `accept_headers`, `ip_address`, `is_java_enabled`, `is_javascript_enabled`, `language`, `timezone_offset_in_minutes`, `user_agent` See the client_browser object for additional details.
device object Optional	Device details. Allowable Values: `channel`, `additional_data` See the device object for additional details.
cardholder_account object Optional	Contains additional information about the cardholder’s account, as provided by the 3D Secure requester. Allowable Values: `identifier`, `name`, `email`, `account_type`, `card_expiry_date`, `account_age`, `last_updated_date`, `last_updated_duration`, `date_created`, `password_changed_date`, `password_changed_duration`, `enrolled_date`, `enrolled_duration`, `shipping_address_first_used_date`, `shipping_address_first_used_duration`, `ship_to_name_is_cardholder_name`, `experienced_suspicious_activity`, `phones`, `statistics`, `billing_address`, `shipping_address` See the cardholder_account object for additional details.
directory_server object Optional	Describes information from the Directory Server (DS) in the network. Allowable Values: `reference_number`, `authentication_result_url` See the directory_server object for additional details.
transaction object Optional	Contains information about how the payment is being made. Allowable Values: `transaction_type`, `sub_type`, `amount`, `currency_code`, `exponent`, `date`, `shipping_address_is_billing_address`, `maximum_permitted_installments`, `detokenisation_source`, `recurring` See the transaction object for additional details.
card_acceptor object Required	Details about the merchant with which this transaction is being conducted. Allowable Values: `acquirer_bin`, `merchant_id`, `merchant_category_code`, `country`, `name`, `risk_indicators` See the card_acceptor object for additional details.
whitelist object Optional	Details regarding the allow list. Allowable Values: `status`, `source` See the allowlist object (also called the whitelist object) for additional details.

THREE_DS_CHALLENGE_RESULT

THREE_DS_CHALLENGE_RESULT is an asynchronous 3D Secure event that informs you about whether the SCA challenge was completed successfully or not. You can use this event to build features that will update the authentication result status, which can then be used in 3D Secure decisioning rules.

The THREE_DS_CHALLENGE_RESULT Schema

Fields	Description
acs_transaction_id string Required	Universally unique identifier assigned to a single transaction by the access control server (ACS). Allowable Values: 36 char max
type string Optional	Authentication type that determines which action the recipient of the message must take. Allowable Values: `authentication.result`
state string Optional	Status of the requested authentication. Allowable Values: - `PENDING` - Authentication request is pending processing - `SUCCESS` - Authentication completed successfully - `FAILED` - Authentication failed or was rejected
card_token string Optional	Marqeta-assigned unique card token identifying the card being used. Allowable Values: 36 char max
user_token string Optional	Marqeta-assigned unique identifier of the user. Allowable Values: 36 char max
acting_user_token string Optional	Marqeta-assigned unique identifier of the user performing the transaction. Allowable Values: 36 char max
authentication_method string Optional	Method used to authenticate the cardholder. Allowable Values: - `BIOMETRIC_FACE` - Facial recognition authentication - `BIOMETRIC_FINGERPRINT` - Fingerprint authentication - `VOICE_RECOGNITION` - Voice pattern recognition authentication - `IN_APP_LOGIN` - Authentication within the issuer’s mobile application - `AUDIO_CALL` - Voice call with human or automated verification - `VIDEO_CALL` - Video call with human verification - `OTP_SMS` - One-time password sent via SMS text message - `OTP_EMAIL` - One-time password sent via email - `KNOWLEDGE_BASED` - Knowledge-based authentication, such as security questions - `OTHER` - Other authentication method not listed above
authentication_result string Optional	Result of the authentication performed. Allowable Values: - `SUCCESS` - Authentication was successful and the cardholder was verified - `FAILED` - Authentication failed due to incorrect credentials or verification - `CANCELLED` - Authentication was cancelled by cardholder or system timeout - `NOT_AUTHENTICATED` - Authentication could not be performed or completed
interaction_counter integer Optional	Indicates the number of authentication cycles attempted by the cardholder. Value to be tracked by the ACS. Allowable Values: As provided by the ACS Default Value: 1
cancel_reason string Optional	Indicates to the ACS and the DS that the authentication has been canceled. Allowable Values: - `CARDHOLDER_CANCEL` - Cardholder explicitly cancelled the authentication - `CHALLENGE_CANCELLED_BY_TRANSACTION_ERROR` - Challenge cancelled due to transaction error - `TIMED_OUT_AT_ACS` - ACS timed out during challenge processing - `TIMED_OUT_AT_ACS_NO_CREQ` - ACS timed out before receiving challenge request - `TIMED_OUT_AT_SDK` - 3DS SDK timed out during authentication - `TIMED_OUT_DECOUPLED_AUTHENTICATION` - Decoupled authentication timed out waiting for cardholder response - `TIMED_OUT_OOB_AUTHENTICATION` - OOB authentication timed out waiting for response - `UNKNOWN` - Cancellation reason could not be determined

​About the 3D Secure Risk Engine

​THREE_DS_DECISION_RT

​The THREE_DS_DECISION_RT schema

​THREE_DS_CHALLENGE_RESULT

​The THREE_DS_CHALLENGE_RESULT Schema

About the 3D Secure Risk Engine

THREE_DS_DECISION_RT

The THREE_DS_DECISION_RT schema

THREE_DS_CHALLENGE_RESULT

The THREE_DS_CHALLENGE_RESULT Schema