---
updatedAt: 2026-11-02T15:12:42.000Z
agentTools:
  projectIndex: https://developer.spreedly.com/llms.txt
---

# iFrame API ThreeDS lifecycle

API docs for version 1 of the Spreedly iFrame Javascript API.

<Callout icon="🚧" theme="warn">
  Legacy iFrame (version 1.140 and older) and non-secure tokenization was deprecated on October 31, 2026; end of life will be December 31, 2028. See the [iFrame payment form](https://developer.spreedly.com/docs/iframe-payment-form) guide for what's changing and how to stay supported.
</Callout>

Spreedly ThreeDS Lifecycle object is used to help simplify your frontend integration of [Spreedly 3DS solutions](https://developer.spreedly.com/docs/3ds-solutions).

The Lifecycle object polls the Spreedly backend and emits events when the transaction changes status or times out. When a 3DS Challenge needs to be displayed to a cardholder, it will create an `<iframe>` element and inject it with the `<form>` from the acquiring bank.

# ThreeDS Lifecycle

## new

### Arguments

| Name                      | Description                                                                      | Required/Optional |
| :------------------------ | :------------------------------------------------------------------------------- | :---------------- |
| `environmentKey`          | The key of the Spreedly environment where the payment method should be tokenized | Optional          |
| `hiddenIframeLocation`    | The DOM node that you’d like to inject hidden iFrames                            | Required          |
| `challengeIframeLocation` | The DOM node that you’d like to inject the challenge flow                        | Required          |
| `transactionToken`        | The token for the transaction - used to poll for state                           | Required          |
| `challengeIframeClasses`  | The css classes that you’d like to apply to the challenge iFrame                 | Optional          |

```javascript
var lifecycle = new Spreedly.ThreeDS.Lifecycle({
  // The key of the Spreedly environment where the payment method should be tokenized
  environmentKey: '...', // (highly recommended)

  // The DOM node that you'd like to inject hidden iframes
  hiddenIframeLocation: 'device-fingerprint', // (required)

  // The DOM node that you'd like to inject the challenge flow
  challengeIframeLocation: 'challenge', // (required)

  // The token for the transaction - used to poll for state
  transactionToken: '...', // (required)

  // The css classes that you'd like to apply to the challenge iframe.
  // e.g. 'red-border left-positioned custom-styles'
  challengeIframeClasses: '...', // (optional)
})
```

## start

Starts Spreedly’s 3DSecure asynchronous flow once it is completely setup using the new constructor.

```javascript
lifecycle.start()
```

### Signature

`start()`

### Events

Before `start()` is invoked, the following events need to be wired with the `Spreedly.on` listener.

| Name         | Action                                              |
| :----------- | :-------------------------------------------------- |
| `3ds:status` | Setup event handling and kickoff 3DSecure lifecycle |

## browser info

Gathers relevant browser information needed by SCA providers to help determine if a challenge flow is necessary. Also gathers information about the desired size of the challenge frame, and needed accept headers. This function returns a base64 encoded string that will be submitted via your backend request to authorize or purchase for 3DS. See [Spreedly's 3DS guide](https://developer.spreedly.com/docs/3ds-solutions) for more details on how to use this function.

### Arguments

| Name                    | Description                                                                                                                     | Required/Optional |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :---------------- |
| `challenge_window_size` | This is a value that represents the desired size of the challenge window if a challenge is needed during the 3DS flow.          | Optional          |
| `accept_header`         | The accept headers allowed by your server. Defaults to `text/html,application/xhtml+xml,application/xml` if no value is passed. | Optional          |

```
const challenge_window_size = '04';
const acceptHeader = 'text/html,application/xhtml+xml,application/xml'

const browser_info = Spreedly.ThreeDS.serialize(challenge_window_size, acceptHeader);
```

Valid values for `challenge_window_size` are:

| Value | Correlating size |
| :---- | :--------------- |
| `01`  | 250px x 400px    |
| `02`  | 390px x 300px    |
| `03`  | 500px x 600px    |
| `04`  | 600px x 400px    |
| `05`  | fullscreen       |