npm package: @payvision/checkout-library
Description: Payvision Checkout javascript customization library.
Author: Payvision
Latest version: 1.2.0

# Checkout.js

Checkout.js is a javascript library to easily embed Payvision checkout into your website. We directly send customers sensitive data to Payvision's servers so cardholder data does not hit your server, reducing PCI compliance requirements. Additionally, you can use the library to customize the checkout layout with your own styles.

[![npm version](https://badge.fury.io/js/%40payvision%2Fcheckout-library.svg)](https://badge.fury.io/js/%40payvision%2Fcheckout-library)

[![NpmLicense](https://img.shields.io/npm/l/%40payvision%2Fcheckout-library.svg)](https://www.npmjs.com/package/%40payvision%2Fcheckout-library)

[![npm](https://img.shields.io/npm/dt/%40payvision%2Fcheckout-library.svg)](https://www.npmjs.com/package/%40payvision%2Fcheckout-library)

## Installation

[ ⚠ **HTTPS** protocol is required ]

### Install NPM package

> Install Checkout npm package from Payvision repository:

```bash
# with npm package manager
npm i @payvision/checkout-library

# with yarn
yarn add @payvision/checkout-library
```

### Install from Payvision CDN

Import the library from Payvision CDN:

```html
<script
  src="https://cdn.payvision.com/checkout/1.2.0/checkout-library.js"
  integrity="sha384-EY45vPLgYiHuuQOzW+lJzVl0h7uQAAfy3Nxlfhjfwap1QrvXXD8R9RqSl9i0BG9L"
  crossorigin="anonymous"
></script>
```

Note that:

Use corresponding integrity "sha384-EY45vPLgYiHuuQOzW+lJzVl0h7uQAAfy3Nxlfhjfwap1QrvXXD8R9RqSl9i0BG9L" to ensure [subresource integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).

## Use of library

> Create an HTML element as the container for the checkout. The **container id** will be used to embed the checkout using the library.

```html
<div id="checkout-container"></div>
```

> Import the library in your javascript code

```javascript
import Checkout from '@payvision/checkout-library'
```

> Get a **checkout id** via API.

```javascript
const checkoutId = '6741b7d4-f413-4c98-8f5a-724f7d3192f7' // Retrieved from Checkout API
```

> Create the checkout custom options object (not required).

```javascript
const options = {
  live: true,
  styles: {
    imageUrl: 'Logo Url',
    autoHeight: false,
    generalStyles: {
      backgroundColor: '#f6f7fb',
      fontFamily: 'Source Sans Pro',
      fontFamilyUrl: 'Font family url',
      primaryThemeColor: '#213d8f',
      accentThemeColor: '#909ec7',
      secondaryThemeColor: '#909ec7',
      infoThemeColor: '#1db9de',
      warningThemeColor: '#fec61f',
      errorThemeColor: '#e6493a',
      successThemeColor: '#35ba6d',
    },
    formStyles: {
      backgroundFormColor: '#ffffff',
      backgroundFormContainerColor: '#ffffff',
      fontSize: '14px',
      borderWidth: '1px',
      borderRadius: '2px',
    },
    paymentButtonStyles: {
      fontSize: '16px',
      borderWidth: '1px',
      borderRadius: '2px',
      fontColor: '#ffffff',
      backgroundColor: '#8ec03f',
      borderColor: '#8ec03f',
    },
    iframe: {
      width: '100%',
      height: '780px',
    },
  },
}
```

> Create the checkout object with parameters from above.

```javascript
const checkout = new Checkout(checkoutId, 'checkout-container', options)
```

> use **render** method to display the checkout in checkout container HTML element.

```javascript
checkout.render()
```

## Options

|            | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **live**   | boolean | The target environment [false: staging (default), true: production]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **events** | object  | <ul><li>onReady: Function emitted when the checkout is ready.</li><li>onSuccess: Function emitted when the checkout is completed.</li><li>onError: Function emitted when an error has occurred.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **styles** | object  | <ul><li>imageUrl: 'Logo Url'</li><li>autoHeight: [*false*]</li><li>generalStyles <ul> <li>fontFamily [_'"Source Sans Pro", "Arial", "Verdana"'_]</li><li>fontFamilyUrl [' ']</li> <li>backgroundColor[<span style="color: #f6f7fb">_'#f6f7fb'_</span>]</li> <li>primaryThemeColor[<span style="color: #213d8f">_'#213d8f'_</span>]</li> <li>accentThemeColor[<span style="color: #909ec7">_'#909ec7'_</span>]</li> <li>secondaryThemeColor[<span style="color: #909ec7">_'#909ec7'_</span>]</li> <li>infoThemeColor[<span style="color: #1db9de">_'#1db9de'_</span>]</li> <li>warningThemeColor[<span style="color: #fec61f">_'#fec61f'_</span>]</li> <li>errorThemeColor[<span style="color: #e6493a">_'#e6493a'_</span>]</li> <li>successThemeColor[<span style="color: #35ba6">_'#35ba6'_</span>]</li> </ul> </li> <li> formStyles <ul> <li>backgroundFormColor[<span style="color: #ffffff">_'#ffffff'_</span>]</li> <li>backgroundFormContainerColor[<span style="color: #ffffff">_'#ffffff'_</span>]</li> <li>fontSize[<span>_14px_</span>]</li> <li>borderWidth[<span >_1px_</span>]</li> <li>borderRadius[<span>_2px_</span>]</li> </ul> </li> <li> paymentButtonStyles <ul> <li>fontColor[<span style="color: #ffffff">_'#ffffff'_</span>]</li> <li>backgroundColor[<span style="color: #8ec03f">_'#8ec03f'_</span>]</li> <li>borderColor[<span style="color: #8ec03f">_'#8ec03f'_</span>]</li> <li>fontSize[<span>_16px_</span>]</li> <li>borderWidth[<span >_1px_</span>]</li> <li>borderRadius[<span>_2px_</span>]</li> </ul> </li> iframe <ul> <li> width ['100%'] </li> <li> heigth ['780px'] </li> </ul> </ul> |

\*_[Default parameters]_

## Environments

You can configure the library for development purposes if set the `option.live` to false. If you want to release your build to production you have to set the target to live environment with the `option.live` set to true.

| Environment | Url                                                                    |
| ----------- | ---------------------------------------------------------------------- |
| Live        | https://connect.acehubpaymentservices.com/gateway/v3/web/checkouts     |
| Staging     | https://stagconnect.acehubpaymentservices.com/gateway/v3/web/checkouts |

## Helper methods

Checkout.js provides the following helper methods to manipulate Checkout UI.

| Method       | Parameters | Description         | Example  |
| ------------ | ---------- | ------------------- | -------- |
| **show()**   | none       | Displays Checkout   | show()   |
| **hide()**   | none       | Hides Checkout      | hide()   |
| **render()** | none       | Renders Checkout UI | render() |

## Events

Checkout.js provides the following helper methods to manipulate Checkout UI.

| Method             	| Parameters   	| Description                    	| Example                                                                                                                             	|
|--------------------	|--------------	|--------------------------------	|-------------------------------------------------------------------------------------------------------------------------------------	|
| **onReady**        	| Checkout     	| Checkout ready to be displayed 	| onReady: checkout => checkout.show()                                                                                                	|
| **onError**        	| Error        	| Error in checkout              	| onError: error => console.log(error.message)                                                                                        	|
| **onSuccess**      	| Redirect     	| Checkout completed             	| onSuccess: redirect => redirect.method === 'GET' ? window.location.assign(redirect.url) : submitForm(redirect.url, redirect.fields) 	|
| **onMobileIntent** 	| MobileIntent 	| Mobile intent dispatched       	| onMobileIntent: intent => launchMobileIntent(intent)                                                                                	|

## 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