Enable 3D Secure (3DS) authentication on the Priority Checkout widget to authenticate cardholders at the time of payment, achieve liability shift, and reduce fraudulent chargebacks — without writing any custom authentication code.

📘

3DS authentication is handled entirely within the Priority Checkout widget. No changes to your frontend authentication flow or backend payment submission are required beyond the configuration steps below.

Prerequisites

Before enabling 3DS on Priority Checkout, ensure the following are in place:

How 3DS Works in Priority Checkout

When 3DS is enabled on your account, the Priority Checkout widget handles the entire authentication lifecycle automatically:

1. When a customer submits their card details, the widget collects browser and device signals and initiates a 3DS authentication session in the background.
2. If the issuer grants frictionless authentication, the transaction proceeds immediately — no customer action is required.
3. If the issuer requires a challenge, the widget renders the challenge modal inline within the checkout interface. The customer completes the challenge without leaving your page.
4. Once authentication is complete, the widget submits the payment with the 3DS result — including the ECI code and CAVV — automatically attached.
5. You receive the final transaction outcome via the onSuccess or onError callback, along with the liabilityShift indicator in the response payload.

Enable 3DS on Priority Checkout

Pass the threeDSecure configuration object when initializing the widget via WidgetSDK.create(). When enabled is set to true, 3DS authentication is triggered automatically for every card payment.

const widget = WidgetSDK.create('CHECKOUT', {
  clientSecret: clientSecret,
  containerId: '#checkout-container',
  businessId: 'biz_123',
  transactionOrigin: 'ECOM',
  amount: {
    value: '125.00',
    currency: 'USD'
  },
  threeDSecure: {
    enabled: true           // Enables 3DS authentication for all card payments
  },
  onSuccess: (result) => {
    console.log('Payment successful:', result.transactionId);
    console.log('Liability shift:', result.threeDSecure.liabilityShift);
    window.location.href = '/order/success';
  },
  onError: (error) => {
    console.error('Payment error:', error.message);
  }
});

3DS Configuration Reference

onSuccess Response — With 3DS

When 3DS is enabled, the onSuccess payload includes an additional threeDSecure object containing the authentication result and liability shift status.

{
  "widgetType": "CHECKOUT",
  "status": "SUCCESS",
  "timestamp": 1774522622702,
  "actions": [
    "PAYMENT.CREATE"
  ],
  "data": {
    "transactionId": "4000000000757938",
    "reference": "608510058551",
    "totalAmount": {
      "value": "125.00"
    },
    "amount": {
      "value": "125.00"
    },
    "paymentMethod": {
      "card": {
        "brand": "VISA",
        "last4": "1111",
        "type": "CREDIT",
        "name": "Jane Smith",
        "expiryMonth": "12",
        "expiryYear": "2027"
      }
    },
    "threeDSecure": {
      "eci": "05",
      "authenticationStatus": "Y",
      "liabilityShift": true
    },
    "customer": {
      "id": "10000000888479"
    }
  }
}

3DS Response Fields

Authentication Outcomes & What They Mean

The widget handles all 3DS outcomes automatically. Your onSuccess and onError callbacks receive the result as described below.

Testing 3DS on Priority Checkout

Use the sandbox environment to test all 3DS flows within the widget before going live.

• In the sandbox, the challenge modal renders a simulated challenge screen. Enter any 6-digit OTP to complete the challenge successfully.
• Use the 3DS test cards to simulate frictionless, challenge, failed, and unavailable authentication outcomes.
• Confirm threeDSecure.liabilityShift is true in the onSuccess payload for fully authenticated flows.

📘

For the full 3DS test card reference, see 3D Secure Authentication — Sandbox Testing.

See Also

• 3D Secure (3DS) Authentication
• Enabling 3DS for Card Vaulting
• Priority Checkout Integration Steps
• ECI Codes
• Card Test Data