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.

Delegate decisioning - determine whether to send an SCA

Action: POST
Endpoint: /three-ds/decision Evaluate whether or not the cardholder will be prompted with a strong customer authentication (SCA) challenge to complete this authentication. To participate in the delegated decision service, your system must handle messages sent by the Marqeta platform and return the appropriate response. This is the URL of the decision service endpoint hosted in your environment, to which POST messages are submitted by the Marqeta platform.

Request header

Fields	Description
X-VERSION char Optional	Identifies the version of the service and data structures used. This value is not the same as the 3DS version. If omitted, the latest version is assumed. Allowable Values: A valid version number.

Body field details

The following table describes the payload required to score an access control server (ACS) request.

The ThreeDSDecisionRequest object

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: `acsTransID`) Allowable Values: 36 char max
type string Optional	Authentication type that determines the action to be taken by the receiver of this message. 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 user token identifying the user. Allowable Values: 36 char max
acting_user_token string Optional	Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 36 char max
card_token string Required	Marqeta-assigned unique card token identifying the user. Allowable Values: 36 char max
created_time string Required	Authentication request time, expressed as an ISO-8601 UTC timestamp. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ
network string Optional	The card network associated with this authentication/decision request. Allowable Values: - `VISA` - Visa card network transactions - `MASTERCARD` - Mastercard network transactions
message_version string Optional	The 3DS protocol version used by the 3DS Requestor. (EMVCo reference: `messageversion`) Allowable Values: minLength: 5 maxLength: 8
message_extension string Optional	The 3DS message extension component. (EMVCo reference: `messageExtension`) Allowable Values: See The message_extension object.
authentication_request_type string Optional	Indicates the type of authentication request. (EMVCo reference: `threeDSRequestorAuthenticationInd`) 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 string Optional	The requestor details. Allowable Values: See The requester object.
server string Optional	The server details. Allowable Values: See The server object.
client_browser string Optional	Client browser details. Allowable Values: See The client_browser object.
device string Optional	The device details. Allowable Values: See The device object.
cardholder_account string Optional	Contains additional information about the cardholder’s account, as provided by the 3DS Requestor. Allowable Values: See The cardholder_account object.
directory_server string Optional	Describes information from the Directory Services (DS) in the network. Allowable Values: See The directory_server object.
transaction string Required	Contains information about how the payment is being made. Allowable Values: See The transaction object.
card_acceptor string Required	Details about the merchant with which this transaction is being conducted. Allowable Values: See The card_acceptor object.
whitelist string Optional	Details regarding the allow list. Allowable Values: See The whitelist object.

The message_extension object

Fields	Description
name string Required	Name of the extension dataset, as defined by the extension owner. Allowable Values: 64 char max
id string Required	A unique identifier for the extension. NOTE: Payment System Registered Application Provider Identifier (RID) is required as the prefix of the ID. Allowable Values: 64 char max
criticality_indicator boolean Required	Indicates whether the recipient must understand the contents of the extension to interpret the entire message. (EMVCo reference: `criticalityIndicator`) Allowable Values: `true`, `false`
data string Required	Data carried in the extension. Allowable Values: 8059 char max

The requester object

Fields	Description
notification_url string Optional	Fully qualified URL of the system that receives the challenge response message or error message. The challenge response message is posted by the ACS through the cardholder browser at the end of the challenge and receipt of the results response message. (EMVCo reference: `notificationURL`) Allowable Values: 256 char max Example: https://www.example.com/path/to/resource
challenge_preference string Optional	Indicates whether a challenge is requested for this transaction. If missing, presume no-preference. (EMVCo reference: `threeDSRequestorChallengeInd`) Allowable Values: - `NO_CHALLENGE` - No challenge requested - `CHALLENGE` - Challenge requested - `RISK_ALREADY_ANALYZED` - Merchant has already performed risk analysis - `DATA_SHARE_ONLY` - Data sharing only; no authentication required - `SCA_ALREADY_PERFORMED` - Strong Customer Authentication already performed - `WHITELIST_CHALLENGE` - Allow list prompt requested if cardholder not on the allow list - `WHITELIST_EXEMPT` - Allow list exemption requested - `MANDATE` - Challenge mandated by regulation or policy
decoupled_challenge_preference string Optional	Indicates whether the 3DS Requestor requests the ACS to use decoupled authentication, and agrees to use decoupled authentication if the ACS confirms its use. This only exists if a preference is expressed for how the challenge should be handled. It’s possible for there to be no preference on the challenge, but to have a preference on how decoupled challenges are conducted. (EMVCo reference: `threeDSRequestorDecReqInd`) Allowable Values: - `DECOUPLED_AUTHENTICATION_PREFERRED` - Prefer decoupled authentication method - `DO_NOT_USE_DECOUPLED_AUTHENTICATION` - Prefer not to use decoupled authentication method
name string Optional	DS-assigned 3DS Requestor name. Each DS provides a unique name to each 3DS Requestor on an individual basis. (EMVCo reference: `threeDSRequestorName`) Allowable Values: 40 char max
customer_care_url string Optional	Fully qualified URL of the 3DS Requestor website or customer care site. (EMVCo reference: `threeDSRequestorURL`) Allowable Values: 2048 char max Example: https://help.example.com/customer-service
request_type string Optional	Indicates the type of 3RI request. (EMVCo reference: `threeRIInd`) Allowable Values: - `RECURRING` - Recurring payment setup or processing - `INSTALLMENT` - Installment payment authentication - `ADD_CARD` - Add a new card to cardholder account - `MAINTAIN_CARD` - Maintain or update existing card information - `ACCOUNT_VERIFICATION` - Account verification without payment - `SPLIT_OR_DELAYED_SHIPMENT` - Split or delayed shipment transaction - `TOP_UP` - Account top-up or reload transaction - `MAIL_ORDER` - Mail order transaction - `TELEPHONE_ORDER` - Telephone order transaction - `WHITELIST_STATUS_CHECK` - Allow list status verification - `OTHER_PAYMENT` - Other payment type not specified above
cardholder_authentication_by_merchant object Optional	Cardholder authentication details by merchant. Allowable Values: See The cardholder_authentication_by_merchant object.
prior_cardholder_authentication object Optional	Authentication details about the prior cardholder. Allowable Values: See The prior_cardholder_authentication object.
sdk object Optional	SDK details. Allowable Values: See The sdk object.

The cardholder_authentication_by_merchant object

Fields	Description
data string Optional	Data that documents and supports a specific authentication process. (EMVCo reference: `threeDSReqAuthData`) Allowable Values: 20,000 char max
method string Optional	Value representing the signature verification performed by the DS on the mechanism used by the cardholder to authenticate to the 3DS Requestor. (EMVCo reference: `threeDSReqAuthMethod`) Allowable Values: - `NO_AUTHENTICATION` - No authentication performed - `REQUESTOR_CREDENTIALS` - Authentication using requestor credentials - `FEDERATED_ID` - Federated identity authentication - `ISSUER_CREDENTIALS` - Authentication using issuer credentials - `THIRD_PARTY_CREDENTIALS` - Third-party authentication service - `FIDO` - FIDO authentication method; your decisioning response is honored for this transaction - `FIDO_WITH_ASSURANCE_SIGNED` - FIDO with signed assurance data; informational only, since Marqeta has already applied the required outcome regardless of your decisioning response - `SRC_ASSURANCE_DATA` - SRC (Secure Remote Commerce) assurance data
time string Optional	Date and time of the cardholder authentication, expressed in UTC. (EMVCo reference: `threeDSReqAuthTimestamp`) Allowable Values: yyyy-MM-dd’T’HH:mm:ss.SSSZ
status boolean Optional	Indicates whether the 3DS method successfully completed. If missing, then this data is unavailable. (EMVCo reference: `threeDSCompInd`) Allowable Values: `true`, `false`

The prior_cardholder_authentication object

Fields	Description
data string Optional	Data that documents and supports a specific authentication process. (EMVCo reference: `threeDSReqPriorAuthData`) Allowable Values: 2048 char max
type string Optional	Mechanism previously used by the cardholder to authenticate to the 3DS Requestor. (EMVCo reference: `threeDSReqPriorAuthMethod`) Allowable Values: - `FRICTIONLESS_AUTHENTICATION_BY_ACS` - Frictionless authentication performed by ACS - `CHALLENGED_BY_ACS` - Challenge authentication performed by ACS - `AVS_VERIFIED` - Address Verification Service (AVS) verified - `OTHER` - Other authentication method not specified
time string Optional	Date and time of the previous cardholder authentication, expressed in UTC. (EMVCo reference: `threeDSReqPriorAuthTimestamp`) Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
acs_transaction_id string Optional	Provides additional information to the ACS to determine the best approach for handling a request. (EMVCo reference: `threeDSReqPriorRef`) Allowable Values: 36 char max

The sdk object

Fields	Description
application_id string Optional	Universally unique ID created upon all installations of the 3DS Requestor app on a consumer device. (EMVCo reference: `sdkAppID`) Allowable Values: 36 char max
reference_number string Optional	Identifies the vendor and version of the 3DS SDK integrated in a 3DS Requestor app; assigned by EMVCo when the 3DS SDK is approved. (EMVCo reference: `sdkReferenceNumber`) Allowable Values: 32 char max

The server object

Fields	Description
reference_number string Optional	Unique identifier assigned by the EMVCo secretariat upon testing and approval. (EMVCo reference: `threeDSServerRefNumber`) Allowable Values: 32 char max
operator_id string Optional	DS-assigned 3DS Server identifier. Each DS provides a unique ID to each 3DS Server on an individual basis. (EMVCo reference: `threeDSServerOperatorID`) Allowable Values: 32 char max

The client_browser object

Fields	Description
accept_headers string Optional	Exact content of the HTTP accept headers, as sent to the 3DS Requestor from the cardholder’s browser. (EMVCo reference: `browserAcceptHeader`) Allowable Values: 2048 char max
ip_address string Optional	IPv4 or IPv6 address of the browser, as returned by the HTTP headers to the 3DS Requestor. (EMVCo reference: `browserIP`) Allowable Values: 45 char max
is_java_enabled boolean Conditionally required	Indicates the ability of the cardholder’s browser to execute Java. Value is returned from the `navigator.javaEnabled` property. Only required when Browser JavaScript Enabled = `true`. (EMVCo reference: `browserJavaEnabled`) Allowable Values: `true`, `false`
is_javascript_enabled boolean Optional	Indicates the ability of the cardholder’s browser to execute JavaScript. (EMVCo reference: `browserJavascriptEnabled`) Allowable Values: `true`, `false`
language string Optional	Value representing the browser language, as defined in IETF BCP47. Returned from the `navigator.language` property. (EMVCo reference: `browserLanguage`) Allowable Values: minLength: 1 maxLength: 8
timezone_offset_in_minutes integer Optional	Time zone offset in minutes between UTC and the cardholder’s browser’s local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Only required when Browser JavaScript Enabled = `true`. (EMVCo reference: `browserTZ`) Allowable Values: minimum: -720 maximum: 720
user_agent string Optional	The exact contents of the HTTP user-agent header. (EMVCo reference: `browserUserAgent`) Allowable Values: 2048 char max

The device object

Fields	Description
channel string Required	Indicates the type of channel interface being used to initiate the transaction. (EMVCo reference: `deviceChannel`) Allowable Values: - `APP_BASED` - Native mobile application-based transaction - `BROWSER` - Browser-based web transaction - `THREEDS_REQUESTER_INITIATED` - 3DS Requestor initiated (3RI) transaction
additional_data string Optional	Device information gathered by the 3DS SDK from a consumer device. This Base64url-encoded JSON name/value pair will be populated by the DS as unencrypted data to the ACS obtained from SDK-encrypted data. (EMVCo reference: `deviceInfo`) Allowable Values: minLength: 1 maxLength: 64,000

The cardholder_account object

Fields	Description
identifier string Optional	Account ID that will be used in the authorization request for payment transactions. Can be represented by the PAN or token. (EMVCo reference: `acctID`) Allowable Values: minLength: 13 maxLength: 19
name string Optional	Name of the cardholder performing the transaction. (EMVCo reference: `cardholderName`) Allowable Values: A valid string.
email string Optional	Email address associated with the account: Either entered by the cardholder, or on file with the 3DS Requestor. (EMVCo reference: `email`) Allowable Values: 254 char max
account_type string Optional	The type of account. Required if the 3DS Requestor is asking the cardholder which account type they are using before making the purchase. (EMVCo reference: `acctType`) Allowable Values: - `NOT_AVAILABLE` - Account type not available or not applicable - `CREDIT` - Credit account or card - `DEBIT` - Debit account or card
card_expiry_date string Optional	Expiry date of the PAN or token supplied by the cardholder to the 3DS Requestor. (EMVCo reference: `cardExpiryDate`) Allowable Values: See The card_expiry_date object.
account_age string Optional	How long the cardholder has had the account with the 3DS Requestor. (EMVCo reference: `chAccAgeInd`) Allowable Values: - `NO_ACCOUNT` - No account exists - `DURING_TRANSACTION` - Account created during this transaction - `FEWER_THAN_30_DAYS` - Account created less than 30 days ago - `BETWEEN_30_AND_60_DAYS` - Account created 30-60 days ago - `GREATER_THAN_60_DAYS` - Account created more than 60 days ago
last_updated_date string Optional	Date when the cardholder’s account with the 3DS Requestor was last updated, including the billing or shipping address, new payment account, or new user(s) added. (EMVCo reference: `chAccChange`) Allowable Values: Format: yyyy-MM-dd
last_updated_duration string Optional	How long since the cardholder’s account information with the 3DS Requestor was last updated, including the billing or shipping address, new payment account, or new user(s) added. (EMVCo reference: `chAccChangeInd`) Allowable Values: - `THIS_TRANSACTION` - Updated during this transaction - `FEWER_THAN_30_DAYS` - Account information changed less than 30 days ago - `BETWEEN_30_AND_60_DAYS` - Account information changed 30-60 days ago - `GREATER_THAN_60_DAYS` - Account information changed more than 60 days ago
date_created string Optional	Date when the cardholder opened the account with the 3DS Requestor. (EMVCo reference: `chAccDate`) Allowable Values: Format: yyyy-MM-dd
password_changed_date string Optional	Date when the cardholder’s account with the 3DS Requestor last had a password change or account reset. (EMVCo reference: `chAccPwChange`) Allowable Values: Format: yyyy-MM-dd
password_changed_duration string Optional	How long since the cardholder’s account with the 3DS Requestor last had a password change or account reset. (EMVCo reference: `chAccPwChangeInd`) Allowable Values: - `NO_CHANGE` - No password change occurred - `THIS_TRANSACTION` - Password changed during this transaction - `FEWER_THAN_30_DAYS` - Password changed less than 30 days ago - `BETWEEN_30_AND_60_DAYS` - Password changed 30-60 days ago - `GREATER_THAN_60_DAYS` - Password changed more than 60 days ago
enrolled_date string Optional	Date when the payment account was enrolled in the cardholder’s account with the 3DS Requestor. (EMVCo reference: `paymentAccAge`) Allowable Values: Format: yyyy-MM-dd
enrolled_duration string Optional	How long since the payment account was enrolled in the cardholder’s account with the 3DS Requestor. (EMVCo reference: `paymentAccInd`) Allowable Values: - `NOT_ENROLLED` - Payment account not enrolled - `THIS_TRANSACTION` - Enrolled during this transaction - `FEWER_THAN_30_DAYS` - Enrolled less than 30 days ago - `BETWEEN_30_AND_60_DAYS` - Enrolled 30-60 days ago - `GREATER_THAN_60_DAYS` - Enrolled more than 60 days ago
shipping_address_first_used_date string Optional	Date when the shipping address indicated for this transaction was first used with the 3DS Requestor. (EMVCo reference: `shipAddressUsage`) Allowable Values: Format: yyyy-MM-dd
shipping_address_first_used_duration string Optional	How long since the shipping address indicated for this transaction was first used with the 3DS Requestor. (EMVCo reference: `shipAddressUsageInd`) Allowable Values: - `THIS_TRANSACTION` - Shipping address first used during this transaction - `FEWER_THAN_30_DAYS` - Shipping address first used less than 30 days ago - `BETWEEN_30_AND_60_DAYS` - Shipping address first used 30-60 days ago - `GREATER_THAN_60_DAYS` - Shipping address first used more than 60 days ago
ship_to_name_is_cardholder_name boolean Optional	Indicates whether the cardholder name on the account is identical to the shipping name used for this transaction. Allowable Values: `true`, `false`
experienced_suspicious_activity boolean Optional	Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. (EMVCo reference: `suspiciousAccActivity`) Allowable Values: `true`, `false`
phones object Optional	A list of phone numbers for this cardholder account. Keys can include `home`, `mobile`, and `work` and will be included if they are present. Allowable Values: See The phones object.
statistics object Optional	Cardholder activity statistics. Allowable Values: See The statistics object.
billing_address object Optional	Provides details related to the cardholder’s billing address. Allowable Values: See The AddressPhysical object.
shipping_address object Optional	Provides details related to the cardholder’s shipping address. Allowable Values: See The AddressPhysical object.

The phones object

Fields	Description
country_code number Required	Sometimes called the country prefix or country code, this is the international public telecommunication numbering plan that defines a numbering plan for the worldwide public switched telephone network (PSTN) and some other data networks. See also: https://en.wikipedia.org/wiki/E.164 Allowable Values: minLength: 1 maxLength: 3
subscriber string Required	The phone number without the country code (i.e., the area code, prefix, and subscriber number). Do not add spaces, hyphens, or the `+` symbol. Allowable Values: minLength: 1 maxLength: 15 Example: 5105551212

The statistics object

Fields	Description
purchase_count_6_months integer Optional	Number of purchases made with this cardholder account during the previous six months. (EMVCo reference: `nbPurchaseAccount`) Allowable Values: min: 0
provision_attempt_count_24_hours integer Optional	Number of add card attempts in the last 24 hours. (EMVCo reference: `provisionAttemptsDay`) Allowable Values: min: 0
transactions_count_24_hours integer Optional	Number of transactions (successful or abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. (EMVCo reference: `txnActivityDay`) Allowable Values: min: 0
transactions_count_1_year integer Optional	Number of transactions (successful or abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. (EMVCo reference: `txnActivityYear`) Allowable Values: min: 0

The directory_server object

This object describes information from the Directory Services (DS) in the network.

Fields	Description
reference_number string Required	EMVCo-assigned unique identifier to track approved DS. (EMVCo reference: `dsReferenceNumber`) Allowable Values: minLength: 1 maxLength: 32
authentication_result_url string Optional	URL of the DS to which the ACS will send the RReq if a challenge occurs. (EMVCo reference: `dsURL`) Allowable Values: A valid URL. 2048 char max Example: https://server.example.com/path

The recurring object

Fields	Description
expiration_date string Conditionally required	Date after which no further authorizations will be performed. Required when `request_type` is set to `RECURRING` or `INSTALLMENT`. (EMVCo reference: `recurringExpiry`) Allowable Values: Format: yyyy-MM-dd Example: 2024-07-21
minimum_days_between_authorizations integer Conditionally required	Indicates the minimum number of days between authorizations. Required when `request_type` is set to `RECURRING` or `INSTALLMENT`. (EMVCo reference: `recurringFrequency`) Allowable Values: minimum: 0 maximum: 9999

The transaction object

Contains information about how the payment is being made.

Fields	Description
transaction_type string Optional	Identifies the category of the message for a specific use case. (EMVCo reference: `messageCategory`) Allowable Values: `PAYMENT` - Payment transaction requiring authorization `NON_PAYMENT` - Non-payment transaction, such as account verification
sub_type string Optional	Identifies the type of transaction being authenticated. (EMVCo reference: `transType`) Allowable Values: - `PURCHASE` - Goods or services purchase transaction - `ACCOUNT_VERIFICATION` - Account verification without payment - `ACCOUNT_FUNDING` - Loading funds to an account - `QUASI_CASH` - Cash-equivalent transaction, such as money orders - `PREPAID_ACTIVATION_AND_LOAD` - Prepaid card activation and initial loading
amount number Optional	Purchase amount in minor units of currency with all punctuation removed. For example, a purchase for $1.99 would be 199. (EMVCo reference: `purchaseAmount`) Allowable Values: A valid number.
currency_code number Optional	ISO 4217 three-digit currency code of the payment or purchased gift card. See https://www.iso.org/iso-4217-currency-codes.html Allowable Values: minLength: 3 maxLength: 3
exponent integer Optional	Minor units of currency value, as specified in the ISO 4217 currency exponent. For USD, the value is 2. (EMVCo reference: `purchaseExponent`) Allowable Values: A valid ISO 4217 code. See https://www.iso.org/iso-4217-currency-codes.html
date string Optional	Date and time of the purchase, expressed in UTC. (EMVCo reference: `purchaseDate`) Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
shipping_address_is_billing_address boolean Optional	Indicates whether the cardholder shipping address and cardholder billing address are the same. (EMVCo reference: `addrMatch`) Allowable Values: `true`, `false`
maximum_permitted_installments integer Optional	Indicates the maximum number of authorizations permitted for installment payments. (EMVCo reference: `purchaseInstalData`) Allowable Values: minimum: 1 maximum: 999
detokenisation_source string Optional	EMV Payment Token Source. This data element is populated by the system residing in the 3D Secure domain where the de-tokenization occurs. If not present, the transaction was not de-tokenized. (EMVCo reference: `payTokenSource` and `payTokenInd`) Allowable Values: - `3DS_SERVER` - De-tokenization performed by 3DS Server - `DIRECTORY_SERVER` - De-tokenization performed by Directory Server
recurring object Optional	Authorization and expiration details for transactions of the recurring type. Allowable Values: See The recurring object.

The card_acceptor object

Warning
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.

Fields	Description
acquirer_bin string Conditionally required	Acquiring institution identification code, as assigned by the DS receiving the AReq message. Required when `messageCategory = 01`; optional when `messageCategory = 02`. (EMVCo reference: `acquirerBIN`) Allowable Values: 11 char max
merchant_id string Conditionally required	Acquirer-assigned merchant identifier. Required when `messageCategory = 01`; optional when `messageCategory = 02`. (EMVCo reference: `acquirerMerchantID`) Allowable Values: 35 char max
merchant_category_code string Optional	Merchant Category Code (MCC). DS-specific code describing the merchant’s type of product or service. (EMVCo reference: `mcc`) Allowable Values: minLength: 4 maxLength: 4
country string Optional	ISO 3166-1 three-digit country code of the merchant address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2 Allowable Values: minLength: 2 maxLength: 3
name string Optional	Merchant name assigned by the acquirer or payment system. (EMVCo reference: `merchantName`) Allowable Values: 40 char max
risk_indicators object Optional	Merchant’s assessment of the level of fraud risk for the specific authentication, as applies to both the cardholder and the authentication being performed. (EMVCo reference: `merchantRiskIndicator`) Allowable Values: See The risk_indicators object.

The risk_indicators object

Fields	Description
delivery object Optional	Contains delivery details. Allowable Values: See The delivery object.
gift_cards object Optional	If the purchase included buying gift cards, this object includes information about those gift cards. Allowable Values: See The gift_cards object.
pre_order object Optional	If a pre-order, includes information about the pre-order. Allowable Values: See The pre_order object.
is_reorder boolean Optional	Indicates whether the cardholder is reordering previously purchased merchandise. If missing, then this is not a reorder. (EMVCo reference: `reorderItemsInd`) Allowable Values: `true`, `false`
shipping_indicator string Optional	Indicates the transaction’s shipping method. Merchants must choose the shipping indicator code that most accurately describes the cardholder’s specific transaction, and not their general business. (EMVCo reference: `shipIndicator` and `addrMatch`) Allowable Values: - `BILLING_ADDRESS` - Ship to cardholder’s billing address - `OTHER_VERIFIED_ADDRESS` - Ship to another verified address on file with the merchant - `UNVERIFIED_ADDRESS` - Ship to address that is different than the cardholder’s billing address - `SHIP_TO_STORE` - Ship to store for customer pickup - `DIGITAL_GOODS` - Digital goods (includes online services, electronic gift cards, and redemption codes) - `TRAVEL_AND_EVENT_TICKETS` - Travel and event tickets, not shipped - `OTHER` - Other (for example, gaming, digital services not shipped, or e-media subscriptions)

The delivery object

Fields	Description
email string Optional	For electronic delivery, the email address to which the merchandise was delivered. (EMVCo reference: `deliveryEmailAddress`) Allowable Values: 254 char max
timeframe string Optional	Indicates the merchandise delivery timeframe. (EMVCo reference: `deliveryTimeframe`) Allowable Values: - `ELECTRONIC` - Electronic delivery - `SAME_DAY_SHIPPING` - Same-day shipping - `OVERNIGHT_SHIPPING` - Overnight shipping - `TWO_DAYS_OR_MORE_SHIPPING` - Two-or-more day shipping

The gift_cards object

Fields	Description
currency_code number Optional	ISO 4217 three-digit currency code of the payment or purchased gift card. See also: https://www.iso.org/iso-4217-currency-codes.html Allowable Values: minLength: 3 maxLength: 3
loaded_amount number Optional	For a prepaid or gift card purchase, the total purchase amount of prepaid or gift cards in major units (for example, a purchase of $123.45 is 12345). (EMVCo reference: `giftCardAmount`) Allowable Values: minimum: 0 maximum: 2147483647
number_of_cards_purchased integer Optional	For a prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased. (EMVCo reference: `giftCardCount`) Allowable Values: minimum: 0 maximum: 99

The pre_order object

Fields	Description
merchandise_available_date string Optional	For a pre-ordered purchase, the expected date when the merchandise will be available. Merchants sometimes create pre-orders to hold an order for customers whose 3DS SCA is pending. This is why the “pre-order” exists and the merchandise availability is immediate. (EMVCo reference: `preOrderDate`) Allowable Values: Format: yyyy-MM-dd
merchandise_availability string Optional	Indicates whether the cardholder is placing an order for merchandise with a future availability or release date. (EMVCo reference: `preOrderPurchaseInd`) Allowable Values: `IMMEDIATE` - Merchandise available immediately `FUTURE` - Merchandise available in the future

The whitelist object

Fields	Description
status string Optional	Enables the communication of trusted beneficiary/allow list status between the ACS, the DS, and the 3DS Requestor. (EMVCo reference: `whiteListStatus`) Allowable Values: - `WHITELISTED` - Cardholder or merchant is allow-listed for exemption - `NOT_WHITELISTED` - Standard authentication required - `NOT_ELIGIBLE` - Cardholder or merchant is not eligible for allow-listing - `PENDING` - Allow list status determination pending - `REJECTED` - Allow list request was rejected - `UNKNOWN` - Allow list status cannot be determined
source string Optional	The allow list status source. (EMVCo reference: `whiteListStatusSource`) Allowable Values: - `3DS_SERVER` - Allow list status provided by 3DS Server - `DIRECTORY_SERVER` - Allow list status provided by Directory Server - `ACS` - Allow list status determined by Access Control Server

The AddressPhysical object

Provides details related to the cardholder’s shipping/billing address.

Fields	Description
address1 string Optional	First line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max
address2 string Optional	Second line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max
address3 string Optional	Third line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max
city string Optional	City of the cardholder’s shipping/billing address. Allowable Values: 50 char max
state string Optional	ISO 3166-2 country subdivision code associated with the state or province of the cardholder’s shipping/billing address. See also: https://en.wikipedia.org/wiki/ISO_3166-2:US Allowable Values: Two- or three-digit state code
post_code string Optional	ZIP or postal code of the cardholder’s shipping/billing address. Allowable Values: 16 char max
country string Optional	ISO 3166-1 three-digit country code of the cardholder’s shipping/billing address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2 Allowable Values: Two- or three-digit country code

The card_expiry_date object

Fields	Description
two_digit_year integer Required	Two-digit year when this card expires. For example, if the card expires in the year 2025, this value is 25. Allowable Values: Two-digit integer
month integer Required	Month of the year when this card expires. For example, if the card expires in February, this value is 2. Allowable Values: minimum: 1 maximum: 12

ThreeDSDecisionResponse (response)

The response to an ACS decision request. Your decision service must respond to each delegated decision request with a decision of CHALLENGE, DECLINE, or EXEMPT. Ensure that your response body adheres to the specifications in this section. You must include all required fields regardless of whether you challenge or exempt the request.

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify a single transaction. Respond with the same value sent in the request. (EMVCo reference: `acsTransID`) Allowable Values: 36 char max
type string Optional	Authentication type that determines the action to be taken by the receiver of this message. Allowable Values: `authentication.decision`
recommended_action string REQUIRED	Whether the ACS system should `CHALLENGE`, `DECLINE`, or `EXEMPT` the transaction from the SCA. This field indicates whether a challenge is required in order for the transaction to be authorized. (EMVCo reference: `acsChallengeMandated`) Allowable Values: - `CHALLENGE` - Strong Customer Authentication (SCA) challenge required - `DECLINE` - Transaction should be declined due to high fraud risk - `EXEMPT` - Transaction qualifies for SCA exemption (low risk/value)
model string Optional	Which model was used to score the request. Allowable Values: minLength: 2 maxLength: 64 Example: FraudModel_inttest_1534190172
challenge_score number Optional	The confidence interface between [0..1] (0 being least confident and 1 being most confident) in the `recommended_action`. Allowable Values: Example: 0.89
reasons array Optional	Reasons why the challenge or exemption was recommended. Allowable Values: A valid array.
primary_reason string Optional	Primary reason why the challenge or exemption was recommended. Allowable Values: 255 char max
use_otp_challenge boolean Optional	Indicates if the Marqeta OTP challenge will be used to authenticate the cardholder. If not sent, the program-level challenge preference will be used. Allowable Values: `true`, `false`
api object Optional	Information regarding the API call and how it was handled. Allowable Values: See DecisionServiceResponse.

APIResponseWithErrors (response)

A list of problems with the request that the caller might be able to fix.

Fields	Description
version_used string Optional	The version of the API that the server supports and is using. Do not simply echo back the `X-VERSION` header. Allowable Values: Pattern: `^\d+\.\d+\.\d+$` Example: 31.41.5
errors string Optional	The error with a message that might be helpful when debugging. Allowable Values: 255 char max

Response codes

Code	Description
200	The decision whether to exempt or to challenge. See ThreeDSDecisionResponse.
400	Invalid ACS payload detected. See APIResponseWithErrors.
401	Authentication information is missing or invalid headers.
500	No model could be found or loaded, including the default.

Sample request body

JSON

{
  "acs_transaction_id": "acs_transaction_id",
  "type": "authentication.decision",
  "state": "PENDING",
  "user_token": "user_token",
  "acting_user_token": "acting_user_token",
  "card_token": "card_token",
  "created_time": "2025-02-12T18:16:32.123Z",
  "network": "VISA",
  "message_version": "2.1.0",
  "message_extension": [
    {
      "name": "name",
      "id": "id",
      "criticality_indicator": true,
      "data": "data"
    }
  ],
  "authentication_request_type": "PAYMENT",
  "requester": {
    "notification_url": "https://www.example.com/path/to/resource",
    "challenge_preference": "NO_CHALLENGE",
    "decoupled_challenge_preference": "DECOUPLED_AUTHENTICATION_PREFERRED",
    "name": "requestor_name",
    "customer_care_url": "https://help.example.com/customer-service",
    "request_type": "RECURRING",
    "cardholder_authentication_by_merchant": {
      "data": "data",
      "method": "FIDO",
      "time": "2025-02-11T19:16:32Z",
      "status": true
    },
    "prior_cardholder_authentication": {
      "data": "string",
      "method": "FRICTIONLESS_AUTHENTICATION_BY_ACS",
      "time": "2025-02-11T18:16:32Z",
      "acs_transaction_id": "acs_transaction_id"
    },
    "sdk": {
      "application_id": "application_id",
      "reference_number": "reference_number"
    }
  },
  "server": {
    "reference_number": "reference_number",
    "operator_id": "operator_id"
  },
  "client_browser": {
    "accept_headers": "string",
    "ip_address": "172.16.254.1",
    "is_java_enabled": true,
    "is_javascript_enabled": true,
    "language": "en-US",
    "timezone_offset_in_minutes": 0,
    "user_agent": "user_agent"
  },
  "device": {
    "channel": "APP_BASED",
    "additional_data": "data"
  },
  "cardholder_account": {
    "identifier": "cardholder_id",
    "name": "cardholder_name",
    "email": "user@example.com",
    "account_type": "NOT_AVAILABLE",
    "card_expiry_date": {
      "two_digit_year": 23,
      "month": 2
    },
    "account_age": "DURING_TRANSACTION",
    "last_updated_date": "2025-02-12T18:16:32Z",
    "last_updated_duration": "THIS_TRANSACTION",
    "date_created": "2025-02-12T18:16:32Z",
    "password_changed_date": "2025-02-12T18:16:32Z",
    "password_changed_duration": "NO_CHANGE",
    "enrolled_date": "2025-02-12T18:16:32Z",
    "enrolled_duration": "NOT_ENROLLED",
    "shipping_address_first_used_date": "2025-02-12T18:16:32Z",
    "shipping_address_first_used_duration": "THIS_TRANSACTION",
    "ship_to_name_is_cardholder_name": true,
    "experienced_suspicious_activity": true,
    "phones": {
      "additionalProp1": {
        "country_code": "1",
        "subscriber": "5105551212"
      },
      "additionalProp2": {
        "country_code": "1",
        "subscriber": "5105551212"
      },
      "additionalProp3": {
        "country_code": "1",
        "subscriber": "5105551212"
      }
    },
    "statistics": {
      "purchase_count_6_months": 0,
      "provision_attempt_count_24_hours": 0,
      "transactions_count_24_hours": 0,
      "transactions_count_1_year": 0
    },
    "billing_address": {
      "address1": "1 Address Street",
      "address2": "Apt A",
      "address3": "",
      "city": "Omaha",
      "state": "NE",
      "post_code": "68134",
      "country": "USA"
    },
    "shipping_address": {
      "address1": "Post Office Box 0",
      "address2": "",
      "address3": "",
      "city": "Omaha",
      "state": "NE",
      "post_code": "68134",
      "country": "USA"
    }
  },
  "directory_server": {
    "reference_number": "reference_number",
    "authentication_result_url": "https://server.example.com/path"
  },
  "transaction": {
    "transaction_type": "PAYMENT",
    "sub_type": "PURCHASE",
    "amount": 199,
    "currency_code": 978,
    "exponent": 2,
    "date": "2025-02-12T18:16:32Z",
    "shipping_address_is_billing_address": true,
    "maximum_permitted_installments": 0,
    "detokenisation_source": "3DS_SERVER",
    "recurring": {
      "expiration_date": "2025-07-21",
      "minimum_days_between_authorizations": 7
    }
  },
  "card_acceptor": {
    "acquirer_bin": "acquirer_bin",
    "merchant_id": "merchant_id",
    "merchant_category_code": "5734",
    "country": "826",
    "name": "Company 3DS2 Validation",
    "risk_indicators": {
      "delivery": {
        "email": "user@example.com",
        "timeframe": "ELECTRONIC"
      },
      "gift_cards": {
        "currency_code": 978,
        "loaded_amount": 0,
        "number_of_cards_purchased": 0
      },
      "pre_order": {
        "merchandise_available_date": "2025-02-21",
        "merchandise_availability": "IMMEDIATE"
      },
      "is_reorder": true,
      "shipping_indicator": "BILLING_ADDRESS"
    }
  },
  "whitelist": {
    "status": "WHITELISTED",
    "source": "3DS_SERVER"
  }
}

Sample response body

JSON

{
  "acs_transaction_id": "acs_transaction_id",
  "type": "authentication.decision",
  "recommended_action": "CHALLENGE",
  "model": "FraudModel_inttest_1534190172",
  "challenge_score": 0.89,
  "reasons": [
    "Three_ds.2.2.article.14",
    "Three_ds.2.2.article.16"
  ],
  "primary_reason": "Three_ds.2.2.article.14",
  "use_otp_challenge": true,
  "api": {
    "version_used": "31.41.5"
  }
}

Notify a 3DS completion status

Action: POST
Endpoint: /three-ds/challenge-result Informs the Delegated 3DS decision service whether or not the strong customer authentication (SCA) challenge has succeeded, which is required to evaluate future transactions. This is the URL of the notification endpoint hosted in your environment, to which POST messages are submitted by the Marqeta platform.

Body field details

The following table describes the payload required to score an ACS request.

The ThreeDSChallengeResultRequest object

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: `acsTransID`) Allowable Values: 36 char max
type string Optional	Authentication type that determines the action to be taken by the receiver of this message. 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 user token identifying the user. Allowable Values: 36 char max
acting_user_token string Optional	Marqeta-assigned unique user token identifying 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. (EMVCo reference: `interactionCounter`) Allowable Values: As provided by the ACS Default Value: 1
cancel_reason integer Optional	Indicates to the ACS and the DS that the authentication has been cancelled. (EMVCo reference: `challengeCancel`) DEPRECATED: This field is still sent for backward compatibility, but its value is outdated. 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

DecisionServiceResponse (response)

Provides information regarding the call and how it was handled.

Fields	Description
version_used string Required	The version of the API that the server supports and is using. Do not simply echo back the `X-VERSION` header. Allowable Values: Pattern: `^\d+\.\d+\.\d+$` Example: 31.41.5

Response codes

Code	Description
200	The result of the 3DS verification (SCA).
400	Invalid ACS payload detected. See APIResponseWithErrors.
409	Result already processed for this ACS transaction; any subsequent responses received are ignored. See APIResponseWithErrors.
500	No model could be found or loaded, including the default.

Sample request body

JSON

{
  "acs_transaction_id": "acs_transaction_id",
  "type": "authentication.result",
  "state": "PENDING",
  "authentication_method": "BIOMETRIC_FACE",
  "authentication_result": "SUCCESS",
  "interaction_counter": 0,
  "cancel_reason": "CARDHOLDER_CANCEL"
}

Sample response

JSON

200 OK

Receive an Advanced Authentication challenge

Action: POST
Endpoint: /three-ds/authentication Stand up this endpoint to receive a cardholder challenge from Marqeta using Advanced Authentication. An Advanced Authentication request prompts you to challenge the cardholder using advanced methods such as biometrics or voice recognition. For details on the Advanced Authentication process, see Advanced Authentication and Advanced authentication lifecycle.

Request header

Fields	Description
X-VERSION char Required	Identifies the version of the service and data structures used. This value is not the same as the 3DS version. If omitted, the latest version is assumed. Allowable Values: A valid version number.

Body field details

The following table describes the payload required to authenticate a request.

The ThreeDSAuthenticationRequest object

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: `acsTransID`) Allowable Values: 36 char max
type string Required	Authentication type that determines the action to be taken by the receiver of this message. Allowable Values: `authentication.challenge.out_of_band`, `authentication.challenge.decoupled`
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 Required	Marqeta-assigned unique user token identifying the user. Allowable Values: 32 char max
acting_user_token string Required	Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 32 char max
card_token string Required	Marqeta-assigned unique card token identifying the user. Allowable Values: 32 char max
created_time string Required	Authentication request time, expressed as an ISO-8601 UTC timestamp. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ
network string Required	The card network associated with this authentication/decision request. Allowable Values: - `VISA` - Visa card network transactions - `MASTERCARD` - Mastercard network transactions
message_version string Required	The 3DS protocol version used by the 3DS Requestor. (EMVCo reference: `messageversion`) Allowable Values: minLength: 5 maxLength: 8
authentication_request_type string Optional	Indicates the type of authentication request. (EMVCo reference: `threeDSRequestorAuthenticationInd`) 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
max_response_time number Required	Indicates the maximum period of time, in minutes, that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction. (EMVCo reference: `threeDSRequestorDecMaxTime`) Allowable Values: A five-digit number with a value between `1` and `10080`, inclusive, without leading zeros. Default value: 8
transaction object Required	Contains information about how the payment is being made. Allowable Values: See The transaction object.
card_acceptor object Required	Details about the merchant with which this transaction is being conducted. Allowable Values: See The card_acceptor object.
three_ds_requester_app_url string Optional	The fully qualified URL of the merchant application that initiated the 3D Secure authentication request. Allowable Values: 255 char max
three_ds_requester_url string Optional	The fully qualified URL of the merchant’s website or customer care site. Allowable Values: 255 char max

The transaction object

Contains information about how the payment is being made.

Fields	Description
transaction_type string Optional	Identifies the category of the message for a specific use case. (EMVCo reference: `messageCategory`) Allowable Values: `PAYMENT` - Payment transaction requiring authorization `NON_PAYMENT` - Non-payment transaction, such as account verification
sub_type string Optional	Identifies the type of transaction being authenticated. (EMVCo reference: `transType`) Allowable Values: - `PURCHASE` - Goods or services purchase transaction - `ACCOUNT_VERIFICATION` - Account verification without payment - `ACCOUNT_FUNDING` - Loading funds to an account - `QUASI_CASH` - Cash-equivalent transaction, such as money orders - `PREPAID_ACTIVATION_AND_LOAD` - Prepaid card activation and initial loading
amount number Optional	Purchase amount in minor units of currency with all punctuation removed. For example, a purchase for $1.99 would be 199. (EMVCo reference: `purchaseAmount`) Allowable Values: Valid number
currency_code number Optional	ISO 4217 three-digit currency code of the payment or purchased gift card. See https://www.iso.org/iso-4217-currency-codes.html Allowable Values: minLength: 3 maxLength: 3
exponent integer Optional	Minor units of currency value, as specified in the ISO 4217 currency exponent. For USD, the value is 2. (EMVCo reference: `purchaseExponent`) Allowable Values: Valid ISO 4217 code See https://www.iso.org/iso-4217-currency-codes.html

The card_acceptor object

Warning
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.

Fields	Description
acquirer_bin string Conditionally required	Acquiring institution identification code, as assigned by the DS receiving the AReq message. Required when `messageCategory = 01`; optional when `messageCategory = 02`. (EMVCo reference: `acquirerBIN`) Allowable Values: 11 char max
merchant_id string Conditionally required	Acquirer-assigned merchant identifier. Required when `messageCategory = 01`; optional when `messageCategory = 02`. (EMVCo reference: `acquirerMerchantID`) Allowable Values: 35 char max
merchant_category_code string Optional	Merchant Category Code (MCC). DS-specific code describing the merchant’s type of product or service. (EMVCo reference: `mcc`) Allowable Values: minLength: 4 maxLength: 4
country string Optional	ISO 3166-1 three-digit country code of the merchant address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2 Allowable Values: minLength: 2 maxLength: 3
name string Optional	Merchant name assigned by the acquirer or payment system. (EMVCo reference: `merchantName`) Allowable Values: 40 char max

Response codes

Code	Description
200	Successful acknowledgement of a 3DS Advanced Authentication request.
400	Invalid authentication payload detected.
401	Unauthorized 3DS Authentication request.
403	Forbidden 3DS Authentication request.
500	Internal server error, unable to process the request.

Sample request body

JSON

{
  "acs_transaction_id": "acs_transaction_id",
  "type": "authentication.challenge.out_of_band",
  "state": "PENDING",
  "user_token": "user_token",
  "acting_user_token": "acting_user_token",
  "card_token": "card_token",
  "created_time": "2025-06-08T17:49:56.594Z",
  "network": "VISA",
  "message_version": "2.1.0",
  "authentication_request_type": "PAYMENT",
  "max_response_time": 7,
  "transaction": {
    "transaction_type": "PAYMENT",
    "sub_type": "PURCHASE",
    "amount": 199,
    "currency_code": 978,
    "exponent": 2
  },
  "card_acceptor": {
    "acquirer_bin": "acquirer_bin",
    "merchant_id": "merchant_id",
    "merchant_category_code": "5734",
    "country": "826",
    "name": "acceptor_name"
  }
}

Sample response

JSON

200 OK

Update an authentication result to Marqeta

Action: POST
Endpoint URL: https://authentication-acs.marqeta.com/v3/three-ds/authentication-result Accepts the 3DS out-of-band/decoupled challenge result and informs the ACS of the cardholder authentication result. Use your Marqeta Core API credentials.

Body field details

The following table describes the response to an ACS authentication request.

The ThreeDSAuthenticationResultRequest object

Fields	Description
acs_transaction_id string Required	Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: `acsTransID`) Allowable Values: 36 char max
authentication_method string Required	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 Required	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. (EMVCo reference: `interactionCounter`) Allowable Values: As provided by the ACS Default Value: 1
cancel_reason string Optional	Indicator informing the ACS and the DS that the authentication has been cancelled. (EMVCo reference: `challengeCancel`) DEPRECATED: This field is still sent for backward compatibility, but its value is outdated. Allowable Values: - `CARDHOLDER_CANCEL` - Cardholder explicitly cancelled authentication - `TIMED_OUT_DECOUPLED_AUTHENTICATION` - Decoupled/out of band (OOB) authentication timed out waiting for response - `TIMED_OUT_AT_ACS` - ACS timed out after receiving initial challenge request but before completion - `TIMED_OUT_AT_ACS_NO_CREQ` - ACS timed out waiting for first challenge request after authentication response challenge required - `TIMED_OUT_AT_SDK` - 3DS SDK timed out during authentication process - `UNKNOWN` - Cancellation reason could not be determined
message_version string Required	The 3DS protocol version used by the 3DS Requestor. Echo the value from the Advanced Authentication request. (EMVCo reference: `messageversion`) Allowable Values: 8 char max

Response codes

Code	Description
200	Successful acknowledgement of 3DS Authentication result.
400	Invalid payload detected.
401	Unauthorized 3DS Authentication request.
403	Forbidden 3DS Authentication request.
500	Internal server error, unable to process the request. Please resubmit.

Sample request body

JSON

{
  "acs_transaction_id": "acs_transaction_id",
  "authentication_method": "BIOMETRIC_FACE",
  "authentication_result": "SUCCESS",
  "interaction_counter": 0,
  "cancel_reason": "CARDHOLDER_CANCEL",
  "message_version": "2.1.0"
}

Sample response

JSON

200 OK

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

​Delegate decisioning - determine whether to send an SCA

​Request header

​Body field details

​The ThreeDSDecisionRequest object

​The message_extension object

​The requester object

​The cardholder_authentication_by_merchant object

​The prior_cardholder_authentication object

​The sdk object

​The server object

​The client_browser object

​The device object

​The cardholder_account object

​The phones object

​The statistics object

​The directory_server object

​The recurring object

​The transaction object

​The card_acceptor object

​The risk_indicators object

​The delivery object

​The gift_cards object

​The pre_order object

​The whitelist object

​The AddressPhysical object

​The card_expiry_date object

​ThreeDSDecisionResponse (response)

​APIResponseWithErrors (response)

​Response codes

​Sample request body

​Sample response body

​Notify a 3DS completion status

​Body field details

​The ThreeDSChallengeResultRequest object

​DecisionServiceResponse (response)

​Response codes

​Sample request body

​Sample response

​Receive an Advanced Authentication challenge

​Request header

​Body field details

​The ThreeDSAuthenticationRequest object

​The transaction object

​The card_acceptor object

​Response codes

​Sample request body

​Sample response

​Update an authentication result to Marqeta

​Body field details

​The ThreeDSAuthenticationResultRequest object

​Response codes

​Sample request body

​Sample response

​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

Delegate decisioning - determine whether to send an SCA

Request header

Body field details

The ThreeDSDecisionRequest object

The message_extension object

The requester object

The cardholder_authentication_by_merchant object

The prior_cardholder_authentication object

The sdk object

The server object

The client_browser object

The device object

The cardholder_account object

The phones object

The statistics object

The directory_server object

The recurring object

The transaction object

The card_acceptor object

The risk_indicators object

The delivery object

The gift_cards object

The pre_order object

The whitelist object

The AddressPhysical object

The card_expiry_date object

ThreeDSDecisionResponse (response)

APIResponseWithErrors (response)

Response codes

Sample request body

Sample response body

Notify a 3DS completion status

Body field details

The ThreeDSChallengeResultRequest object

DecisionServiceResponse (response)

Response codes

Sample request body

Sample response

Receive an Advanced Authentication challenge

Request header

Body field details

The ThreeDSAuthenticationRequest object

The transaction object

The card_acceptor object

Response codes

Sample request body

Sample response

Update an authentication result to Marqeta

Body field details

The ThreeDSAuthenticationResultRequest object

Response codes

Sample request body

Sample response

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