> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/hosted-payment-form/3d-secure.md).

# 3D Secure

Opt into 3DS2 cardholder authentication and shift chargeback liability to the issuer.

The `enable3DSecure` property opts the hosted payment form into 3D Secure (3DS2) cardholder authentication. When enabled, the issuer decides whether the transaction is authenticated frictionlessly or requires a cardholder challenge - challenges are rendered in an overlay on the hosted payment form, which resumes automatically on completion.

## What it changes

* **Liability shift** - Successfully authenticated card transactions (ECI 02/05) shift chargeback liability for fraud from the merchant to the issuer.
* **Default behavior** - When omitted, the payment method default applies. Set `false` to disable 3DS explicitly.
* **Authentication results** - Read `threeDs.status` for the authentication outcome. Additional authentication data appears in `threeDs` when available; see [Authentication data](/glossary/hosted-forms-and-sdk.md#threeds-authentication-data).
* **Decline notifications** - A 3DS authentication failure appears as a declined transaction. Your configured `sale.completed` / `auth.completed` webhook reports it like any other decline.

## Enabling it

```json
{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_12345",
  "formConfig": {
    "billingInfoCaptureLevel": "Full",
    "enable3DSecure": true
  }
}
```

## Card payment methods only

{% hint style="danger" %}
3D Secure is a card-network authentication protocol (Visa, Mastercard, American Express, Discover). It is **not supported** for ACH or EFT payment methods. Setting `enable3DSecure: true` on a non-card payment method is rejected with a validation error.
{% endhint %}

## Use full billing to maximize frictionless authentication

{% hint style="warning" %}
**Recommended:** When 3D Secure is enabled, use `billingInfoCaptureLevel: Full` (the default). The 3DS2 risk engine uses the billing address, email, and phone to assess transaction risk - providing the full set of fields significantly increases the likelihood of a frictionless authentication (no cardholder challenge).

Full billing is *not required* for 3DS to function: it is recommended to maximize conversion.
{% endhint %}

## Reading the outcome

3DS-specific result codes are surfaced on declined card transactions via the transaction's `resultCode` - and correspondingly on the failure redirect URL's `errorCode` query parameter and the SDK's `onComplete` callback payload. They let you distinguish a 3DS-driven decline from a generic issuer decline or an unrelated SDK error. These codes are only emitted when the session was initiated with `formConfig.enable3DSecure: true`.

| Code   | Name                              | What to do                                                                                                                                                                                                                           |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `6800` | `Sdk3dsAuthenticationFailed`      | The issuer's ACS rejected the authentication (card auth failed, security failure, stolen card, suspected fraud, transaction not permitted). Hard decline - retrying the same card without 3DS is unlikely to succeed.                |
| `6801` | `Sdk3dsAuthenticationUnavailable` | Authentication could not be completed due to an upstream technical issue (ACS timeout, directory server unreachable, unexpected ACS error). Retrying later may succeed; retrying without 3DS is only safe if merchant policy allows. |
| `6802` | `Sdk3dsNotEnrolled`               | The card is not enrolled in 3DS . A retry with 3DS disabled - if allowed by merchant policy - may be attempted; approval is not guaranteed.                                                                                          |

{% hint style="warning" %}
Retrying without 3DS after a `6801` or `6802` gives up the liability shift for that transaction. Make that a deliberate, documented policy decision rather than automatic fallback behaviour.
{% endhint %}

## Related

* [Form configuration](/hosted-payment-form/form-configuration.md) - the rest of the `formConfig` object
* [SDK error codes](/payment-sdk/error-codes.md) - the full `6000`-`6999` range