# @mangopay/three-ds-helper

> Mangopay SDK - 3DS Helper

Latest version **1.4.2** (published 2025-09-10) · ISC license · 0 weekly downloads

## Install

```sh
npm install @mangopay/three-ds-helper
pnpm add @mangopay/three-ds-helper
yarn add @mangopay/three-ds-helper
bun add @mangopay/three-ds-helper
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.2 |
| Published | 2025-09-10 |
| First published | 2023-10-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 43.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Mangopay Limited |
| Maintainers | denys.yakovenko, m.shaban.mangopay, jide-mgp |
| Keywords | Mangopay, 3DS Helper |

## Links

- npm: https://www.npmjs.com/package/@mangopay/three-ds-helper
- npm.io page: https://npm.io/package/@mangopay/three-ds-helper

## Dependencies (1)

- [@mangopay/checkout-sdk-core](https://npm.io/package/@mangopay/checkout-sdk-core.md) ^1.4.2

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 1.4.2 (latest) — 2025-09-10
- 1.4.3-beta.0 (beta) — 2025-11-07
- 1.4.2-beta.0 — 2025-09-09
- 1.4.1 — 2025-09-01
- 1.4.0 — 2025-08-08
- 1.4.0-beta.0 — 2025-08-07
- 1.3.8-beta.1 — 2025-07-23
- 1.3.7 — 2025-07-04
- 1.3.6 — 2025-07-04
- 1.3.3 — 2025-04-08
- 1.3.2 — 2025-03-27
- 1.3.1 — 2025-03-25
- 1.3.0-beta.1 — 2025-03-25
- 1.3.0-beta.0 — 2025-03-18
- 1.2.1 — 2024-11-29
- … 47 more at https://npm.io/package/@mangopay/three-ds-helper/versions

## README

# Three DS helper - User integration guide

## Installation

The Mangopay `three-ds-helper` is available on npm. See @mangopay/three-ds-helper for a reference.

```
npm install --save @mangopay/three-ds-helper
# or
yarn add @mangopay/three-ds-helper
```

### Key Features:

`openThreeDSPopup`: A function to open a pop-up window for 3DS authentication.

`runThreeDSRedirectListener`: A function to listen for successful 3DS authentication and handle the post-authentication redirection process.

`Result and Error Handling`: Handle outcomes of the 3DS process, such as success, failure, and errors.

The 3DS Helper offers both hook-based and class-based implementations, ensuring flexibility and ease of
integration across different types of JavaScript or TypeScript projects.

## Hook-based implementation usage

Importing

```javascript
import { useThreeDSHelper } from '@mangopay/three-ds-helper';
```

Initialization

```javascript
const { openThreeDSPopup, runThreeDSRedirectListener } = useThreeDSHelper(params);
```

`params` it is an optional object with a set of callbacks with the following type definition:

`onSuccess`: A callback function triggered upon a successful 3DS authentication.

`onFailure`: A callback function triggered when 3DS authentication fails.

`onError`: A callback function triggered in case of an error during the authentication process.

### Opening 3DS Pop-up (Hook-based)

```typescript
openThreeDSPopup(secureModeRedirectURL);
```

`secureModeRedirectURL`: The URL for 3DS authentication.

### Running the 3DS Redirect Listener

```typescript
runThreeDSRedirectListener();
```

This listener checks for 3DS parameters in the URL. If found, it manages the redirection process.

### Example: Hook-based Usage

```typescript
import { ThreeDSHelperResult, useThreeDSHelper } from '@mangopay/three-ds-helper';

const handle3DSResult = (result: ThreeDSHelperResult) => {
  // handle 3DS result
};

const { runThreeDSRedirectListener, openThreeDSPopup } = useThreeDSHelper({
  onSuccess: handle3DSResult,
  onFailure: handle3DSResult,
});

// On a certain user action or event
const handlePayment = () => {
  const secureModeRedirectURL = 'https://example-3ds-url.com';
  openThreeDSPopup(secureModeRedirectURL);
};

// Run the listener, e.g., on component mount
useEffect(() => {
  runThreeDSRedirectListener();
}, [runThreeDSRedirectListener]);
```

## Class-based implementation usage

Importing

```javascript
import { ThreeDSHelper } from '@mangopay/three-ds-helper';
```

Initialization

```javascript
const threeDSHelper = new ThreeDSHelper(params);
```

`params` it is an optional object with a set of callbacks.

### Opening 3DS Pop-up (Class-based)

```typescript
threeDSHelper.present(secureModeRedirectURL);
```

`secureModeRedirectURL`: The URL for 3DS authentication.

### Running the 3DS Redirect Listener

```typescript
threeDSHelper.runThreeDSRedirectListener();
```

This method checks for 3DS parameters in the URL and manages the redirection process accordingly.

### Example: Class-based Usage

```typescript
import { ThreeDSHelper, ThreeDSHelperResult } from '@mangopay/three-ds-helper';

const handle3DSResult = (result: ThreeDSHelperResult) => {
  // handle 3DS result
};

const threeDS = new ThreeDSHelper({
  onSuccess: handle3DSResult,
  onFailure: handle3DSResult,
});

// On certain user action or event
function handlePayment() {
  const secureModeRedirectURL = 'https://example-3ds-url.com';
  threeDSHelper.present(secureModeRedirectURL);
}

// Run the 3DS Redirect Listener, e.g., on page load or after certain user actions
threeDS.runThreeDSRedirectListener();
```

### Types

```typescript
enum ThreeDSStatus {
  Succeeded = 'SUCCEEDED',
  Failed = 'FAILED',
  Error = 'ERROR',
}

enum TransactionType {
  CARD_DIRECT = 'CARD_DIRECT',
  PREAUTHORIZE = 'PREAUTHORIZE',
  CARD_VALIDATION = 'CARD_VALIDATION',
}

interface ThreeDSHelperResult {
  Id: string;
  Status: ThreeDSStatus;
  Type: TransactionType;
}

interface TypedError {
  Status?: string;
  ResultCode?: string;
  ResultMessage?: string;
}

interface ThreeDSHelperParams {
  onSuccess?: (result: ThreeDSHelperResult) => void;
  onFailure?: (result: ThreeDSHelperResult) => void;
  onError?: (error: TypedError) => void;
}
```

### Events

The package listens for message events from the authentication iframe. Recognized events trigger the handleThreeDSHelper
function, which in turn invokes the appropriate callback (onSuccess, onFailure, onError) based on the result.

---
_Source: https://npm.io/package/@mangopay/three-ds-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._