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
Copy section link
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
Copy section link
Fields | Description |
---|---|
X-VERSION
char
|
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
Copy section link
The following table describes the payload required to score an access control server (ACS) request.
The ThreeDSDecisionRequest object
Copy section link
Fields | Description |
---|---|
acs_transaction_id
string
|
Universally unique transaction identifier assigned by the ACS to identify a single transaction.
(EMVCo reference: Allowable Values: 36 char max |
type
string
|
Authentication type that determines the action to be taken by the receiver of this message. Allowable Values:
|
state
string
|
Status of the requested authentication. Allowable Values:
|
user_token
string
|
Marqeta-assigned unique user token identifying the user. Allowable Values: 36 char max |
acting_user_token
string
|
Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 36 char max |
card_token
string
|
Marqeta-assigned unique card token identifying the user. Allowable Values: 36 char max |
created_time
string
|
Authentication request time, expressed in UTC. Allowable Values: Format: yyyy-MM-dd |
network
string
|
The card network associated with this authentication/decision request. Allowable Values:
|
message_version
string
|
The 3DS protocol version used by the 3DS Requestor.
(EMVCo reference: Allowable Values: minLength: 5 |
message_extension
string
|
The 3DS message extension component.
(EMVCo reference: Allowable Values: |
authentication_request_type
string
|
Indicates the type of authentication request.
(EMVCo reference: Allowable Values:
|
requester
string
|
The requestor details. Allowable Values: See The requester object. |
server
string
|
The server details. Allowable Values: See The server object. |
client_browser
string
|
Client browser details. Allowable Values: |
device
string
|
The device details. Allowable Values: See The device object. |
cardholder_account
string
|
Contains additional information about the cardholder’s account, as provided by the 3DS Requestor. Allowable Values: |
directory_server
string
|
Describes information from the Directory Services (DS) in the network. Allowable Values: |
transaction
string
|
Contains information about how the payment is being made. Allowable Values: |
card_acceptor
string
|
Details about the merchant with which this transaction is being conducted. Allowable Values: |
whitelist
string
|
Details regarding the allow list. Allowable Values: See The whitelist object. |
The message_extension object
Copy section link
Fields | Description |
---|---|
name
string
|
Name of the extension dataset, as defined by the extension owner. Allowable Values: 64 char max |
id
string
|
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
|
Indicates whether the recipient must understand the contents of the extension to interpret the entire message.
(EMVCo reference: Allowable Values:
|
data
string
|
Data carried in the extension. Allowable Values: 8059 char max |
The requester object
Copy section link
Fields | Description |
---|---|
notification_url
string
|
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: Allowable Values: 256 char max Example: |
challenge_preference
string
|
Indicates whether a challenge is requested for this transaction.
If missing, presume no-preference.
(EMVCo reference: Allowable Values:
|
decoupled_challenge_preference
string
|
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: Allowable Values:
|
name
string
|
DS-assigned 3DS Requestor name.
Each DS provides a unique name to each 3DS Requestor on an individual basis.
(EMVCo reference: Allowable Values: 40 char max |
customer_care_url
string
|
Fully qualified URL of the 3DS Requestor website or customer care site.
(EMVCo reference: Allowable Values: 2048 char max Example: |
request_type
string
|
Indicates the type of 3RI request.
(EMVCo reference: Allowable Values:
|
cardholder_authentication_by_merchant
object
|
Cardholder authentication details by merchant. Allowable Values: |
prior_cardholder_authentication
object
|
Authentication details about the prior cardholder. Allowable Values: |
sdk
object
|
SDK details. Allowable Values: See The sdk object. |
The cardholder_authentication_by_merchant object
Copy section link
Fields | Description |
---|---|
data
string
|
Data that documents and supports a specific authentication process.
(EMVCo reference: Allowable Values: 20,000 char max |
type
string
|
Value representing the signature verification performed by the DS on the mechanism used by the cardholder to authenticate to the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
time
string
|
Date and time of the cardholder authentication, expressed in UTC.
(EMVCo reference: Allowable Values: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
status
boolean
|
Indicates whether the 3DS method successfully completed.
If missing, then this data is unavailable.
(EMVCo reference: Allowable Values:
|
The prior_cardholder_authentication object
Copy section link
Fields | Description |
---|---|
data
string
|
Data that documents and supports a specific authentication process.
(EMVCo reference: Allowable Values: 2048 char max |
type
string
|
Mechanism previously used by the cardholder to authenticate to the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
time
string
|
Date and time of the previous cardholder authentication, expressed in UTC.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
acs_transaction_id
boolean
|
Provides additional information to the ACS to determine the best approach for handling a request.
(EMVCo reference: Allowable Values: 36 char max |
The sdk object
Copy section link
Fields | Description |
---|---|
application_id
string
|
Universally unique ID created upon all installations of the 3DS Requestor app on a consumer device.
(EMVCo reference: Allowable Values: 36 char max |
reference_number
string
|
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: Allowable Values: 32 char max |
The server object
Copy section link
Fields | Description |
---|---|
reference_number
string
|
Unique identifier assigned by the EMVCo secretariat upon testing and approval.
(EMVCo reference: Allowable Values: 32 char max |
operator_id
string
|
DS-assigned 3DS Server identifier.
Each DS provides a unique ID to each 3DS Server on an individual basis.
(EMVCo reference: Allowable Values: 32 char max |
The client_browser object
Copy section link
Fields | Description |
---|---|
accept_headers
string
|
Exact content of the HTTP accept headers, as sent to the 3DS Requestor from the cardholder’s browser.
(EMVCo reference: Allowable Values: 2048 char max |
ip_address
string
|
IPv4 or IPv6 address of the browser, as returned by the HTTP headers to the 3DS Requestor.
(EMVCo reference: Allowable Values: 45 char max |
is_java_enabled
boolean
|
Indicates the ability of the cardholder’s browser to execute Java.
Value is returned from the Allowable Values:
|
is_javascript_enabled
boolean
|
Indicates the ability of the cardholder’s browser to execute JavaScript.
(EMVCo reference: Allowable Values:
|
language
string
|
Value representing the browser language, as defined in IETF BCP47.
Returned from the Allowable Values: minLength: 1 |
timezone_offset_in_minutes
integer
|
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 = Allowable Values: minimum: -720 |
user_agent
string
|
The exact contents of the HTTP user-agent header.
(EMVCo reference: Allowable Values: 2048 char max |
The device object
Copy section link
Fields | Description |
---|---|
channel
string
|
Indicates the type of channel interface being used to initiate the transaction.
(EMVCo reference: Allowable Values:
|
additional_data
string
|
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: Allowable Values: minLength: 1 |
The cardholder_account object
Copy section link
Fields | Description |
---|---|
identifier
string
|
Account ID that will be used in the authorization request for payment transactions.
Can be represented by the PAN or token.
(EMVCo reference: Allowable Values: minLength: 13 |
name
string
|
Name of the cardholder performing the transaction.
(EMVCo reference: Allowable Values: A valid string. |
email
string
|
Email address associated with the account: Either entered by the cardholder, or on file with the 3DS Requestor.
(EMVCo reference: Allowable Values: 254 char max |
account_type
string
|
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: Allowable Values:
|
card_expiry_date
string
|
Expiry date of the PAN or token supplied by the cardholder to the 3DS Requestor.
(EMVCo reference: Allowable Values: |
account_age
string
|
How long the cardholder has had the account with the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
last_updated_date
string
|
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: Allowable Values: Format: yyyy-MM-dd |
last_updated_duration
string
|
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: Allowable Values:
|
date_created
string
|
Date when the cardholder opened the account with the 3DS Requestor.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd |
password_changed_date
string
|
Date when the cardholder’s account with the 3DS Requestor last had a password change or account reset.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd |
password_changed_duration
string
|
How long since the cardholder’s account with the 3DS Requestor last had a password change or account reset.
(EMVCo reference: Allowable Values:
|
enrolled_date
string
|
Date when the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd |
enrolled_duration
string
|
How long since the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
shipping_address_first_used_date
string
|
Date when the shipping address indicated for this transaction was first used with the 3DS Requestor.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd |
shipping_address_first_used_duration
string
|
How long since the shipping address indicated for this transaction was first used with the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
ship_to_name_is_cardholder_name
boolean
|
Indicates whether the cardholder name on the account is identical to the shipping name used for this transaction. Allowable Values:
|
experienced_suspicious_activity
boolean
|
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
(EMVCo reference: Allowable Values:
|
phones
object
|
A list of phone numbers for this cardholder account.
Keys can include Allowable Values: See The phones object. |
statistics
object
|
Cardholder activity statistics. Allowable Values: |
billing_address
object
|
Provides details related to the cardholder’s billing address. Allowable Values: |
shipping_address
object
|
Provides details related to the cardholder’s shipping address. Allowable Values: |
The phones object
Copy section link
Fields | Description |
---|---|
country_code
number
|
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 |
subscriber
string
|
The phone number without the country code (i.e., the area code, prefix, and subscriber number).
Do not add spaces, hyphens, or the Allowable Values: minLength: 1 Example: |
The statistics object
Copy section link
Fields | Description |
---|---|
purchase_count_6_months
integer
|
Number of purchases made with this cardholder account during the previous six months.
(EMVCo reference: Allowable Values: min: 0 |
provision_attempt_count_24_hours
integer
|
Number of add card attempts in the last 24 hours.
(EMVCo reference: Allowable Values: min: 0 |
transactions_count_24_hours
integer
|
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: Allowable Values: min: 0 |
transactions_count_1_year
integer
|
Number of transactions (successful or abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
(EMVCo reference: Allowable Values: min: 0 |
The directory_server object
Copy section link
This object describes information from the Directory Services (DS) in the network.
Fields | Description |
---|---|
reference_number
string
|
EMVCo-assigned unique identifier to track approved DS.
(EMVCo reference: Allowable Values: minLength: 1 |
authentication_result_url
string
|
URL of the DS to which the ACS will send the RReq if a challenge occurs.
(EMVCo reference: Allowable Values: A valid URL. Example: |
The recurring object
Copy section link
Fields | Description |
---|---|
expiration_date
string
|
Date after which no further authorizations will be performed.
Required when Allowable Values: Format: yyyy-MM-dd Example: |
minimum_days_between_authorizations
integer
|
Indicates the minimum number of days between authorizations.
Required when Allowable Values: minimum: 0 |
The transaction object
Copy section link
Contains information about how the payment is being made.
Fields | Description |
---|---|
transaction_type
string
|
Identifies the category of the message for a specific use case.
(EMVCo reference: Allowable Values:
|
sub_type
string
|
Identifies the type of transaction being authenticated.
(EMVCo reference: Allowable Values:
|
amount
number
|
Purchase amount in minor units of currency with all punctuation removed.
For example, a purchase for $1.99 would be 199.
(EMVCo reference: Allowable Values: A valid number. |
currency_code
number
|
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 |
exponent
integer
|
Minor units of currency value, as specified in the ISO 4217 currency exponent.
For USD, the value is 2.
(EMVCo reference: Allowable Values: A valid ISO 4217 code. |
date
string
|
Date and time of the purchase, expressed in UTC.
(EMVCo reference: Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
shipping_address_is_billing_address
boolean
|
Indicates whether the cardholder shipping address and cardholder billing address are the same.
(EMVCo reference: Allowable Values:
|
maximum_permitted_installments
integer
|
Indicates the maximum number of authorizations permitted for installment payments.
(EMVCo reference: Allowable Values: minimum: 1 |
detokenisation_source
string
|
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: Allowable Values:
|
recurring
object
|
Authorization and expiration details for transactions of the recurring type. Allowable Values: See The recurring object. |
The card_acceptor object
Copy section link
Warning
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.Fields | Description |
---|---|
acquirer_bin
string
|
Acquiring institution identification code, as assigned by the DS receiving the AReq message.
Required when Allowable Values: 11 char max |
merchant_id
string
|
Acquirer-assigned merchant identifier.
Required when Allowable Values: 35 char max |
merchant_category_code
string
|
Merchant Category Code (MCC).
DS-specific code describing the merchant’s type of product or service.
(EMVCo reference: Allowable Values: minLength: 4 |
country
string
|
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 |
name
string
|
Merchant name assigned by the acquirer or payment system.
(EMVCo reference: Allowable Values: 40 char max |
risk_indicators
object
|
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: Allowable Values: |
The risk_indicators object
Copy section link
Fields | Description |
---|---|
delivery
object
|
Contains delivery details. Allowable Values: See The delivery object. |
gift_cards
object
|
If the purchase included buying gift cards, this object includes information about those gift cards. Allowable Values: |
pre_order
object
|
If a pre-order, includes information about the pre-order. Allowable Values: See The pre_order object. |
is_reorder
boolean
|
Indicates whether the cardholder is reordering previously purchased merchandise.
If missing, then this is not a reorder.
(EMVCo reference: Allowable Values:
|
shipping_indicator
string
|
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: Allowable Values:
|
The delivery object
Copy section link
Fields | Description |
---|---|
email
string
|
For electronic delivery, the email address to which the merchandise was delivered.
(EMVCo reference: Allowable Values: 254 char max |
timeframe
string
|
Indicates the merchandise delivery timeframe.
(EMVCo reference: Allowable Values:
|
The gift_cards object
Copy section link
Fields | Description |
---|---|
currency_code
number
|
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 |
loaded_amount
number
|
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: Allowable Values: minimum: 0 |
number_of_cards_purchased
integer
|
For a prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased.
EMVCo reference: Allowable Values: minimum: 0 |
The pre_order object
Copy section link
Fields | Description |
---|---|
merchandise_available_date
string
|
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: Allowable Values: Format: yyyy-MM-dd |
merchandise_availability
string
|
Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.
(EMVCo reference: Allowable Values:
|
The whitelist object
Copy section link
Fields | Description |
---|---|
status
string
|
Enables the communication of trusted beneficiary/whitelist (i.e., allow list) status between the ACS, the DS, and the 3DS Requestor.
(EMVCo reference: Allowable Values:
|
source
string
|
The whitelist (i.e., allow list) status source.
(EMVCo reference: Allowable Values:
|
The AddressPhysical object
Copy section link
Provides details related to the cardholder’s shipping/billing address.
Fields | Description |
---|---|
address1
string
|
First line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max |
address2
string
|
Second line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max |
address3
string
|
Third line of the street address (or equivalent local portion) of the cardholder’s shipping/billing address. Allowable Values: 50 char max |
city
string
|
City of the cardholder’s shipping/billing address. Allowable Values: 50 char max |
state
string
|
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
|
ZIP or postal code of the cardholder’s shipping/billing address. Allowable Values: 16 char max |
country
string
|
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
Copy section link
Fields | Description |
---|---|
two_digit_year
integer
|
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
|
Month of the year when this card expires. For example, if the card expires in February, this value is 2. Allowable Values: minimum: 1 |
ThreeDSDecisionResponse (response)
Copy section link
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
|
Universally unique transaction identifier assigned by the ACS to identify a single transaction.
Respond with the same value sent in the request.
(EMVCo reference: Allowable Values: 36 char max |
type
string
|
Authentication type that determines the action to be taken by the receiver of this message. Allowable Values:
|
recommended_action
string
|
Whether the ACS system should Allowable Values:
|
model
string
|
Which model was used to score the request. Allowable Values: minLength: 2 Example: |
challenge_score
number
|
The confidence interface between [0..1] (0 being least confident and 1 being most confident) in the Allowable Values: Example: |
reasons
array
|
Reasons why the challenge or exemption was recommended. Allowable Values: A valid array. |
primary_reason
string
|
Primary reason why the challenge or exemption was recommended. Allowable Values: 255 char max |
use_otp_challenge
boolean
|
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:
|
api
object
|
Information regarding the API call and how it was handled. Allowable Values: |
APIResponseWithErrors (response)
Copy section link
A list of problems with the request that the caller might be able to fix.
Fields | Description |
---|---|
version_used
string
|
The version of the API that the server supports and is using.
Do not simply echo back the Allowable Values: Pattern: Example: |
errors
string
|
The error with a message that might be helpful when debugging. Allowable Values: 255 char max |
Response codes
Copy section link
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. |
Notify a 3DS completion status
Copy section link
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
Copy section link
The following table describes the payload required to score an ACS request.
The ThreeDSChallengeResultRequest object
Copy section link
Fields | Description |
---|---|
acs_transaction_id
string
|
Universally unique transaction identifier assigned by the ACS to identify a single transaction.
(EMVCo reference: Allowable Values: 36 char max |
type
string
|
Authentication type that determines the action to be taken by the receiver of this message. Allowable Values:
|
state
string
|
Status of the requested authentication. Allowable Values:
|
user_token
string
|
Marqeta-assigned unique user token identifying the user. Allowable Values: 36 char max |
acting_user_token
string
|
Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 36 char max |
authentication_method
string
|
Method used to authenticate the cardholder. Allowable Values:
|
authentication_result
string
|
Result of the authentication performed. Allowable Values:
|
interaction_counter
integer
|
Indicates the number of authentication cycles attempted by the cardholder.
Value to be tracked by the ACS.
(EMVCo reference: Allowable Values: As provided by the ACS Default Value: |
cancel_reason
integer
|
Indicates to the ACS and the DS that the authentication has been cancelled.
(EMVCo reference: Allowable Values:
|
DecisionServiceResponse (response)
Copy section link
Provides information regarding the call and how it was handled.
Fields | Description |
---|---|
version_used
string
|
The version of the API that the server supports and is using.
Do not simply echo back the Allowable Values: Pattern: Example: |
Response codes
Copy section link
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. |
Receive an Advanced Authentication challenge
Copy section link
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
Copy section link
Fields | Description |
---|---|
X-VERSION
char
|
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
Copy section link
The following table describes the payload required to authenticate a request.
The ThreeDSAuthenticationRequest object
Copy section link
Fields | Description |
---|---|
acs_transaction_id
string
|
Universally unique transaction identifier assigned by the ACS to identify a single transaction.
(EMVCo reference: Allowable Values: 36 char max |
type
string
|
Authentication type that determines the action to be taken by the receiver of this message. Allowable Values:
|
state
string
|
Status of the requested authentication. Allowable Values:
|
user_token
string
|
Marqeta-assigned unique user token identifying the user. Allowable Values: 32 char max |
acting_user_token
string
|
Marqeta-assigned unique user token identifying the user performing the transaction. Allowable Values: 32 char max |
card_token
string
|
Marqeta-assigned unique card token identifying the user. Allowable Values: 32 char max |
created_time
string
|
Authentication request time, expressed in UTC. Allowable Values: Format: yyyy-MM-dd |
network
string
|
The card network associated with this authentication/decision request. Allowable Values:
|
message_version
string
|
The 3DS protocol version used by the 3DS Requestor.
(EMVCo reference: Allowable Values: minLength: 5 |
authentication_request_type
string
|
Indicates the type of authentication request.
(EMVCo reference: Allowable Values:
|
max_response_time
number
|
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: Allowable Values: A five-digit number with a value between Default value: |
transaction
object
|
Contains information about how the payment is being made. Allowable Values: |
card_acceptor
object
|
Details about the merchant with which this transaction is being conducted. Allowable Values: |
three_ds_requestor_app_url
string
|
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
|
The fully qualified URL of the merchant’s website or customer care site. Allowable Values: 255 char max |
The transaction object
Copy section link
Contains information about how the payment is being made.
Fields | Description |
---|---|
transaction_type
string
|
Identifies the category of the message for a specific use case.
(EMVCo reference: Allowable Values:
|
sub_type
string
|
Identifies the type of transaction being authenticated.
(EMVCo reference: Allowable Values:
|
amount
number
|
Purchase amount in minor units of currency with all punctuation removed.
For example, a purchase for $1.99 would be 199.
(EMVCo reference: Allowable Values: A valid number. |
currency_code
number
|
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 |
exponent
integer
|
Minor units of currency value, as specified in the ISO 4217 currency exponent.
For USD, the value is 2.
(EMVCo reference: Allowable Values: A valid ISO 4217 code. |
The card_acceptor object
Copy section link
Warning
This object reports information as supplied by the merchant, and could contain inaccurate or unexpected values.Fields | Description |
---|---|
acquirer_bin
string
|
Acquiring institution identification code, as assigned by the DS receiving the AReq message.
Required when Allowable Values: 11 char max |
merchant_id
string
|
Acquirer-assigned merchant identifier.
Required when Allowable Values: 35 char max |
merchant_category_code
string
|
Merchant Category Code (MCC).
DS-specific code describing the merchant’s type of product or service.
(EMVCo reference: Allowable Values: minLength: 4 |
country
string
|
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 |
name
string
|
Merchant name assigned by the acquirer or payment system.
(EMVCo reference: Allowable Values: 40 char max |
Response codes
Copy section link
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. |
Update an authentication result to Marqeta
Copy section link
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
Copy section link
The following table describes the response to an ACS authentication request.
The ThreeDSAuthenticationResultRequest object
Copy section link
Fields | Description |
---|---|
acs_transaction_id
string
|
Universally unique transaction identifier assigned by the ACS to identify a single transaction.
(EMVCo reference: Allowable Values: 36 char max |
authentication_method
string
|
Method used to authenticate the cardholder. Allowable Values:
|
authentication_result
string
|
Result of the authentication performed. Allowable Values:
|
interaction_counter
integer
|
Indicates the number of authentication cycles attempted by the cardholder.
Value to be tracked by the ACS.
(EMVCo reference: Allowable Values: As provided by the ACS Default Value: |
cancel_reason
string
|
Indicator informing the ACS and the DS that the authentication has been cancelled.
(EMVCo reference: Allowable Values:
|
message_version
string
|
The 3DS protocol version used by the 3DS Requestor.
Echo the value from the Advanced Authentication request.
(EMVCo reference: Allowable Values: 8 char max |
Response codes
Copy section link
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. |