npm package: @payvision/threedsecure2-library
Description: Payvision 3DS2 javascript library.
Author: Payvision
Latest version: 1.1.3

# threedsecure2-library.js

![npm](https://img.shields.io/npm/v/@payvision/threedsecure2-library)
![NPM](https://img.shields.io/npm/l/@payvision/threedsecure2-library)
![npm](https://img.shields.io/npm/dw/@payvision/threedsecure2-library)
[![Build Status](https://dev.azure.com/payvision/NightsWatch/_apis/build/status/3ds-collector-library/CI-3ds-collector-library?branchName=master)](https://dev.azure.com/payvision/NightsWatch/_build/latest?definitionId=7903&branchName=master)

Payvision @payvision/threedsecure2-library.js is a JavaScript library used to collect the customer’s browser data and render the authentication challenge (if applicable) within the Merchant’s website to complete Payvision 3D Secure 2.0 Strong Customer Authentication process.

## Installation

### Install from NPM package

Install 3DS2 Secure library npm package from Payvision repository:

```bash
# using npm
npm i @payvision/threedsecure2-library

# using yarn
yarn add @payvision/threedsecure2-library
```

### Install from Payvision CDN

You have two options to install the library from the CDN, choose the one you like:

- Import the resource as html script tag

  Import the library from Payvision CDN:

  ```html
  <script
    src="https://cdn.payvision.com/threedsecure2/1.1.3/threedsecure2-library.js"
    integrity="sha384-wrgHcOuaf7c/l1wU5O9vVRuTLY9X3sUoDSsiUhdOKsfNqBA7oU4WWcqCw+BEOUWm"
    crossorigin="anonymous"
  ></script>
  ```

- Install the package from a remote gzipped tarball

  Install the library from Payvision CDN:

  ```bash
  # using npm
  yarn add http://cdn.payvision.com/threedsecure2/1.1.3/threedsecure2-library.tgz

  # using yarn
  yarn add http://cdn.payvision.com/threedsecure2/1.1.3/threedsecure2-library.tgz
  ```

Note that:

Use corresponding integrity "sha384-wrgHcOuaf7c/l1wU5O9vVRuTLY9X3sUoDSsiUhdOKsfNqBA7oU4WWcqCw+BEOUWm" to ensure [subresource integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).

## Use of library

If using NPM, import the library:

```javascript
import ThreeDSecure2 from '@payvision/threedsecure2-library'
```

Create ThreeDSecure2 redirection object (mandatory):

```javascript
const redirect = {
  method: 'POST',
  url: 'https://merchant.com/returnUrl',
  fields: {
    ...
  },
}
```

Create ThreeDSecure2 options object (optional):

```javascript
const options = {
  sandbox: true,
}
```

Create an instance of ThreeDSecure2:

```javascript
const threeDSecure = new ThreeDSecure2(options)
```

Call authenticate method from object instance:

```javascript
const response = await threeDSecure.authenticate(redirect)
```

Get the payment status using the [`response`](#response-object-fields).

## Example

Firstly, you must send a Payment request to Acehub Payments endpoint. If 3DS 2.0 authentication is requested, the response object returned contains an object filed named "redirection". Use this object create:

```javascript
import ThreeDSecure2 from '@payvision/threedsecure2-library'

// Submit your payment request to Acehub
const acehubResponse = yourAcehubProxy.submitPayment(...)
const redirect = acehubResponse.body.redirect
```

Acehub response redirect object looks like the following object:

```javascript
const redirect = {
  method: 'POST',
  url: 'https://merchant.com/returnUrl',
  fields: {
    ...
  },
}
```

Set your options object:

```javascript
const options = {
  sandbox: true,
}
```

Create a `@payvision/threedsecure2-library` instance and invoke authenticate method to trigger 3DS 2.0 process:

```javascript
const threeDSecure = new ThreeDSecure2(options)

const response = await threeDSecure.authenticate(redirect)
```

Finally, use the [`response`](#response-object-fields) variable to create and submit the form.

## Options

| Field   | Type    | Description                    | Default |
| ------- | ------- | ------------------------------ | ------- |
| sandbox | boolean | Staging true, Production false | false   |

## Response object fields

| Field  | Type   | Description                                                                           |
| ------ | ------ | ------------------------------------------------------------------------------------- |
| method | string | HTTP method: GET/POST...                                                              |
| url    | string | Merchant return url used after authentication                                         |
| fields | object | Returned from Acehub Payment request. Within this object is included the payment `Id` |

## Available methods

| Method         | Parameters                                        | Description                   |
| -------------- | ------------------------------------------------- | ----------------------------- |
| authenticate() | [Response object fields](#response-object-fields) | Starts authentication process |

## Supported browsers

| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt="IE / Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>IE / Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari-ios/safari-ios_48x48.png" alt="iOS Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>iOS Safari </br>Opera |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IE11, Edge                                                                                                                                                                                                      | last 2 versions                                                                                                                                                                                                   | last 2 versions                                                                                                                                                                                               | last 2 versions                                                                                                                                                                                               | last 2 versions                                                                                                                                                                                                                          |

## Copyright

Payvision © 2020