Review 3-D Secure challenge

The 3-D Secure challenge can be presented either through a full-page redirect or within an iFrame, depending on the configured mode. The SDK manages the challenge lifecycle and payment state in both modes, including navigation, polling, frame handling, and fallback behaviour.

3-D Secure challenges

Redirect mode (default)

The challenge is performed as a POST navigation of the current tab to the ACS; the customer comes back via the return_url configured on the payment request. Your page (and the SDK instance) is destroyed and recreated; a fresh init() picks up the in-flight payment on its own — no dedicated recovery code is needed, just initialise as usual and react to next_action.

iFrame mode

The challenge opens in an iframe inside the SDK's modal (or in your container). The page does not navigate; the instance and polling stay alive.

The frame's lifecycle is driven by the payment state. The frame appears with the acs_redirect directive and disappears as soon as the display status stops being action_required (or on destroy()).

There is deliberately no SDK-side timeout: the customer may be reading an SMS or re-requesting an OTP — the backend is the authority on 3-DS expiration, and it arrives as a regular snapshot (a decline + retry), which also closes the frame.

Container fallback

If the configured challenge.container does not resolve at the moment of opening (no match, an invalid selector, an element outside the document), the SDK emits an error (invalid_config, details.challengeContainer) and opens its own modal — the challenge is never "lost", because it is the only path to completing the payment.