3D Secure Setup
This guide provides an overview of the 3D Secure 2 (3DS 2.2 and 2.1 for Visa and 3DS 2.1 for Mastercard) setup and the onboarding process with Marqeta and payment networks, and outlines the integration points you need to plan for during 3D Secure authentication and payment transactions. Use this guide to plan the actions and integrations required to enable 3D Secure 2 features on the Marqeta platform.
Setting up 3D Secure
Copy section link
The following sections describe how to set up 3D Secure on the Marqeta platform.
Setting up 3DS for your use case
Copy section link
For some use cases, such as those for Buy Now, Pay Later (BNPL) applications, configuring Challenge All may result in challenging cards that are not enrolled for OTP or biometrics decisioning. For these cases, implement delegated decisioning at your gateway to prevent unnecessary declines. To do this, perform the decisioning at your gateway to identify the risk for the user and transaction and, if the risk is low, exempt the transaction at the gateway. See option 3 in Available Combinations below.
For detailed information on setting up the best 3D Secure configuration for your use case, contact your Marqeta representative.
Available combinations
Copy section link
The following table shows the available combinations for 3D Secure risk policy and authentication, as well as the amount of effort required.
3D Secure Risk Policy |
Authentication Mechanism |
|||||
Options |
Challenge All (Default – No policy chosen) |
Delegated Decisioning |
Automated Decisioning |
Default OTP |
Advanced Authentication |
Customer Effort |
Option 1 |
✔ |
∅ |
∅ |
✔ |
∅ |
○ ○ ○ |
Option 2 |
∅ |
✔ |
∅ |
✔ |
∅ |
● ● ○ |
Option 3 |
∅ |
✔ |
∅ |
∅ |
✔ |
● ● ● |
Option 4 |
∅ |
∅ |
✔ |
✔ |
∅ |
○ ○ ○ |
Option 5 |
∅ |
∅ |
✔ |
∅ |
✔ |
● ○ ○ |
Option 6 |
✔ |
∅ |
∅ |
∅ |
✔ |
● ○ ○ |
Integration flow
Copy section link
The following figure shows the overall flow for the 3D Secure 2 authentication, as well as for the payment authorization.
Setup details
Copy section link
The following sections describe in detail the overall flow shown in the figure above, with a focus on the steps where a specific action or API integration is required.
Step 1 — Setup and onboarding
Copy section link
| Step # | Summary | Details | Customer Configuration Required | Marqeta API Integration Required |
|---|---|---|---|---|
1.1 |
Enable 3DS using the card network’s CIQ/APW |
Enable 3DS with the card network using Visa’s CIQ or Mastercard’s APW and other required documents. |
No |
No |
1.2 |
Create users, cards using API |
Using Marqeta’s API, create users and cards. |
No |
Yes |
1.3 |
Enable 3DS request |
Request to enable 3DS with Marqeta through your Marqeta representative. |
Yes |
No |
1.4 |
Enable 3DS using the Marqeta Dashboard |
Marqeta representative enables 3DS using app.marqeta.com. |
No |
No |
1.5 |
Choose a 3DS policy and configure 3DS parameters |
Choose the appropriate 3DS Risk and Authentication options, then contact your Marqeta representative to have the required parameters configured. Configuration Parameters:
|
Yes |
No |
1.6 |
Configure 3DS parameters using the Marqeta Dashboard |
Marqeta representative enables 3DS configurations using app.marqeta.com. |
No |
No |
Step 2 — Cardholder authentication
Copy section link
| Step # | Summary | Details | Customer Configuration Required | Marqeta API Integration Required |
|---|---|---|---|---|
2.1 |
Cardholder makes an online transaction |
None |
No |
No |
2.2 |
Merchant requests authentication |
None |
No |
No |
2.3 |
Card network requests authentication |
None |
No |
No |
2.4A |
If no decisioning policy is configured: |
|||
Challenge All authentication requests from the 3DS requestor and/or merchant |
||||
2.4B |
If Delegated Decisioning is configured: |
|||
2.4B1 |
Delegated Decisioning request via API |
Marqeta’s systems make a web request to obtain a decision from you on whether to apply SCA to the request in picture or exempt it from SCA. You must implement the necessary systems to handle this request. |
No |
Yes |
2.4B2 |
Respond to Marqeta with the SCA decision |
Your system must respond to the Marqeta system’s request with the SCA decision within the prescribed SLA. |
No |
Yes |
2.4C |
If Automated Decisioning is configured: |
|||
2.4C1 |
Evaluate the risk and decide to exempt or challenge the cardholder |
No |
No |
|
2.5A |
If Challenge All and Advanced Authentication are configured: |
|||
2.5A1 |
Advanced Authentication request via API |
Marqeta requests that you authenticate the cardholder (in-app or otherwise), using the API defined by Marqeta. You must be able to process Marqeta’s authentication request using the Marqeta-defined JSON payload. |
No |
Yes |
2.5A2 |
Acknowledge |
Your endpoint should acknowledge Marqeta’s API request with a |
No |
Yes |
2.5A3 |
Complete cardholder challenge via mobile APP or other preferred method |
You request in-app authentication from the cardholder using the mobile banking APP or another preferred method such as voice calling. |
No |
No |
2.5A4 |
Perform authentication |
You perform the authentication. |
No |
No |
2.5A5 |
Respond to Marqeta with the authentication result |
Marqeta acknowledges with a |
No |
Yes |
2.5B |
If Challenge All and Default OTP is configured: |
|||
2.5B1 |
Marqeta sends OTP via text or email to the registered phone number or email address |
None |
No |
No |
2.5B2 |
Marqeta presents the OTP screen on the merchant’s website |
None |
No |
No |
2.5B3 |
Cardholder enters OTP |
None |
No |
No |
2.5B4 |
OTP data is received by Marqeta |
None |
No |
No |
2.5B5 |
Marqeta performs cardholder authentication |
None |
No |
No |
2.6 |
Marqeta sends the cardholder authentication result to the merchant |
None |
No |
No |
2.6A |
If Delegated Decisioning is configured: |
|||
2.6A1 |
Authentication final result via API |
Marqeta’s systems will make a web request to update the authentication results.
Your endpoint should acknowledge Marqeta’s API request with a |
No |
Yes |
2.7 |
Marqeta sends the cardholder authentication result to the card network |
None |
No |
No |
Step 3 — Payment authorization
Copy section link
| Step # | Summary | Details | Customer Configuration Required | Marqeta API Integration Required |
|---|---|---|---|---|
3.1 |
Merchant initiates the payment transaction |
None |
No |
No |
3.2 |
Card network routes the payment transaction to Marqeta |
None |
No |
No |
3.2A |
If Gateway JIT Funding is configured: |
|||
3.2A1 |
Marqeta initiates a Gateway JIT Funding request with 3DS result data |
Marqeta makes a JIT call to your JIT gateway endpoint. This call includes transaction-related information: how the transaction was authenticated and whether or not the authentication was successful. At this time, you can decide to approve or decline the payment transaction. |
No |
Yes |
3.2A2 |
JIT gateway response |
You respond back to the JIT gateway call with your decision (approve or deny). |
No |
Yes |
3.3 |
Marqeta sends the payment transaction response to the card network |
None |
No |
No |
3.4 |
The card network sends the payment transaction response to the merchant |
None |
No |
No |
Enabling 3D Secure
Copy section link
To enable 3D Secure, log into the Marqeta Dashboard and go to Control center > 3D secure. For detailed instructions, see Enabling 3D Secure in Control Center.
APIs and contracts
Copy section link
You must provide code for the following endpoints, which Marqeta calls during the 3D Secure 2 flow:
-
Delegate decisioning – determine whether to send an SCA.
-
Notify a 3DS completion status.
-
Initiate an Advanced Authentication.
-
Update an authentication result to Marqeta.
For detailed information on these endpoints, see 3D Secure in the Core API Reference.
When to use each interface
Copy section link
Depending on the 3D Secure options you choose, you will need to implement and configure for one or more of the API endpoints described above.
The following table lists the policies along with the required actions:
| Option | Policy | Action |
|---|---|---|
1 |
Challenge All and Default OTP |
No API integration necessary |
2 |
Delegated Decisioning and Default OTP |
Delegated Decisioning request |
3 |
Delegated Decisioning and Advanced Authentication |
Delegated Decisioning request |
4 |
Automated Decisioning and Default OTP challenge |
No API integration necessary |
5 |
Automated Decisioning and Advanced Authentication |
Advanced Authentication request |
6 |
Challenge All and Advanced Authentication |
Advanced Authentication request |