3D Secure

X-VERSION

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.

A valid version number.

notification_url

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)

256 char max

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

challenge_preference

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

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

decoupled_challenge_preference

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)

DECOUPLED_AUTHENTICATION_PREFERRED, DO_NOT_USE_DECOUPLED_AUTHENTICATION

name

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

40 char max

customer_care_url

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

2048 char max

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

request_type

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

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

Cardholder authentication details by merchant.

See The cardholder_authentication_by_merchant object.

prior_cardholder_authentication

Authentication details about the prior cardholder.

See The prior_cardholder_authentication object.

sdk

SDK details.

See The sdk object.

data

Data that documents and supports a specific authentication process. (EMVCo reference: threeDSReqAuthData)

20,000 char max

type

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)

NO_AUTHENTICATION, REQUESTOR_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_CREDENTIALS, FIDO, FIDO_WITH_ASSURANCE_SIGNED, SRC_ASSURANCE_DATA

time

Date and time of the cardholder authentication, expressed in UTC. (EMVCo reference: threeDSReqAuthTimestamp)

yyyy-MM-dd’T’HH:mm:ss.SSSZ

status

Indicates whether the 3DS method successfully completed. If missing, then this data is unavailable. (EMVCo reference: threeDSCompInd)

true, false

data

Data that documents and supports a specific authentication process. (EMVCo reference: threeDSReqPriorAuthData)

2048 char max

type

Mechanism previously used by the cardholder to authenticate to the 3DS Requestor. (EMVCo reference: threeDSReqPriorAuthMethod)

FRICTIONLESS_AUTHENTICATION_BY_ACS, CHALLENGED_BY_ACS, ACS_VERIFIED, OTHER

time

Date and time of the previous cardholder authentication, expressed in UTC. (EMVCo reference: threeDSReqPriorAuthTimestamp)

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

acs_transaction_id

Provides additional information to the ACS to determine the best approach for handling a request. (EMVCo reference: threeDSReqPriorRef)

36 char max

application_id

Universally unique ID created upon all installations of the 3DS Requestor app on a consumer device. (EMVCo reference: sdkAppID)

36 char max

reference_number

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)

32 char max

reference_number

Unique identifier assigned by the EMVCo secretariat upon testing and approval. (EMVCo reference: threeDSServerRefNumber)

32 char max

operator_id

DS-assigned 3DS Server identifier. Each DS provides a unique ID to each 3DS Server on an individual basis. (EMVCo reference: threeDSServerOperatorID)

32 char max

accept_headers

Exact content of the HTTP accept headers, as sent to the 3DS Requestor from the cardholder’s browser. (EMVCo reference: browserAcceptHeader)

2048 char max

ip_address

IPv4 or IPv6 address of the browser, as returned by the HTTP headers to the 3DS Requestor. (EMVCo reference: browserIP)

45 char max

is_java_enabled

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)

true, false

is_javascript_enabled

Indicates the ability of the cardholder’s browser to execute JavaScript. (EMVCo reference: browserJavascriptEnabled)

true, false

language

Value representing the browser language, as defined in IETF BCP47. Returned from the navigator.language property. (EMVCo reference: browserLanguage)

minLength: 1
maxLength: 8

timezone_offset_in_minutes

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)

minimum: -720
maximum: 720

user_agent

The exact contents of the HTTP user-agent header. (EMVCo reference: browserUserAgent)

2048 char max

channel

Indicates the type of channel interface being used to initiate the transaction. (EMVCo reference: deviceChannel)

APP_BASED, BROWSER, THREEDS_REQUESTER_INITIATED

additional_data

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)

minLength: 1
maxLength: 64,000

identifier

Account ID that will be used in the authorization request for payment transactions. Can be represented by the PAN or token. (EMVCo reference: acctID)

minLength: 13
maxLength: 19

name

Name of the cardholder performing the transaction. (EMVCo reference: cardholderName)

A valid string.

email

Email address associated with the account: Either entered by the cardholder, or on file with the 3DS Requestor. (EMVCo reference: email)

254 char max

account_type

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)

NOT_AVAILABLE, CREDIT, DEBIT

card_expiry_date

Expiry date of the PAN or token supplied by the cardholder to the 3DS Requestor. (EMVCo reference: cardExpiryDate)

See The card_expiry_date object.

account_age

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

NO_ACCOUNT, DURING_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

last_updated_date

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)

Format: yyyy-MM-dd

last_updated_duration

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)

THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

date_created

Date when the cardholder opened the account with the 3DS Requestor. (EMVCo reference: chAccDate)

Format: yyyy-MM-dd

password_changed_date

Date when the cardholder’s account with the 3DS Requestor last had a password change or account reset. (EMVCo reference: chAccPwChange)

Format: yyyy-MM-dd

password_changed_duration

How long since the cardholder’s account with the 3DS Requestor last had a password change or account reset. (EMVCo reference: chAccPwChangeInd)

NO_CHANGE, THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

enrolled_date

Date when the payment account was enrolled in the cardholder’s account with the 3DS Requestor. (EMVCo reference: paymentAccAge)

Format: yyyy-MM-dd

enrolled_duration

How long since the payment account was enrolled in the cardholder’s account with the 3DS Requestor. (EMVCo reference: paymentAccInd)

NOT_ENROLLED, THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

shipping_address_first_used_date

Date when the shipping address indicated for this transaction was first used with the 3DS Requestor. (EMVCo reference: shipAddressUsage)

Format: yyyy-MM-dd

shipping_address_first_used_duration

How long since the shipping address indicated for this transaction was first used with the 3DS Requestor. (EMVCo reference: shipAddressUsageInd)

THIS_TRANSACTION, FEWER_THAN_30_DAYS, BETWEEN_30_AND_60_DAYS, GREATER_THAN_60_DAYS

ship_to_name_is_cardholder_name

Indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.

true, false

experienced_suspicious_activity

Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. (EMVCo reference: suspiciousAccActivity)

true, false

phones

A list of phone numbers for this cardholder account. Keys can include home, mobile, and work and will be included if they are present.

See The phones object.

statistics

Cardholder activity statistics.

See The statistics object.

billing_address

Provides details related to the cardholder’s billing address.

See The AddressPhysical object.

shipping_address

Provides details related to the cardholder’s shipping address.

See The AddressPhysical object.

country_code

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

minLength: 1
maxLength: 3

subscriber

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

minLength: 1
maxLength: 15

Example:
5105551212

purchase_count_6_months

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

min: 0

provision_attempt_count_24_hours

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

min: 0

transactions_count_24_hours

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)

min: 0

transactions_count_1_year

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)

min: 0

reference_number

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

minLength: 1
maxLength: 32

authentication_result_url

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

A valid URL.
2048 char max

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

expiration_date

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

Format: yyyy-MM-dd

Example:
2021-07-21

minimum_days_between_authorizations

Indicates the minimum number of days between authorizations. Required when request_type is set to RECURRING or INSTALLMENT. (EMVCo reference: recurringFrequency)

minimum: 0
maximum: 9999

transaction_type

Identifies the category of the message for a specific use case. (EMVCo reference: messageCategory)

PAYMENT, NON_PAYMENT

sub_type

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

PURCHASE, ACCOUNT_VERIFICATION, ACCOUNT_FUNDING, QUASI_CASH, PREPAID_ACTIVATION_AND_LOAD

amount

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

A valid number.

currency_code

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

minLength: 3
maxLength: 3

exponent

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

A valid ISO 4217 code.

date

Date and time of the purchase, expressed in UTC. (EMVCo reference: purchaseDate)

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

shipping_address_is_billing_address

Indicates whether the cardholder shipping address and cardholder billing address are the same. (EMVCo reference: addrMatch)

true, false

maximum_permitted_installments

Indicates the maximum number of authorizations permitted for installment payments. (EMVCo reference: purchaseInstalData)

minimum: 1
maximum: 999

detokenisation_source

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)

3DS_SERVER, DIRECTORY_SERVER

recurring

Authorization and expiration details for transactions of the recurring type.

See The recurring object.

acquirer_bin

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

11 char max

merchant_id

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

35 char max

merchant_category_code

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

minLength: 4
maxLength: 4

country

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

minLength: 2
maxLength: 3

name

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

40 char max

risk_indicators

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)

See The risk_indicators object.

delivery

Contains delivery details.

See The delivery object.

gift_cards

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

See The gift_cards object.

pre_order

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

See The pre_order object.

is_reorder

Indicates whether the cardholder is reordering previously purchased merchandise. If missing, then this is not a reorder. (EMVCo reference: reorderItemsInd)

true, false

shipping_indicator

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)

BILLING_ADDRESS, OTHER_VERIFIED_ADDRESS, UNVERIFIED_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TRAVEL_AND_EVENT_TICKETS, OTHER

email

For electronic delivery, the email address to which the merchandise was delivered. (EMVCo reference: deliveryEmailAddress)

254 char max

timeframe

Indicates the merchandise delivery timeframe. (EMVCo reference: deliveryTimeframe)

ELECTRONIC, SAME_DAY_SHIPPING, OVERNIGHT_SHIPPING, TWO_DAYS_OR_MORE_SHIPPING

currency_code

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

minLength: 3
maxLength: 3

loaded_amount

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)

minimum: 0
maximum: 2147483647

number_of_cards_purchased

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

minimum: 0
maximum: 99

merchandise_available_date

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)

Format: yyyy-MM-dd

merchandise_availability

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

IMMEDIATE, FUTURE

status

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

WHITELISTED, NOT_WHITELISTED, NOT_ELIGIBLE, PENDING, REJECTED, UNKNOWN

source

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

3DS_SERVER, DIRECTORY_SERVER, ACS

address1

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

50 char max

address2

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

50 char max

address3

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

50 char max

city

City of the cardholder’s shipping/billing address.

50 char max

state

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

Two- or three-digit state code

post_code

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

16 char max

country

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

Two- or three-digit country code

two_digit_year

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

Two-digit integer

month

Month of the year when this card expires. For example, if the card expires in February, this value is 2.

minimum: 1
maximum: 12

acs_transaction_id

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)

36 char max

type

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

authentication.decision

recommended_action

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)

CHALLENGE, EXEMPT

model

Which model was used to score the request.

minLength: 2
maxLength: 64

Example:
FraudModel_inttest_1534190172

challenge_score

The confidence interface between [0..1] (0 being least confident and 1 being most confident) in the recommended_action.

Example:
0.89

reasons

Reasons why the challenge or exemption was recommended.

A valid array.

primary_reason

Primary reason why the challenge or exemption was recommended.

255 char max

use_otp_challenge

Indicates if the Marqeta OTP challenge will be used to authenticate the cardholder. If not sent, the program-level challenge preference will be used.

true, false

api

Information regarding the API call and how it was handled.

See DecisionServiceResponse.

version_used

The version of the API that the server supports and is using. Do not simply echo back the X-VERSION header.

Pattern: ^\d+\.\d+\.\d+$

Example:
31.41.5

errors

The error with a message that might be helpful when debugging.

255 char max

version_used

The version of the API that the server supports and is using. Do not simply echo back the X-VERSION header.

Pattern: ^\d+\.\d+\.\d+$

Example:
31.41.5

X-VERSION

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.

A valid version number.

transaction_type

Identifies the category of the message for a specific use case. (EMVCo reference: messageCategory)

PAYMENT, NON_PAYMENT

sub_type

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

PURCHASE, ACCOUNT_VERIFICATION, ACCOUNT_FUNDING, QUASI_CASH, PREPAID_ACTIVATION_AND_LOAD

amount

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

A valid number.

currency_code

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

minLength: 3
maxLength: 3

exponent

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

A valid ISO 4217 code.

acquirer_bin

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

11 char max

merchant_id

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

35 char max

merchant_category_code

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

minLength: 4
maxLength: 4

country

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

minLength: 2
maxLength: 3

name

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

40 char max