> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlaspay.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```tsx theme={null}
<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

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```javascript theme={null}
// 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

```bash theme={null}
curl https://api.atlas.co/functions/v1/threeds-authenticate/sessions/3ds_session_abc123/result \
  -H "Authorization: Bearer cs_client_secret_xxx"
```

**Response:**

```json theme={null}
{
  "status": "authenticated",
  "authentication_value": "kBx2ZWJ3Y...",
  "eci": "05",
  "ds_transaction_id": "d8e8b...",
  "liability_shift": true
}
```

### Complete Challenge

After the customer completes the challenge:

```bash theme={null}
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

1. **Always attempt 3DS** for European cards (PSD2 requirement)
2. **Use challenge\_preference wisely** - "no\_challenge" may result in lower approval rates
3. **Handle timeouts** - 3DS challenges can take several minutes
4. **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          |