@payoneer/op-risk-lib/README.md

JS client-side library for risk management

<!-- README FILE FOR NPM | CONSUMERS | END-USERS -->

# RiskLib (Risk Client Library)
Client-Side (Javascript) library used to 
- Load/initialize 3rd-party risk-provider scripts inside iframes
- Collect data from those 3rd-party risk-provider scripts
- Return stored data in a specific format (at any given time)

> You only need to use it as a standalone library if you are building your own native integration to Payoneer Checkout APIs. 
> It is included in our Web SDK by default, which is usually the best way to integrate our payment services on your checkout page.

Documentation and examples can be found here: https://checkoutdocs.payoneer.com/docs/add-your-js-risk-library

---
<br />


## Installation
Install the library directly from npm by executing the following command

``` bash
npm install @payoneer/op-risk-lib
```


---
<br />


## Usage
The library is exposed in multiple form.

> ### As a JS Module
Import `RiskLib` to use the library.

``` js
import RiskLib from "@payoneer/op-risk-lib";
```

> ### As commonJs
Require `RiskLib` to use the library.

``` js
const RiskLib = require("@payoneer/op-risk-lib");
```

> ### As a script (iife)
Use the file named `op-risk-lib.js` with __.js__ extension. Once loaded, access a global variable/instance named `RiskLib` to use the library.

``` html
<script type="text/javascript" src="https://checkout.payoneer.com/web/libraries/risk/op-risk-lib.js"></script>
```


---
<br />


## Methods
The library exposes following methods

### `init`
Method to initialize the library. It requires an array of input configs 
(`riskProviders` key's value from LIST response) that is used to configure/initialize library. 
During the initialization process, library reads the input config, validates it, filters invalid configs 
and generates dynamic iframe for the valid configs to load the 3rd-party risk-provider scripts


> #### Method Parameters

|         NAME        |     TYPE     |   REQUIRED   |                   DESCRIPTION                  |
| :-----------------: | :----------: | :----------: | :--------------------------------------------: |
| riskProviderConfigs |   []Object   |     true     | `riskProviders` key's value from LIST response |


> #### Example (usage)

```JS
RiskLib.init([{...}]);
```

<br />

### `getRiskData`
Returns an array of stored information in a specific format

> #### Example (usage)

```JS
const data = RiskLib.getRiskData();
```

<br />

### `destroy`
Remove all content generated by library. That includes dynamically created iframes, stored data and event listeners

> #### Example (usage)
> 
```JS
RiskLib.destroy();
```

<br />

### `configureExternalStorage`
Method to configure and external storage to temporarily store the received information from risk-provider scripts

__Library comes with internal storage, configuring external storage is optional__

> #### Method Parameters
|     NAME    |   TYPE    |   REQUIRED    |                     DESCRIPTION                     |
| :---------: | :-------: | :-----------: | :-------------------------------------------------: |
|   setData   |  function |     true      | callback that receives `key`, `value` as parameters |
|   getData   |  function |     true      | callback that receives `key` as parameter           |
|  removeData |  function |     true      | callback that receives `key` as parameter           |

> #### Example (usage)
> 
```JS
const storeData = (key, value) => {
    ...code
};
const getData = (key) => {
    ...code
};
const removeData = (key) => {
    ...code
};

RiskLib.configureExternalStorage(storeData, getData, removeData);
```


---
<br />


## License
`op-risk-lib` is licensed under [Payoneer](./LICENSE)