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

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

Initialization

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)

openThreeDSPopup(secureModeRedirectURL);

secureModeRedirectURL: The URL for 3DS authentication.

Running the 3DS Redirect Listener

runThreeDSRedirectListener();

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

Example: Hook-based Usage

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

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

Initialization

const threeDSHelper = new ThreeDSHelper(params);

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

Opening 3DS Pop-up (Class-based)

threeDSHelper.present(secureModeRedirectURL);

secureModeRedirectURL: The URL for 3DS authentication.

Running the 3DS Redirect Listener

threeDSHelper.runThreeDSRedirectListener();

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

Example: Class-based Usage

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

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.