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, dataSee 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, sdkSee the requester object for additional details. |
| server object Optional | Server details. Allowable Values: reference_number, operator_idSee 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_agentSee the client_browser object for additional details. |
| device object Optional | Device details. Allowable Values: channel, additional_dataSee 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_addressSee 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_urlSee 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, recurringSee 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_indicatorsSee the card_acceptor object for additional details. |
| whitelist object Optional | Details regarding the allow list. Allowable Values: status, sourceSee 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 |