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.
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

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

Card payment methods only

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.

Use full billing to maximize frictionless authentication

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.

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 and the gateway reports a 3D Secure reason for the failure. Any other failure in a 3D Secure session reports 6900-6902, as in a session without 3D Secure, and threeDs can still carry the authentication data, such as the ECI, from before the failure.

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.

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.

Form configuration - the rest of the formConfig object
SDK error codes - the full 6000-6999 range