npm package: @gatefi/js-sdk
Description: SDK for Unlimit
Latest version: 1.2.0

# Unlimit JS SDK
[Full documentation](https://docs.gatefi.com/)

## Get started
Unlimit can be integrated in a variety of ways. The supported integration modes make it possible to find the configuration that is most suitable for your project.

```
$ yarn add @gatefi/js-sdk
```
or
```
$ npm install @gatefi/js-sdk
```

Once the npm package is installed, you need to configure the constructor of our SDK. For the overlay mode, the simplest configuration will look as follows:

```javascript
var instance = new gateFiSDK.GateFiSDK({
    merchantId: "testID",
    displayMode: "embedded",
    nodeSelector: "#container",
})
```


## SDK Configuration Options

The Unlimit widget provides multiple customization options that can be used to modify the look of the payment form. The following configuration parameters are available:

| PARAMETER          |         | TYPE            | REQUIRED | DESCRIPTION                                                                                                                                                                  |
|--------------------|---------|-----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| merchantId         |         | String          | Y        | ID of the user account.                                                                                                                                                      |
| displayMode        |         | String          | Y        | Specifies the display mode. Possible options:<br>- `embedded`<br>- `overlay`                                                                                                 |
| nodeSelector       |         | String          | 	Y       | 	Defines the .CSS selector related to the HTML element, where you want to integrate the widget.                                                                              |
| externalId         |         | String	         |	       | Custom ID of the order.                                                                                                                                                      |
| walletAddress      |         | String	         |	       | Pre-populates the wallet address, to which the purchased cryptocurrency will be sent.                                                                                        |
| walletMemo         |         | String	         |	       | Pre-populates the memo/tag for wallet address.                                                                                                                               |
| email              |         | String	         |        | 	Pre-populates the user's e-mail address.                                                                                                                                    |
| hideThemeSwitcher  |         | Boolean	        |        | Allows to hide the theme switcher in the widget.                                                                                                                             |
| defaultFiat        |         | Object          |       | 	An object that sets the default fiat currency type and amount.                                                                                                              |
|                    | currency	 | String          |	      | Sets the default fiat currency type.                                                                                                                                         |
|                    | amount  | 	String         |       | 	Sets the default fiat currency amount.                                                                                                                                      |
| defaultCrypto      |         | Object          |       | 	An object that sets the default cryptocurrency type and amount.                                                                                                             |
|                    | currency	 | String          |       | 	Sets the default cryptocurrency type.                                                                                                                                       |
|                    | amount  | 	String         |       | 	Sets the default cryptocurrency amount.                                                                                                                                     |
| availableCrypto    |         | Array (string)	 |	       | Defines a list of available cryptocurrencies.                                                                                                                                |
| availableFiat      |         | Array (string)	 |	       | Defines a list of available fiat currencies.                                                                                                                                 |
| styles             |         | Object	         |	       | An object that customizes the look of the widget.                                                                                                                            |
|                    |type	    | String	         |	       | Specifies the theme for which you want to customize the look of the widget. Possible options:<br>- `dark`<br>- `light`                                                       |
|                    |primaryBackground	 | String	         |	       | Specifies the background color.                                                                                                                                              |
|                    |secondaryBackground	 | String	         |	       | Specifies an additional background color.                                                                                                                                    |
|                    | primaryColor	 | String	         |	       | Specifies the main color for the widget elements (text, buttons, hyperlinks, etc.).                                                                                          |
|                    | secondaryColor	 | String	         |	       | Specifies an additional color for the main elements (text, buttons, hyperlinks, etc.).                                                                                       |
|                    | primaryTextColor| String	         |        | Specifies an additional color for text elements (label inside primary button)                                                                                                |
| isSandbox          | 	 | Boolean	        |	       | Defines if the widget is used in the sandbox mode.                                                                                                                           |
| walletLock         | 	 | Boolean	        |	       | Blocks the ability to change the crypto wallet address.                                                                                                                      |
| walletMemoLock     | 	 | Boolean	        |	       | Blocks the ability to change the crypto wallet address memo.                                                                                                                 |
| fiatAmountLock     | 	 | Boolean	        |	       | Blocks the ability to change the amount for fiat currency.                                                                                                                   |
| cryptoAmountLock   | 	 | Boolean	        |	       | Blocks the ability to change the amount for cryptocurrency.                                                                                                                  |
| fiatCurrencyLock   | 	 | Boolean	        |	       | Blocks the ability to select a fiat currency.                                                                                                                                |
| cryptoCurrencyLock | 	 | Boolean	        |	       | Blocks the ability to select a cryptocurrency.                                                                                                                               |
| hideAsset          | 	 | Boolean	        |	       | Hide the cryptocurrency field.                                                                                                                                               | |
| hideThemeSwitcher  | 	 | Boolean	        |	       | Defines if the theme switcher link should be hidden.                                                                                                                         |
| successUrl         | 	 | String	         |	       | Defines the URL for redirection after the payment is successful.                                                                                                             |
| cancelUrl          | 	 | String	         |	       | Defines the URL for redirection after the payment is cancelled.                                                                                                              |
| declineUrl         | 	 | String	         |	       | Defines the URL for redirection after the payment is declined.                                                                                                               |                                                                                                              |
| inprocessUrl       | 	 | String	         |	       | Defines the redirect URL for in process status of payment.                                                                                                                   |                                                                                                              |
| availablePayments  | 	 | Array (string)	 |	       | Lists the available payment method codes.                                                                                                                                    |
| payment            | 	 | String	         |	       | Sets the payment method code for the order.                                                                                                                                  |
| payout             | 	 | String	         |	       | Sets the payout method code for the order.                                                                                                                                   |
| region             | 	 | String	         |	       | Pre-sets the user's region. Can be a country ID (for example: US) or state ID (for example: US-AL).                                                                          |
| lang               | 	 | String	         |	       | Specifies the language of the widget. Possible options:<br>- `GateFiLangEnum.es_PE (Spanish)`<br>- `GateFiLangEnum.en_US (English)`<br>- `GateFiLangEnum.pt_BR (Portuguese)`<br>- `GateFiLangEnum.id_ID (Indonesian)` |
| redirectUrl        | 	 | String	         |	       | Redirects the user to this url after the purchase has been performed and the user has clicked "Back to Shop" button in the platform widget. For example: https://google.com  |
| meta               | 	 | Object	         |	       | Custom parameters for webhooks.                                                                                                                                              |
| customTexts        | 	 | Object	         |	       | An object with custom texts.                                                                                                                                                 |
|                    | backToButtonLabel	 | String	         |	       | Custom text for manual redirect button. Default text: Back to Shop                                                                                                           |
| confirmRedirectUrl | 	 | String	         |	       | Redirects the user to this url after the order has been created. This param allowed in OFF-RAMP flow.                                                                        |
| authToken          | 	 | String	         |	       | A token for login user to account.                                                                                                                                           |
| userId             | 	 | String	         |	       | User ID in your system for identify user and skip sign in & sign up flow in widget.                                                                                          |
| fingerprint        | 	 | String	         |	       | Fingerprint hash for skip sign in & sign up flow in widget. Use @fingerprintjs/fingerprintjs package for generate this param.                                                |

## Events

Using the `.subscribe()` и `.unsubscribe()` methods provided in the Unlimit SDK, the merchant can subscribe/unsubscribe to the widget-related events. It is possible to subscribe to the following events:

- `onLoad` - the widget is loaded and ready to work (after that, the configuration is sent to the widget).
- `onClose` - the widget was closed by the customer (after that, the widget dialog is closed). This event is relevant only for the overlay mode.
- `onRedirectBack` - the widget was redirected by redirectUrl parameter (click to "Back to Shop" button on order status screen).

Below is an example of subscription to widget-related events:

```javascript
var instance = new gateFiSDK.GateFiSDK({
  merchantId: "testID",
  displayMode: "overlay",
  nodeSelector: "container"
})

instance.subscribe(GateFiEventTypes.onClose, (type, payload) => {
   console.log(type, payload)
})
```

## Callbacks

Using a variety of methods provided in the Unlimit SDK, the merchant can manipulate the widget. The following actions are available:

- `hide()` - closes the widget dialog (this method is relevant only for the overlay mode).
- `setThemeType(type: "dark" | "light")` - sets the theme for the widget.
- `show()` - displays the widget dialog (this method is relevant only for the overlay mode).
- `destroy()` - removes the instance of the widget (deletes the widget from DOM).