> ## Documentation Index > Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 3D Secure > The 3DS API provides a decision service that accepts scoring events and evaluates whether to apply strong customer authentication (SCA) with 3DS or to exempt. export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => { const METHOD_STYLES = { GET: { bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20", text: "mint-text-green-700 dark:mint-text-green-400", border: "mint-border-green-300 dark:mint-border-green-700" }, POST: { bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20", text: "mint-text-blue-700 dark:mint-text-blue-400" }, PUT: { bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20", text: "mint-text-yellow-700 dark:mint-text-yellow-400" }, PATCH: { bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20", text: "mint-text-orange-700 dark:mint-text-orange-400" }, DELETE: { bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20", text: "mint-text-red-700 dark:mint-text-red-400" }, API: { bg: "mint-bg-black", text: "mint-text-white" } }; const MethodBadge = ({method}) => { const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET; return {method?.toUpperCase()} ; }; const content =
{}
{}

{title}

{children &&

{children}

}
; if (!href) return content; return {content} ; }; 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](https://www.emvco.com/specifications). 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](/developer-guides/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](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](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 | | type

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: `threeDSReqAuthMethodInd`)

**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

- `FIDO_WITH_ASSURANCE_SIGNED` - FIDO with signed assurance data

- `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](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](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](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](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](https://www.iso.org/iso-3166-country-codes.html) and [https://en.wikipedia.org/wiki/ISO\_3166-2](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](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](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](https://www.iso.org/iso-3166-country-codes.html) and [https://en.wikipedia.org/wiki/ISO\_3166-2](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 JSON expandable lines wrap theme={null} { "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 JSON lines wrap theme={null} { "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`)

**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 JSON lines wrap theme={null} { "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 JSON lines wrap theme={null} 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](/developer-guides/about-3d-secure/#_advanced_authentication) and [Advanced authentication lifecycle](/developer-guides/about-3d-secure/#_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](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](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](https://www.iso.org/iso-3166-country-codes.html) and [https://en.wikipedia.org/wiki/ISO\_3166-2](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 JSON expandable lines wrap theme={null} { "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 JSON lines wrap theme={null} 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`)

**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 JSON lines wrap theme={null} { "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 JSON lines wrap theme={null} 200 OK ``` ## Related topics - [3D Secure Overview](/docs/developer-guides/3ds-landing-page.md) - [About 3D Secure](/docs/developer-guides/about-3d-secure.md) - [3D Secure Setup](/docs/developer-guides/3ds-setup.md) - [3D Secure in Europe](/docs/developer-guides/mq-eu-3ds.md) - [3D Secure Risk Engine Schema](/docs/developer-guides/3ds-risk-engine-schema.md)