POST//
Stand up this endpoint to receive a cardholder challenge from Marqeta using Advanced Authentication. An Advanced Authentication request prompts you to challenge the cardholder using advanced methods such as biometrics or voice recognition. For details on the Advanced Authentication process, see Advanced Authentication and Advanced authentication lifecycle.
Request header
| Fields | Description |
|---|---|
| X-VERSION char Required | Identifies the version of the service and data structures used. This value is not the same as the 3DS version. If omitted, the latest version is assumed. Allowable Values: A valid version number. |
Body field details
The following table describes the payload required to authenticate a request.The ThreeDSAuthenticationRequest object
| Fields | Description |
|---|---|
| acs_transaction_id string Required | Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: acsTransID)Allowable Values: 36 char max |
| type string Required | Authentication type that determines the action to be taken by the receiver of this message. Allowable Values: authentication.challenge.out_of_band, authentication.challenge.decoupled |
| state string Required | Status of the requested authentication. Allowable Values: - PENDING - Authentication request is pending processing- SUCCESS - Authentication completed successfully- FAILED - Authentication failed or was rejected |
| user_token string Required | Marqeta-assigned unique user token identifying the user. Allowable Values: 32 char max |
| acting_user_token string Required | Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 32 char max |
| card_token string Required | Marqeta-assigned unique card token identifying the user. Allowable Values: 32 char max |
| created_time string Required | Authentication request time, expressed as an ISO-8601 UTC timestamp. Allowable Values: Format: yyyy-MM-ddThh:mm:ss.sssZ |
| network string Required | The card network associated with this authentication/decision request. Allowable Values: - VISA - Visa card network transactions- MASTERCARD - Mastercard network transactions |
| message_version string Required | The 3DS protocol version used by the 3DS Requestor. (EMVCo reference: messageversion)Allowable Values: minLength: 5 maxLength: 8 |
| authentication_request_type string Optional | Indicates the type of authentication request. (EMVCo reference: threeDSRequestorAuthenticationInd)Allowable Values: - PAYMENT - Payment transaction authentication- RECURRING - Recurring payment setup or processing- INSTALLMENT - Installment payment authentication- ADD_CARD - Adding a new card to cardholder account- MAINTAIN_CARD - Maintaining or updating existing card information- EMV_CARDHOLDER_VERIFICATION - EMV cardholder verification method |
| max_response_time number Required | Indicates the maximum period of time, in minutes, that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction. (EMVCo reference: threeDSRequestorDecMaxTime)Allowable Values: A five-digit number with a value between 1 and 10080, inclusive, without leading zeros.Default value: 8 |
| transaction object Required | Contains information about how the payment is being made. Allowable Values: See The transaction object. |
| card_acceptor object Required | Details about the merchant with which this transaction is being conducted. Allowable Values: See The card_acceptor object. |
| three_ds_requester_app_url string Optional | The fully qualified URL of the merchant application that initiated the 3D Secure authentication request. Allowable Values: 255 char max |
| three_ds_requester_url string Optional | The fully qualified URL of the merchant’s website or customer care site. Allowable Values: 255 char max |
The transaction object
Contains information about how the payment is being made.| Fields | Description |
|---|---|
| transaction_type string Optional | Identifies the category of the message for a specific use case. (EMVCo reference: messageCategory)Allowable Values: PAYMENT - Payment transaction requiring authorizationNON_PAYMENT - Non-payment transaction, such as account verification |
| sub_type string Optional | Identifies the type of transaction being authenticated. (EMVCo reference: transType)Allowable Values: - PURCHASE - Goods or services purchase transaction- ACCOUNT_VERIFICATION - Account verification without payment- ACCOUNT_FUNDING - Loading funds to an account- QUASI_CASH - Cash-equivalent transaction, such as money orders- PREPAID_ACTIVATION_AND_LOAD - Prepaid card activation and initial loading |
| amount number Optional | Purchase amount in minor units of currency with all punctuation removed. For example, a purchase for $1.99 would be 199. (EMVCo reference: purchaseAmount)Allowable Values: Valid number |
| currency_code number Optional | ISO 4217 three-digit currency code of the payment or purchased gift card. See https://www.iso.org/iso-4217-currency-codes.html Allowable Values: minLength: 3 maxLength: 3 |
| exponent integer Optional | Minor units of currency value, as specified in the ISO 4217 currency exponent. For USD, the value is 2. (EMVCo reference: purchaseExponent)Allowable Values: Valid ISO 4217 code See https://www.iso.org/iso-4217-currency-codes.html |
The card_acceptor object
Warning
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.
| Fields | Description |
|---|---|
| acquirer_bin string Conditionally required | Acquiring institution identification code, as assigned by the DS receiving the AReq message. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerBIN)Allowable Values: 11 char max |
| merchant_id string Conditionally required | Acquirer-assigned merchant identifier. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerMerchantID)Allowable Values: 35 char max |
| merchant_category_code string Optional | Merchant Category Code (MCC). DS-specific code describing the merchant’s type of product or service. (EMVCo reference: mcc)Allowable Values: minLength: 4 maxLength: 4 |
| country string Optional | ISO 3166-1 three-digit country code of the merchant address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2 Allowable Values: minLength: 2 maxLength: 3 |
| name string Optional | Merchant name assigned by the acquirer or payment system. (EMVCo reference: merchantName)Allowable Values: 40 char max |
Response codes
| Code | Description |
|---|---|
| 200 | Successful acknowledgement of a 3DS Advanced Authentication request. |
| 400 | Invalid authentication payload detected. |
| 401 | Unauthorized 3DS Authentication request. |
| 403 | Forbidden 3DS Authentication request. |
| 500 | Internal server error, unable to process the request. |
Sample request body
JSON
{
"acs_transaction_id": "acs_transaction_id",
"type": "authentication.challenge.out_of_band",
"state": "PENDING",
"user_token": "user_token",
"acting_user_token": "acting_user_token",
"card_token": "card_token",
"created_time": "2025-06-08T17:49:56.594Z",
"network": "VISA",
"message_version": "2.1.0",
"authentication_request_type": "PAYMENT",
"max_response_time": 7,
"transaction": {
"transaction_type": "PAYMENT",
"sub_type": "PURCHASE",
"amount": 199,
"currency_code": 978,
"exponent": 2
},
"card_acceptor": {
"acquirer_bin": "acquirer_bin",
"merchant_id": "merchant_id",
"merchant_category_code": "5734",
"country": "826",
"name": "acceptor_name"
}
}
Sample response
JSON
200 OK