> ## 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. # Delegate decisioning - determine whether to send an SCA > Evaluate whether or not the cardholder will be prompted with a strong customer authentication (SCA) challenge to complete this authentication. POST/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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_requester_object). | | server string Optional | The server details. **Allowable Values:** See [The server object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_server_object). | | client\_browser string Optional | Client browser details. **Allowable Values:** See [The client\_browser object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_client_browser_object). | | device string Optional | The device details. **Allowable Values:** See [The device object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_directory_server_object). | | transaction string Required | Contains information about how the payment is being made. **Allowable Values:** See [The transaction object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_card_acceptor_object). | | whitelist string Optional | Details regarding the allow list. **Allowable Values:** See [The whitelist object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_whitelist_object). | | tra\_response object Optional | The decision returned by the Marqeta automated decisioning service (issuer transaction risk analysis) for this authentication. Included only for programs that have opted in to running both automated decisioning and delegated decisioning. **NOTE:** This feature requires additional activation steps. To learn about activating it for your program, contact your Marqeta representative. **Allowable Values:** See [The tra\_response object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_tra_response_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_prior_cardholder_authentication_object). | | sdk object Optional | SDK details. **Allowable Values:** See [The sdk object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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 | | verified\_acs\_authentication string Optional | Outcome of the prior authentication, as verified by the ACS. **NOTE:** The ACS verifies this value; the merchant does not supply it. This field is present only when the request includes a prior `acs_transaction_id` that belongs to the card in this transaction. **Allowable Values:** - `CHALLENGE_SUCCESS` - The cardholder successfully completed a challenge in the prior authentication - `FRICTIONLESS` - The prior authentication was completed without a challenge - `FAILED` - The prior authentication failed | | verified\_amount number Optional | Amount of the prior authentication, as verified by the ACS. **NOTE:** The ACS verifies this value; the merchant does not supply it. This field is present only when the request includes a prior `acs_transaction_id` that belongs to the card in this transaction. **Allowable Values:** A valid number. | | verified\_currency\_code string Optional | ISO 4217 three-digit numeric currency code of the prior authentication, as verified by the ACS. **NOTE:** The ACS verifies this value; the merchant does not supply it. This field is present only when the request includes a prior `acs_transaction_id` that belongs to the card in this transaction. **Allowable Values:** A valid ISO 4217 numeric code. See [[https://www.iso.org/iso-4217-currency-codes.html](https://www.iso.org/iso-4217-currency-codes.html)](https://www.iso.org/iso-4217-currency-codes.html) | | verified\_exponent integer Optional | Minor units of currency for `verified_amount`, as specified in the ISO 4217 currency exponent. For USD, the value is 2. **NOTE:** The ACS verifies this value; the merchant does not supply it. This field is present only when the request includes a prior `acs_transaction_id` that belongs to the card in this transaction. **Allowable Values:** A valid ISO 4217 currency exponent. | ## 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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_phones_object). | | statistics object Optional | Cardholder activity statistics. **Allowable Values:** See [The statistics object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_statistics_object). | | billing\_address object Optional | Provides details related to the cardholder's billing address. **Allowable Values:** See [The AddressPhysical object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_addressphysical_object). | | shipping\_address object Optional | Provides details related to the cardholder's shipping address. **Allowable Values:** See [The AddressPhysical object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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)](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)](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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_recurring_object). | ## The card\_acceptor object > [!CAUTION] > > **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)](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)](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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_the_risk_indicators_object). | ## The risk\_indicators object | Fields | Description | | - | - | | delivery object Optional | Contains delivery details. **Allowable Values:** See [The delivery object](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_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)](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 tra\_response object Contains the decision returned by the Marqeta automated decisioning service (issuer transaction risk analysis) for this authentication. This object is included only for programs that have opted in to running both automated decisioning and delegated decisioning. > [!NOTE] > > This feature requires additional activation steps. > To learn about activating it for your program, contact your Marqeta representative. | Fields | Description | | - | - | | recommended\_action string Optional | The action recommended by automated decisioning. **Allowable Values:** - `CHALLENGE` - Strong customer authentication (SCA) challenge recommended - `EXEMPT` - Transaction recommended for SCA exemption - `DECLINE` - Transaction recommended for decline | | primary\_reason string Optional | Name of the automated decisioning rule that primarily triggered the recommended action. For custom rules, this is the rule name defined in your program configuration. **Allowable Values:** A valid rule name. | | reasons array of strings Optional | Names of all automated decisioning rules triggered for this authentication. **Allowable Values:** A valid array of rule names. | | status string Optional | Indicates whether automated decisioning ran successfully. A value of `FAILURE` means that automated decisioning timed out or returned an error, rather than that no rules were triggered. When the value is `FAILURE`, the other fields in this object are not present. **Allowable Values:** - `SUCCESS` - Automated decisioning returned a usable recommendation - `FAILURE` - Automated decisioning timed out or returned an error | ## 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)](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)](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)](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](https://www.marqeta.com/docs/core-api/3ds/notify-completion-status.md#_decisionserviceresponse_response). | ## 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](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_threedsdecisionresponse_response). | | 400 | Invalid ACS payload detected. See [APIResponseWithErrors](https://www.marqeta.com/docs/core-api/3ds/delegate-decisioning-determine-whether-send-sca.md#_apiresponsewitherrors_response). | | 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", "verified_acs_authentication": "CHALLENGE_SUCCESS", "verified_amount": 199, "verified_currency_code": "978", "verified_exponent": 2 }, "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" }, "tra_response": { "recommended_action": "CHALLENGE", "primary_reason": "Three_ds.2.2.article.14", "reasons": [ "Three_ds.2.2.article.14", "Three_ds.2.2.article.16" ], "status": "SUCCESS" } } ``` ## 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" } } ``` ## Related topics - [3D Secure Overview](https://www.marqeta.com/docs/core-api/3ds.md) - [3D Secure in Europe](https://www.marqeta.com/docs/developer-guides/mq-eu-3ds.md) - [About SCA in Europe](https://www.marqeta.com/docs/developer-guides/mq-eu-about-sca.md) - [3D Secure Setup](https://www.marqeta.com/docs/developer-guides/3ds-setup.md) - [3D Secure Risk Engine Schema](https://www.marqeta.com/docs/developer-guides/3ds-risk-engine-schema.md)