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

# 3DS via Paysight Widget

> Implement 3D Secure (3DS) in the Paysight Widget including standard, fallback, and frictionless-only flows with practical configuration and event handling examples.

<Info>
  This guide covers two primary 3DS strategies in the Paysight Widget:

  1. Standard 3DS (with optional fallback if 3DS fails), and 2) Frictionless-only (no challenge UI).
</Info>

## Overview

3D Secure (3DS) adds an extra authentication step to reduce fraud and can provide liability shift benefits. Within the Paysight Widget, you control 3DS behavior via configuration flags and handle progress through widget events.

### When to use which flow

* <strong>Standard 3DS</strong>
  : Maximize approvals and liability shift by allowing challenge flows when required by the issuer.
* <strong>Standard 3DS with fallback</strong>
  : Attempt 3DS, but if the authentication fails, continue without 3DS to reduce drop-offs.
* <strong>Frictionless-only</strong>
  : Only allow frictionless 3DS (no challenge UI). If a challenge would be required, skip 3DS and proceed.

<Warning>
  Skipping or falling back from 3DS may remove liability shift benefits. Validate policy with your risk team and acquiring agreements.
</Warning>

## Prerequisites

<Steps>
  <Step title="Install and load the Widget">
    Ensure you have the Paysight Widget installed or loaded on your page. See <a href="/widget-sdk/guides/installation">
    Installation</a>

    .
  </Step>

  <Step title="Confirm product and MID support">
    Your product/MID must be enabled to support 3DS. Confirm configuration with your Paysight account manager if unsure.
  </Step>

  <Step title="Implement event handling">
    Add an <code>
    onMessage</code>

    handler for 3DS and payment events. See <a href="/widget-sdk/guides/events">
    Event Handling</a>

    .
  </Step>
</Steps>

## 3DS Configuration Options

These options control 3DS behavior:

* <strong>threeDSRequired</strong>
  (boolean): Turn on 3DS for the payment.
* <strong>failOnThreeDSChallenge</strong>
  (boolean): If true, do not show a challenge UI. If a challenge is required, proceed without 3DS.
* <strong>cancelOnThreeDSFailure</strong>
  (boolean): If true, cancel the payment when 3DS is not successfully completed.

<Info>
  **Google Pay** follows the same 3DS path as the card form when <code>threeDSRequired</code> is <code>true</code> (in-widget 3DS challenge + Paysight outcome reporting). See <a href="/widget-sdk/guides/google-pay-via-widget">Google Pay via Widget</a>.
</Info>

<Warning>
  **Apple Pay** does **not** run the widget’s 3DS flow: the payment request omits <code>threeDSecure</code>, and if the API returns a <code>threeDSecureId</code>, the Apple Pay path fails with an explicit “3D Secure not supported with Apple Pay” error. Use <code>threeDSRequired: false</code> for Apple Pay–only checkouts unless Paysight advises otherwise.
</Warning>

<Note>
  The widget will emit 3DS-related events during the flow: <code>PAYMENT\_3DS\_START</code>, <code>PAYMENT\_3DS\_SUCCESS</code>, <code>PAYMENT\_3DS\_ERROR</code>, and <code>PAYMENT\_3DS\_FAILURE</code>.
</Note>

## Flow 1: Standard 3DS

Two configuration variants:

1. <strong>Strict 3DS</strong>
   (challenge allowed, cancel on failure)

* <code>threeDSRequired: true</code>
* <code>failOnThreeDSChallenge: false</code>
* <code>cancelOnThreeDSFailure: true</code>

2. <strong>3DS with fallback</strong>
   (challenge allowed, continue if 3DS fails)

* <code>threeDSRequired: true</code>
* <code>failOnThreeDSChallenge: false</code>
* <code>cancelOnThreeDSFailure: false</code>

<CodeGroup>
  ```javascript Strict — challenge allowed, cancel on failure theme={null}
  PaySightSDK.createWidget({
    targetId: 'payment-container',
    config: {
      productId: YOUR_PRODUCT_ID,
      sessionId: 'YOUR_SESSION_ID',
      environment: 'sandbox',
      amount: 29.99,
      threeDSRequired: true,
      failOnThreeDSChallenge: false,
      cancelOnThreeDSFailure: true,
    },
    onMessage: (message) => {
      switch (message.type) {
        case 'PAYMENT_3DS_START':
          break;
        case 'PAYMENT_3DS_SUCCESS':
          break;
        case 'PAYMENT_3DS_ERROR':
        case 'PAYMENT_3DS_FAILURE':
          break;
        case 'PAYMENT_SUCCESS':
          break;
        case 'PAYMENT_ERROR':
          break;
      }
    },
  });
  ```

  ```javascript Fallback — challenge allowed, continue if 3DS fails theme={null}
  PaySightSDK.createWidget({
    targetId: 'payment-container',
    config: {
      productId: YOUR_PRODUCT_ID,
      sessionId: 'YOUR_SESSION_ID',
      environment: 'sandbox',
      amount: 29.99,
      threeDSRequired: true,
      failOnThreeDSChallenge: false,
      cancelOnThreeDSFailure: false,
    },
    onMessage: (message) => { /* same handlers as above */ },
  });
  ```
</CodeGroup>

## Flow 2: 3DS Frictionless-only

Frictionless-only means you will not show a 3DS challenge UI. If the issuer requires a challenge, the widget will proceed without performing 3DS.

* <code>threeDSRequired: true</code>
* <code>failOnThreeDSChallenge: true</code> (skip challenge, only frictionless allowed)
* <code>cancelOnThreeDSFailure</code>: choose behavior if frictionless fails
  * <strong>true</strong>
    : cancel payment if frictionless fails
  * <strong>false</strong>
    : continue without 3DS even if frictionless fails

```javascript Frictionless-only theme={null}
PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    productId: YOUR_PRODUCT_ID,
    sessionId: 'YOUR_SESSION_ID',
    environment: 'sandbox',
    amount: 29.99,
    threeDSRequired: true,
    failOnThreeDSChallenge: true,
    cancelOnThreeDSFailure: false,
  },
  onMessage: (message) => { /* handle PAYMENT_3DS_* and PAYMENT_* */ },
});
```

## Event Handling Essentials

Handle these events to keep users informed and manage edge cases:

```javascript theme={null}
onMessage: (message) => {
  switch (message.type) {
    case 'PAYMENT_START':
      // Disable submit, show "Processing"
      break;
    case 'PAYMENT_3DS_START':
      // Show "Verifying with 3D Secure..."
      break;
    case 'PAYMENT_3DS_SUCCESS':
      // Update UI and continue
      break;
    case 'PAYMENT_3DS_ERROR':
    case 'PAYMENT_3DS_FAILURE':
      // Depending on config, either retry or continue without 3DS
      break;
    case 'PAYMENT_SUCCESS':
      // Confirmation UI / redirect
      break;
    case 'PAYMENT_ERROR':
      // Show error and allow retry
      break;
  }
}
```

<Info>
  Full event details and patterns: <a href="/widget-sdk/guides/events">
  Event Handling</a>

  and <a href="/widget-sdk/reference/events">
  Events Reference</a>

  .
</Info>

## Testing

<Steps>
  <Step title="3DS Testing Flow">
    To test the 3DS flow, use the widget in production and use a real card to perform a 3DS flow test. Please note that you may receive a frictionless flow or a challenge flow depending on the card you use.
  </Step>

  <Step title="Expect variability">
    Whether a challenge is required depends on issuer risk. Test multiple times and with different cards to observe 3DS vs frictionless behavior.
  </Step>

  <Step title="Track outcomes">
    Log all `PAYMENT_3DS_*` and `PAYMENT_*` events while testing to validate your UX and fallback logic.
  </Step>
</Steps>

## Best Practices

* <strong>Communicate clearly</strong>
  : Tell users when additional verification may be required.
* <strong>Be intentional with fallback</strong>
  : Only continue without 3DS if your risk policy allows it.
* <strong>Measure conversion</strong>
  : A/B test strict vs fallback vs frictionless-only to find the best balance of security and UX.
* <strong>Surface failures</strong>
  : If you continue without 3DS, consider showing a subtle banner indicating verification was skipped.

## Live demo

Try 3DS flags in the sandbox playground: [https://payment.paysight.io/demo?preset=three-ds](https://payment.paysight.io/demo?preset=three-ds)

## See Also

<CardGroup cols={2}>
  <Card title="3DS live demo" icon="play" href="https://payment.paysight.io/demo?preset=three-ds">
    Interactive sandbox preset with 3DS toggles.
  </Card>

  <Card title="3DS Integration Example" icon="shield" href="/widget-sdk/examples/3ds-integration">
    A complete HTML example that wires up configuration and events.
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/widget-sdk/guides/configuration">
    Detailed configuration including all 3DS options.
  </Card>
</CardGroup>

## Visibility

For successful 3DS, you'll see ' 3DS' in the debug info at the bottom of the Transactions detail view, as per screenshot:

<img src="https://mintcdn.com/paysight/csx5Ubv1hP5_yyiU/images/image.png?fit=max&auto=format&n=csx5Ubv1hP5_yyiU&q=85&s=0b864e22940aaadc08258166821f37dd" alt="image.png" width="1032" height="131" data-path="images/image.png" />

We have some upcoming updates to provide better visibility on 3DS in Transactions and Reporting. We released this feature early so that clients could start using it immediately.