3D Secure

The Three-Domain Secure (3D Secure or 3DS) API provides a decision service that accepts scoring events from the Marqeta platform and evaluates whether to apply strong customer authentication (SCA) with 3DS or to exempt. This implementation is based on the EMV 3-D Secure Protocol and Core Functions Specification. For more information, see the specification on the EMVCo website. The 3DS API is RESTful, so it uses HTTP methods (POST, PUT, GET) to perform functions on objects. For example, to determine whether to send an SCA challenge, send a POST request to the /three-ds/decision endpoint. Some requests include data in their message body. The 3DS API requires that data be in JSON format. The 3DS API provides endpoints that enable you to:

Delegate decisioning – determine whether to send an SCA.
Notify a 3DS completion status.
Receive an Advanced Authentication challenge.
Update an authentication result to Marqeta.

For more on 3D Secure, see About 3D Secure.

Available operations

Method	Endpoint	Operation
`POST`	`/three-ds/decision`	Delegate decisioning - determine whether to send an SCA
`POST`	`/three-ds/challenge-result`	Notify a 3DS completion status
`POST`	`/three-ds/authentication`	Receive an Advanced Authentication challenge
`POST`	`/three-ds/authentication-result`	Update an authentication result to Marqeta

3D Secure webhook events

In addition to the endpoints described above, the Marqeta platform sends two webhook events to your registered webhook endpoint for every 3D Secure authentication performed on your program: threedstransition.initialization, when an authentication begins, and threedstransition.completion, when the authentication reaches its final state. The two events are delivered independently, so design your integration to tolerate receiving a completion notification without a matching initialization notification, or a notification not arriving at all. Ordering between the two events is not guaranteed, so treat the completion notification as authoritative for the authentication outcome. Correlate the two notifications for a single authentication using acs_transaction_id. For sample notification payloads, see 3D Secure transition events in Event Types.

New properties and new allowable values can be added to these objects without notice. Ignore properties you don’t recognize, and treat an unrecognized allowable value as unknown rather than rejecting the payload.

Body field details

The initialization notification object

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify this authentication. Use this value to correlate the `initialization` and `completion` notifications for the same authentication. Allowable Values: 36 char max
ds_transaction_id string Optional	Transaction identifier assigned by the Directory Server. Omitted if the Directory Server did not supply one. Allowable Values: Valid UUID
type string Required	Identifies this payload as the initialization notification. Allowable Values: `initialization`
state string Required	State of the authentication at the time this notification was generated. Always `PENDING` for the initialization notification, since the outcome isn’t yet known. Allowable Values: `PENDING`
user_token string Optional	Marqeta-assigned unique user token identifying the cardholder, where available. Allowable Values: Existing user token
acting_user_token string Optional	Marqeta-assigned unique user token identifying a party acting on the cardholder’s behalf. Included only for delegated flows. Allowable Values: Existing user token
card_token string Optional	Marqeta-assigned unique card token identifying the card being authenticated, where available. Allowable Values: Existing card token
created_time datetime Required	Date and time this notification was generated, expressed as an ISO-8601 UTC timestamp. This value is not the time the authentication began, and it differs from the `created_time` of the corresponding completion notification. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ
network string Required	Card network for the authenticated card. Allowable Values: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `PULSE`, `MARQETA`
message_version string Required	3DS protocol version used for this authentication. Allowable Values: minLength: 5 maxLength: 8
authentication_request_type string Required	Type of authentication request indicated by the 3DS Requestor. Allowable Values: `PAYMENT`, `RECURRING`, `INSTALLMENT`, `ADD_CARD`, `MAINTAIN_CARD`, `EMV_CARDHOLDER_VERIFICATION`
authentication_method string Optional	How the cardholder was verified. Omitted when no challenge took place, such as for a frictionless authentication. Allowable Values: `OTP_SMS`, `OTP_EMAIL`, `KNOWLEDGE_BASED`, `KBA_OTP_EMAIL`, `KBA_OTP_SMS`, `BIOMETRIC_FACE`, `BIOMETRIC_FINGERPRINT`, `VOICE_RECOGNITION`, `IN_APP_LOGIN`, `AUDIO_CALL`, `VIDEO_CALL`, `OTHER`
authentication_source string Optional	Destination the challenge was delivered to, such as a partially redacted phone number or email address. Omitted when no challenge took place. Allowable Values: String
device object Required	Device details for this authentication. Allowable Values: See The device object.
requester object Required	The 3DS Requestor for this authentication. Included on the initialization notification only. Allowable Values: See The requester object.
recommended_action string Optional	Authentication path selected for this transaction. On the initialization notification, this is the intended path, not the outcome. Allowable Values: `CHALLENGE_REQUIRED_OOB`, `CHALLENGE_REQUIRED`, `CHALLENGE_REQUIRED_DECOUPLED`, `FRICTIONLESS`
interaction_counter integer Required	Number of cardholder interactions during the authentication. Always `0` on the initialization notification. Allowable Values: Minimum: 0
transaction object Required	Information about how the payment is being made. Allowable Values: See The transaction object.
card_acceptor object Required	The merchant for this authentication. Allowable Values: See The card_acceptor object.
token string Required	Unique identifier for this webhook notification: the value of `acs_transaction_id` with `-00` appended. Stable across redelivery, so use it as your idempotency key. Allowable Values: Format: `{acs_transaction_id}-00`

The completion notification object

The completion notification does not carry the requester object. Use card_acceptor for merchant details, or correlate back to the initialization notification using acs_transaction_id.

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify this authentication. Use this value to correlate the `initialization` and `completion` notifications for the same authentication. Allowable Values: 36 char max
ds_transaction_id string Optional	Transaction identifier assigned by the Directory Server. Omitted if the Directory Server did not supply one. Allowable Values: Valid UUID
type string Required	Identifies this payload as the completion notification. Allowable Values: `completion`
state string Required	State of the authentication at the time this notification was generated. Always `COMPLETE` for the completion notification. Allowable Values: `COMPLETE`
user_token string Optional	Marqeta-assigned unique user token identifying the cardholder, where available. Allowable Values: Existing user token
acting_user_token string Optional	Marqeta-assigned unique user token identifying a party acting on the cardholder’s behalf. Included only for delegated flows. Allowable Values: Existing user token
card_token string Optional	Marqeta-assigned unique card token identifying the card being authenticated, where available. Allowable Values: Existing card token
created_time datetime Required	Date and time this notification was generated, expressed as an ISO-8601 UTC timestamp. This value is not the time the authentication began, and it differs from the `created_time` of the corresponding initialization notification. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ
network string Required	Card network for the authenticated card. Allowable Values: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `PULSE`, `MARQETA`
message_version string Required	3DS protocol version used for this authentication. Allowable Values: minLength: 5 maxLength: 8
authentication_request_type string Required	Type of authentication request indicated by the 3DS Requestor. Allowable Values: `PAYMENT`, `RECURRING`, `INSTALLMENT`, `ADD_CARD`, `MAINTAIN_CARD`, `EMV_CARDHOLDER_VERIFICATION`
authentication_method string Optional	How the cardholder was verified. Omitted when no challenge took place, such as for a frictionless authentication. Allowable Values: `OTP_SMS`, `OTP_EMAIL`, `KNOWLEDGE_BASED`, `KBA_OTP_EMAIL`, `KBA_OTP_SMS`, `BIOMETRIC_FACE`, `BIOMETRIC_FINGERPRINT`, `VOICE_RECOGNITION`, `IN_APP_LOGIN`, `AUDIO_CALL`, `VIDEO_CALL`, `OTHER`
authentication_source string Optional	Destination the challenge was delivered to, such as a partially redacted phone number or email address. Omitted when no challenge took place. Allowable Values: String
device object Required	Device details for this authentication. Allowable Values: See The device object.
recommended_action string Optional	Authentication path selected for this transaction. Allowable Values: `CHALLENGE_REQUIRED_OOB`, `CHALLENGE_REQUIRED`, `CHALLENGE_REQUIRED_DECOUPLED`, `FRICTIONLESS`
authentication_result string Required	Final result of the authentication. Allowable Values: `SUCCESS`, `FAILED`, `REJECTED`, `CANNOT_BE_VERIFIED`, `INFORMATIONAL`, `CHALLENGE_REQUIRED`
cardholder_authentication_verification_value string Optional	Cardholder Authentication Verification Value (CAVV). Included for Visa authentications where a value was generated. Allowable Values: 255 char max
interaction_counter integer Required	Number of cardholder interactions during the authentication. Allowable Values: Minimum: 0
transaction_reason string Optional	Reason for the authentication outcome. Omitted when no specific reason applies, which is common for approved frictionless authentications. Allowable Values: See transaction_reason allowable values.
cancel_reason string Optional	Reason the authentication was cancelled. Where no cancellation occurred, this property repeats the value of `transaction_reason`, so treat it as significant only when the two values differ. DEPRECATED: This field is still sent for backward compatibility, but its value is outdated. Allowable Values: See transaction_reason allowable values, plus the cancellation-specific values listed under cancel_reason allowable values.
transaction object Required	Information about how the payment is being made. Allowable Values: See The transaction object.
card_acceptor object Required	The merchant for this authentication. This is the only merchant detail carried on the completion notification. Allowable Values: See The card_acceptor object.
token string Required	Unique identifier for this webhook notification: the value of `acs_transaction_id` with `-01` appended. Stable across redelivery, so use it as your idempotency key. Allowable Values: Format: `{acs_transaction_id}-01`

The device object

Fields	Description
channel string Required	3DS device channel through which the authentication arrived. Allowable Values: `APP_BASED`, `BROWSER`, `THREEDS_REQUESTER_INITIATED`

The requester object

Included on the initialization notification only.

Fields	Description
name string Optional	DS-assigned 3DS Requestor name. Allowable Values: 40 char max
customer_care_url string Optional	Fully qualified URL of the 3DS Requestor website or customer care site. Allowable Values: 2048 char max
challenge_preference string Optional	Challenge preference indicated by the 3DS Requestor, where one was supplied. Allowable Values: `NO_CHALLENGE`, `CHALLENGE`, `MANDATE`, `RISK_ALREADY_ANALYZED`, `DATA_SHARE_ONLY`, `SCA_ALREADY_PERFORMED`, `WHITELIST_EXEMPT`, `WHITELIST_CHALLENGE`

The transaction object

Fields	Description
transaction_type string Required	Whether the authentication relates to a payment. Allowable Values: `PAYMENT`, `NON_PAYMENT`
sub_type string Optional	More specific transaction classification, where supplied. Allowable Values: `PURCHASE`, `ACCOUNT_VERIFICATION`, `ACCOUNT_FUNDING`, `QUASI_CASH`, `PREPAID_ACTIVATION_AND_LOAD`
amount integer Optional	Transaction amount in minor units. Apply `exponent` to obtain the decimal value. Allowable Values: A valid integer
currency_code integer Optional	ISO 4217 numeric currency code, sent as a JSON number rather than a string, so `978` rather than `"978"`. Allowable Values: A valid ISO 4217 numeric currency code. See https://www.iso.org/iso-4217-currency-codes.html
exponent integer Optional	Number of decimal places implied in `amount`. Allowable Values: A valid ISO 4217 exponent value. See https://www.iso.org/iso-4217-currency-codes.html

The card_acceptor object

Included on both notifications, and the only merchant detail carried on the completion notification.

Fields	Description
acquirer_bin string Optional	Acquiring institution identification code as assigned by the Directory Server. Allowable Values: 11 char max
merchant_id string Optional	Acquirer-assigned merchant identifier. Allowable Values: 35 char max
merchant_category_code string Optional	Code describing the merchant’s type of business. Allowable Values: 4-digit numeric string
country string Optional	Merchant country as an ISO 3166-1 numeric three-digit code. Allowable Values: 3-digit numeric code. See https://www.iso.org/iso-3166-country-codes.html
name string Optional	Merchant name as assigned by the acquirer or payment system. Allowable Values: 40 char max

transaction_reason allowable values

The following values apply to the transaction_reason field, and are also part of the allowable values for cancel_reason.

FIDO_APPROVED, FIDO_REJECTED, FIDO_WITH_ASSURANCE_SIGNED, and FIDO_DELETION are net-new values, added to support Visa Payment Passkeys.

CARD_AUTHENTICATION_FAILED - Card authentication failed
UNKNOWN_DEVICE - Device is unknown
UNSUPPORTED_DEVICE - Device is unsupported
EXCEEDS_FREQUENCY_LIMIT - Exceeds the authentication frequency limit
EXPIRED_CARD - Card is expired
INVALID_CARD_NUMBER - Card number is invalid
INVALID_TRANSACTION - Transaction is invalid
NO_CARD_RECORD - No card record was found
SECURITY_FAILURE - Security failure
STOLEN_CARD - Card is reported stolen
SUSPECTED_FRAUD - Suspected fraud
TXN_NOT_PERMITTED_TO_CARDHOLDER - Transaction not permitted to the cardholder
CARDHOLDER_NOT_ENROLLED - Cardholder is not enrolled in the service
TRANSACTION_TIMEDOUT - Transaction timed out at the ACS
LOW_CONFIDENCE - Low confidence in the authentication
MEDIUM_CONFIDENCE - Medium confidence in the authentication
HIGH_CONFIDENCE - High confidence in the authentication
VERY_HIGH_CONFIDENCE - Very high confidence in the authentication
EXCEEDS_MAX_CHALLENGES - Exceeds the ACS maximum number of challenges
EXCEEDS_MAX_CHALLENGES_FOR_KBA - Exceeds the ACS maximum number of challenges for knowledge-based authentication
NON_PAYMENT_TRANSACTION_NOT_SUPPORTED - Non-payment transaction is not supported
THREE_RI_NOT_SUPPORTED - 3RI transaction is not supported
ACS_TECHNICAL_ISSUES - ACS technical issue
DECOUPLED_AUTHENTICATION_NOT_REQUESTED - Decoupled authentication is required by the ACS but was not requested by the 3DS Requestor
DECOUPLED_AUTHENTICATION_TIMED_OUT - 3DS Requestor decoupled maximum expiry time was exceeded
AUTHENTICATION_NOT_ATTEMPTED - Authentication was attempted but not performed by the cardholder
THREEDS_REQUESTOR_TRA_EXEMPTION - Transaction risk analysis was already performed
THREEDS_REQUESTOR_SCA_EXEMPTION - Strong customer authentication was already performed
THREEDS_REQUESTOR_DATA_SHARE_EXEMPTION - Data share only
CORPORATE_PAYMENT_EXEMPTION - Corporate payment exemption
MERCHANT_INITIATED_TRANSACTION_PAYMENT_EXEMPTION - Merchant-initiated transaction payment exemption
LOW_VALUE_PAYMENT - Low value payment
ISSUER_SCA_REQUIRED - Issuer requires strong customer authentication
NETWORK_SUSPECTED_BIN_ATTACK - Card network suspects a BIN attack
NPA_FRICTIONLESS - Non-payment authentication completed frictionless
PROGRAM_NOT_ENROLLED_V220 - Program is not enrolled for 3DS version 2.2.0
FIDO_APPROVED - Passkey registration approved following a successful challenge
FIDO_REJECTED - Passkey registration declined following a successful challenge
FIDO_WITH_ASSURANCE_SIGNED - Passkey transaction with assurance signed
FIDO_DELETION - Authentication completed frictionless because the request was to delete a passkey

cancel_reason allowable values

cancel_reason is deprecated. The Marqeta platform continues to send this field for backward compatibility, but its value is outdated.

In addition to the transaction_reason allowable values, cancel_reason accepts the following cancellation-specific values:

CARDHOLDER_CANCEL - Challenge was cancelled by the cardholder
CHALLENGE_CANCELLED_BY_TRANSACTION_ERROR - Challenge was cancelled due to a transaction error
TIMED_OUT_AT_ACS - Transaction timed out at the ACS; the intermediate CReq was not received by the ACS
TIMED_OUT_AT_ACS_NO_CREQ - Transaction timed out at the ACS; the first CReq was not received by the ACS
TIMED_OUT_AT_SDK - Transaction timed out at the SDK
TIMED_OUT_DECOUPLED_AUTHENTICATION - Transaction timed out during decoupled authentication
TIMED_OUT_OOB_AUTHENTICATION - Transaction timed out during out-of-band (OOB) authentication
UNKNOWN - Reason is unknown

Getting Started

Testing

Card Issuing

Card Processing

Accounts & Money Movement

Risk, Fraud, and Disputes

Cardholder User Experience

3D Secure Overview

Available operations

3D Secure webhook events

Body field details

The initialization notification object

The completion notification object

The device object

The requester object

The transaction object

The card_acceptor object

transaction_reason allowable values

cancel_reason allowable values

​Available operations

​3D Secure webhook events

​Body field details

​The initialization notification object

​The completion notification object

​The device object

​The requester object

​The transaction object

​The card_acceptor object

​transaction_reason allowable values

​cancel_reason allowable values

Available operations

3D Secure webhook events

Body field details

The initialization notification object

The completion notification object

The device object

The requester object

The transaction object

The card_acceptor object

transaction_reason allowable values

cancel_reason allowable values