npm package: @fluidcoins/pay.js
Description: Fluidcoins Pay Javascript SDK
Author: Fluidcoins Inc.
Latest version: 0.1.15

## Documentation
# Fluidcoins Pay.js

Fluidcoins Pay.js is quick and secure way to receive crypto payments in your application. It works with all Javascript frameworks
## Requirement

Nodejs version > 10 

## Getting Started
1: Register a merchant account on [Fluidcoins](https://fluidcoins.com/) and get your public API key

## Installation

You can install the package via NPM or Yarn;

```
npm install @fluidcoins/pay.js
```

OR

```
yarn add @fluidcoins/pay.js
```

## Usage

Parameters
- `key`
- `amount`
- `email`
- `onSuccess`
- `onLoad` (optional)
- `onClose` (optional)
- `onError` (optional)
- `name` (optional)
- `phone` (optional)
- `metadata` (optional)
- `callback_url` (optional)
- `currency` (optional)
- `reference` (optional)

**_`key`_**

**REQUIRED**

This is your Fluidcoins public API key from the [Fluidcoins dashboard](https://fluidcoins.com/).

```
new Fluidcoins({key: 'fluidcoins_public_api_key'})
```


**_`amount`_**

**REQUIRED**

This is amount in the smallest unit of currency you'd want to receive from the customer. 

**NOTE: The minimum amounts are**
- 500 NGN for the Nigerian Naira 
- 1 USD for the United State Dollars


```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 50000 // or 100 for 1 USD
})
```

**_`email`_**

**REQUIRED**

This is the email address of the customer 

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com'
})
```

**_`onSuccess`_**

**REQUIRED**

This is function that will be called when a successful transaction occurs.

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})}
})
```

 A JSON payload is passed as argument with the structure below;

``` 
{ 
    reference: TRANS_REFERENCE,
    coin: 'BTC',
    human_readable_amount: 1000,
    payment_status: 'underpaid | overpaid | paid_in_full'
}
```
> Payment status could be overpaid, underpaid or paid_in_full

**_`onLoad`_**

**OPTIONAL**

This closure is called once the Fluidcoins PaySDK loads

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')}
})
```

**_`onClose`_**

**OPTIONAL**

This optional closure is called when a user closes the Fluidcoins Widget. It takes no argument

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')}
})
```

**_`onError`_**

**OPTIONAL**

This optional closure is called when an error occurs. Error such as session expired, etc.

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
})
```
A JSON payload is passed as argument with the structure below;

``` 
{ 
    type: 'expired',
}
```
> Error type could be; 
>
>   - expired : Payment session for the initiated transaction expired


**_`name`_**

**OPTIONAL**

This optional parameter; which is the name of customer who want to initiate the transaction. It reflects on the  [Fluidcoins dashboard](https://fluidcoins.com/).

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni'
})
```

**_`phone`_**

**OPTIONAL**

This optional parameter; which is the phone number of customer who want to initiate the transaction. It reflects on the  [Fluidcoins dashboard](https://fluidcoins.com/).

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
})
```

**_`reference`_**

**OPTIONAL**

This optional parameter; which is used to identify the initiated transaction.

**NOTE** : It must be unique per transaction

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
    reference: 'random-identifier'
})
```

**_`metadata`_**

**OPTIONAL**

This optional parameter, which is should contain data you will like to be passed via webhooks about the transaction.
NOTE: The _metadata_ must be an **OBJECT**

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
    metadata: {
        key: 1
    }
})
```

**_`callback_url`_**

**OPTIONAL**

This optional parameter is used to open a new window tab when a successful [ underpaid, overpaid, paid_in_full ] payment occurs.
NOTE: The _callback_url_ must be a valid URL with a **HTTPS scheme** . Also, it **DOES NOT** override the onSuccess() event.

```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
    metadata: {
        key: 1
    },
    callback_url: 'https://www.google.com/'
})
```

**_`currency`_**

**OPTIONAL**

Possible values are the ISO 4217 currency codes, such as "USD" for the US dollar"

NOTE: It defaults to default currency set on your [Fluidcoins](https://fluidcoins.com/)  dashboard.


```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
    metadata: {
        key: 1
    },
    callback_url: 'https://www.google.com/',
    currency: 'USD'
})
```

**_`reference`_**

**OPTIONAL**

This optional parameter is used as a reference instead of the Fluidcoins auto-generated reference. We recommended random string.


```
new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onLoad: () => { console.log('Loaded sdk successfully')},
    onClose: () => { console.log('User closed widget')},
    onError: (error) => { console.log({error})},
    name: 'Seun Akanni',
    phone: '+2348090909090',
    metadata: {
        key: 1
    },
    callback_url: 'https://www.google.com/',
    currency: 'USD',
    reference: 'REF_random_reference'
})
```
## API References

**_`setup()`_**

This method is used to load the widget unto the DOM, the widget remains hidden after invoking this function until the open() method is called.

```
const fluidcoins = new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
})
fluidcoins.setup()
```

**_`open()`_**

This method makes the widget visible to the user.

```
const fluidcoins = new Fluidcoins({
    key: 'fluidcoins_public_api_key',
    amount: 100000,
    email: 'customer@test.com',
    onSuccess: (data) => { console.log({data})},
})
fluidcoins.setup()
fluidcoins.open()
```

## More on Documentations
[Fluidcoins Developer's section](http://developers.fluidcoins.com/)