3D Secure

Strong customer authentication for card payments.

What is 3D Secure?

3D Secure (3DS) is an authentication protocol that adds an extra layer of security for online card transactions. It shifts liability for fraudulent chargebacks from the merchant to the card issuer.

Benefits

Benefit	Description
Liability Shift	Fraud chargebacks become issuer’s responsibility
Frictionless Flow	Low-risk transactions authenticate silently
PSD2 Compliant	Required for European transactions

Automatic 3DS

When using the Payment Sheet or Elements SDK, 3DS is handled automatically:

<PaymentSheet
  clientSecret="cs_test_..."
  onSuccess={(payment) => {
    // 3DS was handled automatically if needed
    console.log('Payment complete:', payment.id);
  }}
/>

Manual 3DS API

For custom integrations, use the 3DS API directly.

Initiate Authentication

curl -X POST https://api.atlas.co/functions/v1/threeds-authenticate \
  -H "Authorization: Bearer cs_client_secret_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "token_id": "tok_card_xyz",
    "amount": 4990,
    "currency": "USD",
    "challenge_preference": "no_preference"
  }'

Parameters:

Parameter	Type	Required	Description
`session_id`	string	Yes	Payment session ID
`token_id`	string	Yes	Card token from tokenization
`amount`	integer	Yes	Transaction amount in cents
`currency`	string	Yes	Three-letter ISO currency code
`challenge_preference`	string	No	no_preference, no_challenge, challenge_requested, challenge_mandated

Response:

{
  "id": "3ds_session_abc123",
  "status": "challenge_required",
  "challenge_required": true,
  "challenge_url": "https://acs.issuer.com/challenge/...",
  "authentication_value": null,
  "eci": null,
  "ds_transaction_id": "d8e8b...",
  "liability_shift": false
}

Handle Challenge

If challenge_required is true, display the challenge URL in an iframe:

// Create iframe for 3DS challenge
const iframe = document.createElement('iframe');
iframe.src = response.challenge_url;
iframe.style.cssText = 'width: 400px; height: 600px; border: none;';
document.getElementById('3ds-container').appendChild(iframe);

// Listen for completion
window.addEventListener('message', (event) => {
  if (event.data.type === 'ATLAS_3DS_COMPLETE') {
    // Challenge completed, fetch result
    fetch3DSResult(response.id);
  }
});

Get Authentication Result

curl https://api.atlas.co/functions/v1/threeds-authenticate/sessions/3ds_session_abc123/result \
  -H "Authorization: Bearer cs_client_secret_xxx"

Response:

{
  "status": "authenticated",
  "authentication_value": "kBx2ZWJ3Y...",
  "eci": "05",
  "ds_transaction_id": "d8e8b...",
  "liability_shift": true
}

Complete Challenge

After the customer completes the challenge:

curl -X POST https://api.atlas.co/functions/v1/threeds-authenticate/sessions/3ds_session_abc123/challenge-complete \
  -H "Authorization: Bearer cs_client_secret_xxx"

Authentication Status Values

Status	Description
`Y`	Fully authenticated - proceed with payment
`A`	Attempted authentication - proceed with payment
`N`	Authentication failed - do not proceed
`U`	Unable to authenticate - proceed at merchant risk
`R`	Rejected by issuer - do not proceed

ECI Values

ECI	Network	Meaning
05	Visa	Fully authenticated
06	Visa	Attempted authentication
07	Visa	Non-3DS transaction
02	Mastercard	Fully authenticated
01	Mastercard	Attempted authentication
00	Mastercard	Non-3DS transaction

Best Practices

Always attempt 3DS for European cards (PSD2 requirement)
Use challenge_preference wisely - “no_challenge” may result in lower approval rates
Handle timeouts - 3DS challenges can take several minutes
Test all scenarios - Use test cards that trigger challenges

Test Cards

Card Number	3DS Behavior
`4000000000003220`	3DS required, authentication succeeds
`4000000000003063`	3DS required, authentication fails
`4000000000003055`	3DS optional, not challenged

Getting Started

Payments

UI Components

Billing

Data & Security

Mobile

Developer

What is 3D Secure?

Benefits

Automatic 3DS

Manual 3DS API

Initiate Authentication

Handle Challenge

Get Authentication Result

Complete Challenge

Authentication Status Values

ECI Values

Best Practices

Test Cards

​What is 3D Secure?

​Benefits

​Automatic 3DS

​Manual 3DS API

​Initiate Authentication

​Handle Challenge

​Get Authentication Result

​Complete Challenge

​Authentication Status Values

​ECI Values

​Best Practices

​Test Cards

What is 3D Secure?

Benefits

Automatic 3DS

Manual 3DS API

Initiate Authentication

Handle Challenge

Get Authentication Result

Complete Challenge

Authentication Status Values

ECI Values

Best Practices

Test Cards