3D Secure

Overview

3D Secure is handled automatically inside confirmPayment, with no separate call. If the customer’s bank requires a challenge, the SDK shows it in-page and resumes when they finish. Frictionless authentications need no UI at all. When a challenge is required, the customer sees their bank’s authentication screen (OTP, biometric, etc.) inside a secure iframe. You choose where it appears.

Option	How
Default modal	Do nothing extra. The SDK pops a centered modal overlay on top of your page. Fastest to integrate.
Your own container	Pass `threeDS: { container: '#threeds-container' }`, a CSS selector or DOM node, and the challenge renders inside that element, fitting your checkout layout.

Rendering in your own container

Put a container in your checkout (only needed if you do not want the default modal), then pass it to threeDS.container and drive your UI from onStatusChange. That is why the callback matters: it is how you show a spinner during authentication and hide it when the challenge appears.

<div id="threeds-container"></div> <!-- the bank's challenge renders in here -->

const result = await modulus.confirmPayment({
  elements,
  billingDetails,
  threeDS: { container: '#threeds-container' }, // omit this to use the default modal
  onStatusChange: (status) => {
    if (status === 'submitting')      spinner.show('Processing...');
    if (status === 'requires_action') spinner.hide();  // let the customer do the challenge
    if (status === 'authenticating')  spinner.show('Authenticating...');
  },
});

Lifecycle status

onStatusChange reports the payment’s progress:

Status	Meaning
`submitting`	`confirmPayment` called. Billing validated, card and intent sent to the server.
`requires_action`	The bank requires a 3D Secure challenge, and the SDK is now showing it (modal or your container). Challenge path only.
`authenticating`	Challenge finished (or frictionless). Authorizing the payment with the issuer.
`succeeded` · `declined` · `failed` · `processing` · `expired`	Terminal outcomes, mirrored in the resolved `result`.

There are two paths through the lifecycle:

Frictionless: submitting -> authenticating -> terminal. No requires_action, the customer sees nothing.
Challenge: submitting -> requires_action -> authenticating -> terminal. The customer completes the OTP in between.

Challenge window size

The EMVCo challenge window dimensions, passed to confirmPayment as acsWindowSize. This only applies to the challenge path and is ignored when the authentication is frictionless.

`acsWindowSize`	Dimensions (W x H)
`"01"`	250 x 400
`"02"`	390 x 400
`"03"`	500 x 600
`"04"`	600 x 400
`"05"`	Full page (default)

Test both paths with the sandbox test cards: a challenge card presents the OTP step (enter 1234), and a frictionless card authenticates with no customer interaction.

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Rendering in your own container

Lifecycle status

Challenge window size

​Overview

​Rendering in your own container

​Lifecycle status

​Challenge window size

Overview

Rendering in your own container

Lifecycle status

Challenge window size