/
35 minute read
August 11, 2023

3D Secure

The Three-Domain Secure (3D Secure or 3DS) API provides a decision service that accepts scoring events from jCard and evaluates whether to apply strong customer authentication (SCA) with 3DS or to exempt. This implementation is based on the EMV 3-D Secure Protocol and Core Functions Specification. For more information, see the specification on the EMVCo website.

The 3DS API is RESTful, so it uses HTTP methods (POST, PUT, GET) to perform functions on objects. For example, to determine whether to send an SCA challenge, send a POST request to the /three-ds/decision endpoint. Some requests include data in their message body. The 3DS API requires that data be in JSON format.

The 3DS API provides endpoints that enable you to:

  • Delegate decisioning – determine whether to send an SCA.

  • Notify a 3DS completion status.

  • Receive an Advanced Authentication challenge.

  • Update an authentication result to Marqeta.

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

Delegate decisioning - determine whether to send an SCA

Action: POST
Endpoint: /three-ds/decision

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

Request header

Fields Description

X-VERSION

char
Optional

Identifies the version of the service and data structures used. This value is not the same as the 3DS version. If omitted, the latest version is assumed.

Allowable Values:

A valid version number.

Body field details

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

The ThreeDSDecisionRequest object

Fields Description

acs_transaction_id

string
Required

Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: acsTransID)

Allowable Values:

36 char max

type

string
Optional

Authentication type that determines the action to be taken by the receiver of this message.

Allowable Values:

authentication.decision, authentication.result

state

string
Required

Status of the requested authentication.

Allowable Values:

PENDING, SUCCESS, FAILED

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
Optional

Authentication request time, expressed in UTC.

Allowable Values:

Format: yyyy-MM-dd

network

string
Optional

The card network associated with this authentication/decision request.

Allowable Values:

VISA, MASTERCARD

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:

authentication_request_type

string
Optional

Indicates the type of authentication request. (EMVCo reference: threeDSRequestorAuthenticationInd)

Allowable Values:

PAYMENT, RECURRING, INSTALLMENT, ADD_CARD, MAINTAIN_CARD, EMV_CARDHOLDER_VERIFICATION

requester

string
Optional

The requestor details.

Allowable Values:

server

string
Optional

The server details.

Allowable Values:

client_browser

string
Optional

Client browser details.

Allowable Values:

device

string
Optional

The device details.

Allowable Values:

cardholder_account

string
Optional

Contains additional information about the cardholder’s account, as provided by the 3DS Requestor.

Allowable Values:

directory_server

string
Optional

Describes information from the Directory Services (DS) in the network.

Allowable Values:

transaction

string
Required

Contains information about how the payment is being made.

Allowable Values:

card_acceptor

string
Required

Details about the merchant with which this transaction is being conducted.

Allowable Values:

whitelist

string
Optional

Details regarding the allow list.

Allowable Values:

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 CRes message or error message. The CRes message is posted by the ACS through the cardholder browser at the end of the challenge and receipt of the RRes message. (EMVCo reference: notificationURL)

Allowable Values:

256 char max

Example:
https://www.example.com/path/to/resource

challenge_preference

string
Optional

Indicates whether a challenge is requested for this transaction. If missing, presume no-preference. (EMVCo reference: threeDSRequestorChallengeInd)

Allowable Values:

NO_CHALLENGE, CHALLENGE, RISK_ALREADY_ANALYZED, DATA_SHARE_ONLY, SCA_ALREADY_PERFORMED, WHITELIST_CHALLENGE, WHITELIST_EXEMPT, MANDATE

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, DO_NOT_USE_DECOUPLED_AUTHENTICATION

name

string
Optional

DS-assigned 3DS Requestor name. Each DS provides a unique name to each 3DS Requestor on an individual basis. (EMVCo reference: threeDSRequestorName)

Allowable Values:

40 char max

customer_care_url

string
Optional

Fully qualified URL of the 3DS Requestor website or customer care site. (EMVCo reference: threeDSRequestorURL)

Allowable Values:

2048 char max

Example:
https://help.example.com/customer-service

request_type

string
Optional

Indicates the type of 3RI request. (EMVCo reference: threeRIInd)

Allowable Values:

RECURRING, INSTALLMENT, ADD_CARD, MAINTAIN_CARD, ACCOUNT_VERIFICATION, SPLIT_OR_DELAYED_SHIPMENT, TOP_UP, MAIL_ORDER, TELEPHONE_ORDER, WHITELIST_STATUS_CHECK, OTHER_PAYMENT

cardholder_authentication_by_merchant

object
Optional

Cardholder authentication details by merchant.

Allowable Values:

prior_cardholder_authentication

object
Optional

Authentication details about the prior cardholder.

Allowable Values:

sdk

object
Optional

SDK details.

Allowable Values:

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, REQUESTOR_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_CREDENTIALS, FIDO, FIDO_WITH_ASSURANCE_SIGNED, SRC_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, CHALLENGED_BY_ACS, ACS_VERIFIED, OTHER

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

boolean
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, BROWSER, THREEDS_REQUESTER_INITIATED

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, CREDIT, DEBIT

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:

account_age

string
Optional

How long the cardholder has had the account with the 3DS Requestor. (EMVCo reference: chAccAgeInd)

Allowable Values:

NO_ACCOUNT, DURING_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

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, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

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, THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

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, THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

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, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

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:

statistics

object
Optional

Cardholder activity statistics.

Allowable Values:

billing_address

object
Optional

Provides details related to the cardholder’s billing address.

Allowable Values:

shipping_address

object
Optional

Provides details related to the cardholder’s shipping address.

Allowable Values:

The phones object

Fields Description

country_code

number
Required

Sometimes called the country prefix or country code, this is the international public telecommunication numbering plan that defines a numbering plan for the worldwide public switched telephone network (PSTN) and some other data networks. See also: https://en.wikipedia.org/wiki/E.164

Allowable Values:

minLength: 1
maxLength: 3

subscriber

string
Required

The phone number without the country code (i.e., the area code, prefix, and subscriber number). Do not add spaces, hyphens, or the + symbol.

Allowable Values:

minLength: 1
maxLength: 15

Example:
5105551212

The statistics object

Fields Description

purchase_count_6_months

integer
Optional

Number of purchases made with this cardholder account during the previous six months. (EMVCo reference: nbPurchaseAccount)

Allowable Values:

min: 0

provision_attempt_count_24_hours

integer
Optional

Number of add card attempts in the last 24 hours. (EMVCo reference: provisionAttemptsDay)

Allowable Values:

min: 0

transactions_count_24_hours

integer
Optional

Number of transactions (successful or abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. (EMVCo reference: txnActivityDay)

Allowable Values:

min: 0

transactions_count_1_year

integer
Optional

Number of transactions (successful or abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. (EMVCo reference: txnActivityYear)

Allowable Values:

min: 0

The directory_server object

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

Fields Description

reference_number

string
Required

EMVCo-assigned unique identifier to track approved DS. (EMVCo reference: dsReferenceNumber)

Allowable Values:

minLength: 1
maxLength: 32

authentication_result_url

string
Optional

URL of the DS to which the ACS will send the RReq if a challenge occurs. (EMVCo reference: dsURL)

Allowable Values:

A valid URL.
2048 char max

Example:
https://server.example.com/path

The recurring object

Fields Description

expiration_date

string
Conditionally required

Date after which no further authorizations will be performed. Required when request_type is set to RECURRING or INSTALLMENT. (EMVCo reference: recurringExpiry)

Allowable Values:

Format: yyyy-MM-dd

Example:
2021-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, NON_PAYMENT

sub_type

string
Optional

Identifies the type of transaction being authenticated. (EMVCo reference: transType)

Allowable Values:

PURCHASE, ACCOUNT_VERIFICATION, ACCOUNT_FUNDING, QUASI_CASH, PREPAID_ACTIVATION_AND_LOAD

amount

number
Optional

Purchase amount in minor units of currency with all punctuation removed. For example, a purchase for $1.99 would be 199. (EMVCo reference: purchaseAmount)

Allowable Values:

A valid number.

currency_code

number
Optional

ISO 4217 three-digit currency code of the payment or purchased gift card. See https://www.iso.org/iso-4217-currency-codes.html

Allowable Values:

minLength: 3
maxLength: 3

exponent

integer
Optional

Minor units of currency value, as specified in the ISO 4217 currency exponent. For USD, the value is 2. (EMVCo reference: purchaseExponent)

Allowable Values:

A valid ISO 4217 code.

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, DIRECTORY_SERVER

recurring

object
Optional

Authorization and expiration details for transactions of the recurring type.

Allowable Values:

The card_acceptor object

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

acquirer_bin

string
Conditionally required

Acquiring institution identification code, as assigned by the DS receiving the AReq message. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerBIN)

Allowable Values:

11 char max

merchant_id

string
Conditionally required

Acquirer-assigned merchant identifier. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerMerchantID)

Allowable Values:

35 char max

merchant_category_code

string
Optional

Merchant Category Code (MCC). DS-specific code describing the merchant’s type of product or service. (EMVCo reference: mcc)

Allowable Values:

minLength: 4
maxLength: 4

country

string
Optional

ISO 3166-1 three-digit country code of the merchant address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2

Allowable Values:

minLength: 2
maxLength: 3

name

string
Optional

Merchant name assigned by the acquirer or payment system. (EMVCo reference: merchantName)

Allowable Values:

40 char max

risk_indicators

object
Optional

Merchant’s assessment of the level of fraud risk for the specific authentication, as applies to both the cardholder and the authentication being performed. (EMVCo reference: merchantRiskIndicator)

Allowable Values:

The risk_indicators object

Fields Description

delivery

object
Optional

Contains delivery details.

Allowable Values:

gift_cards

object
Optional

If the purchase included buying gift cards, this object includes information about those gift cards.

Allowable Values:

pre_order

object
Optional

If a pre-order, includes information about the pre-order.

Allowable Values:

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, OTHER_VERIFIED_ADDRESS, UNVERIFIED_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TRAVEL_AND_EVENT_TICKETS, OTHER

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, SAME_DAY_SHIPPING, OVERNIGHT_SHIPPING, TWO_DAYS_OR_MORE_SHIPPING

The gift_cards object

Fields Description

currency_code

number
Optional

ISO 4217 three-digit currency code of the payment or purchased gift card. See also: https://www.iso.org/iso-4217-currency-codes.html

Allowable Values:

minLength: 3
maxLength: 3

loaded_amount

number
Optional

For a prepaid or gift card purchase, the total purchase amount of prepaid or gift cards in major units (for example, a purchase of $123.45 is 12345). (EMVCo reference: giftCardAmount)

Allowable Values:

minimum: 0
maximum: 2147483647

number_of_cards_purchased

integer
Optional

For a prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased. EMVCo reference: giftCardCount)

Allowable Values:

minimum: 0
maximum: 99

The pre_order object

Fields Description

merchandise_available_date

string
Optional

For a pre-ordered purchase, the expected date when the merchandise will be available. Merchants sometimes create pre-orders to hold an order for customers whose 3DS SCA is pending. This is why the "pre-order" exists and the merchandise availability is immediate. (EMVCo reference: preOrderDate)

Allowable Values:

Format: yyyy-MM-dd

merchandise_availability

string
Optional

Indicates whether the cardholder is placing an order for merchandise with a future availability or release date. (EMVCo reference: preOrderPurchaseInd)

Allowable Values:

IMMEDIATE, FUTURE

The whitelist object

Fields Description

status

string
Optional

Enables the communication of trusted beneficiary/whitelist (i.e., allow list) status between the ACS, the DS, and the 3DS Requestor. (EMVCo reference: whiteListStatus)

Allowable Values:

WHITELISTED, NOT_WHITELISTED, NOT_ELIGIBLE, PENDING, REJECTED, UNKNOWN

source

string
Optional

The whitelist (i.e., allow list) status source. (EMVCo reference: whiteListStatusSource)

Allowable Values:

3DS_SERVER, DIRECTORY_SERVER, ACS

The AddressPhysical object

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

Fields Description

address1

string
Optional

First line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address.

Allowable Values:

50 char max

address2

string
Optional

Second line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address.

Allowable Values:

50 char max

address3

string
Optional

Third line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address.

Allowable Values:

50 char max

city

string
Optional

City of the cardholder’s shipping/billing address.

Allowable Values:

50 char max

state

string
Optional

ISO 3166-2 country subdivision code associated with the state or province of the cardholder’s shipping/billing address. See also: https://en.wikipedia.org/wiki/ISO_3166-2:US

Allowable Values:

Two- or three-digit state code

post_code

string
Optional

ZIP or postal code of the cardholder’s shipping/billing address.

Allowable Values:

16 char max

country

string
Optional

ISO 3166-1 three-digit country code of the cardholder’s shipping/billing address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2

Allowable Values:

Two- or three-digit country code

The card_expiry_date object

Fields Description

two_digit_year

integer
Required

Two-digit year when this card expires. For example, if the card expires in the year 2023, this value is 23.

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 either a CHALLENGE or EXEMPT decision. 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 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, EXEMPT

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:

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
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

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.decision, authentication.result

state

string
Optional

Status of the requested authentication.

Allowable Values:

PENDING, SUCCESS, FAILED

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, BIOMETRIC_FINGERPRINT, VOICE_RECOGNITION, IN_APP_LOGIN, AUDIO_CALL, VIDEO_CALL, OTP_SMS, OTP_EMAIL, KNOWLEDGE_BASED, OTHER

authentication_result

string
Optional

Result of the authentication performed.

Allowable Values:

SUCCESS, FAILED, CANCELLED, NOT_AUTHENTICATED

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, TIMED_OUT_DECOUPLED_AUTHENTICATION, TIMED_OUT_AT_ACS, TIMED_OUT_AT_ACS_NO_CREQ, TIMED_OUT_AT_SDK, UNKNOWN

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
Copied

Is this helpful?

Yes
No

Sample response

JSON
Copied

Is this helpful?

Yes
No

Receive an Advanced Authentication challenge

Action: POST
Endpoint: /three-ds/authentication

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

Request header

Fields Description

X-VERSION

char
Required

Identifies the version of the service and data structures used. This value is not the same as the 3DS version. If omitted, the latest version is assumed.

Allowable Values:

A valid version number.

Body field details

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

The ThreeDSAuthenticationRequest object

Fields Description

acs_transaction_id

string
Required

Universally unique transaction identifier assigned by the ACS to identify a single transaction. (EMVCo reference: acsTransID)

Allowable Values:

36 char max

type

string
Required

Authentication type that determines the action to be taken by the receiver of this message.

Allowable Values:

authentication.challenge.out_of_band, authentication.challenge.decoupled

state

string
Required

Status of the requested authentication.

Allowable Values:

PENDING, SUCCESS, FAILED

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
Optional

Authentication request time, expressed in UTC.

Allowable Values:

Format: yyyy-MM-dd

network

string
Required

The card network associated with this authentication/decision request.

Allowable Values:

VISA, MASTERCARD

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, RECURRING, INSTALLMENT, ADD_CARD, MAINTAIN_CARD, EMV_CARDHOLDER_VERIFICATION

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:

card_acceptor

object
Required

Details about the merchant with which this transaction is being conducted.

Allowable Values:

three_ds_requestor_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_requestor_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, NON_PAYMENT

sub_type

string
Optional

Identifies the type of transaction being authenticated. (EMVCo reference: transType)

Allowable Values:

PURCHASE, ACCOUNT_VERIFICATION, ACCOUNT_FUNDING, QUASI_CASH, PREPAID_ACTIVATION_AND_LOAD

amount

number
Optional

Purchase amount in minor units of currency with all punctuation removed. For example, a purchase for $1.99 would be 199. (EMVCo reference: purchaseAmount)

Allowable Values:

A valid number.

currency_code

number
Optional

ISO 4217 three-digit currency code of the payment or purchased gift card. See https://www.iso.org/iso-4217-currency-codes.html

Allowable Values:

minLength: 3
maxLength: 3

exponent

integer
Optional

Minor units of currency value, as specified in the ISO 4217 currency exponent. For USD, the value is 2. (EMVCo reference: purchaseExponent)

Allowable Values:

A valid ISO 4217 code.

The card_acceptor object

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

acquirer_bin

string
Conditionally required

Acquiring institution identification code, as assigned by the DS receiving the AReq message. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerBIN)

Allowable Values:

11 char max

merchant_id

string
Conditionally required

Acquirer-assigned merchant identifier. Required when messageCategory = 01; optional when messageCategory = 02. (EMVCo reference: acquirerMerchantID)

Allowable Values:

35 char max

merchant_category_code

string
Optional

Merchant Category Code (MCC). DS-specific code describing the merchant’s type of product or service. (EMVCo reference: mcc)

Allowable Values:

minLength: 4
maxLength: 4

country

string
Optional

ISO 3166-1 three-digit country code of the merchant address. See also: https://www.iso.org/iso-3166-country-codes.html and https://en.wikipedia.org/wiki/ISO_3166-2

Allowable Values:

minLength: 2
maxLength: 3

name

string
Optional

Merchant name assigned by the acquirer or payment system. (EMVCo reference: merchantName)

Allowable Values:

40 char max

Response codes

Code Description

200

Successful acknowledgement of a 3DS Advanced Authentication request.

400

Invalid authentication payload detected.

401

Unauthorized 3DS Authentication request.

403

Forbidden 3DS Authentication request.

500

Internal server error, unable to process the request.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response

JSON
Copied

Is this helpful?

Yes
No

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, BIOMETRIC_FINGERPRINT, VOICE_RECOGNITION, IN_APP_LOGIN, AUDIO_CALL, VIDEO_CALL, OTP_SMS, OTP_EMAIL, KNOWLEDGE_BASED, OTHER

authentication_result

string
Required

Result of the authentication performed.

Allowable Values:

SUCCESS, FAILED, CANCELLED, NOT_AUTHENTICATED

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, TIMED_OUT_DECOUPLED_AUTHENTICATION, UNKNOWN

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
Copied

Is this helpful?

Yes
No

Sample response

JSON
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter