@usezilla/zilla-connect/README.md

Zilla sdk to allow users make payments on merchants application

# Zilla Connect

Zilla connect is an easy, fast and secure way for your users to buy now and pay later from your app. It is a drop in framework that allows you host the Zilla checkout application within your application and allow customers make payments using any of the available payment plans. Zilla connect also supports all major javascript frameworks!

## Documentation

For complete information about other Zilla Connect SDKs, head to the [docs](https://www.notion.so/usezilla/Zilla-Connect-3e109a8afc7a4e29a72baa4225f529a3).

## Requirements

Node 10 or higher.

## Getting Started

<!-- Register on your Zilla Merchant  -->

1. Register on your [Zilla](https://merchant.usezilla.com/register) Merchant dashboard to get your public and secret keys.

## Installation

You can install the package using NPM or Yarn;

```bash
npm install  @usezilla/zilla-connect
```

or

```bash
yarn add @usezilla/zilla-connect
```

Then import it into your project;

```js
import Connect from "@usezilla/zilla-connect";
```

or use our CDN

```js
<script src="https://cdn.jsdelivr.net/npm/@usezilla/zilla-connect@1.0.6/index.js"></script>
```

Then in your code, create a new instance of the Zilla connect

```js
const connect = new Connect();
```

## Methods

There are two ways to make use of the zilla-connect sdk

- [`openById()`](#openById)
  You can use this if have your own server and choose to create your order from your server [(see how)](https://www.notion.so/usezilla/Accepting-payments-5528b21e758244878d9b72acbdb8500c) to generate an `id`(`orderCode`) that you can pass as a parameter to your zilla connect instance.

- [`openNew()`](#openNew)
  You can use this if you want to create your order on the fly from your frontend. Your order parameters are passed to the zilla connect instance

## Usage

### <a name="openById"></a> `openById`

These are the `required` parameters for `openById()`

- [`publicKey`](#key)
- [`onSuccess`](#onSuccess)
- [`orderCode`](#orderCode)

e.g

```js
const connect = new Connect();

const config = {
  publicKey: "public_key",
  onSuccess: (data) => console.log(data)
  orderCode: "orderCode"
}

connect.openId(config)
```

### <a name="openNew"></a> `openNew`

These are the `required` parameters for `openNew()`

- [`publicKey`](#key)
- [`onSuccess`](#onSuccess)
- [`clientOrderReference`](#clientOrderReference)
- [`title`](#title)
- [`amount`](#amount)

e.g

```js
const connect = new Connect();

const config = {
  publicKey: "public_key",
  onSuccess: (data) => console.log(data),
  clientOrderReference: "random string",
  title: "order title",
  amount: "order amount",
};

connect.openNew(config);
```

<!-- **Required**
This is your Zilla public API key from the [Zilla merchant dashboard](https://merchant.usezilla.com).

```js
const config = { key: "public_key" };
``` -->

<!-- Click the links below for detailed examples on how to use connect.js with your favourite framework;
- [React](docs/examples/react.md)
- [Angular](docs/examples/angular.md)
- [Next.js](docs/examples/nextjs.md)

> NOTE
> The list above is not exhaustive, you can use this package in other frontend javascript frameworks. -->

## Parameters

<!-- - [`setupConfig`](#setupConfig) -->

- [`publicKey`](#key)
- [`onSuccess`](#onSuccess)
- [`onClose`](#onClose)
- [`onLoad`](#onLoad)
- [`onEvent`](#onEvent)
- [`clientOrderReference`](#clientOrderReference)
- [`orderCode`](#orderCode)
- [`title`](#title)
- [`amount`](#amount)
- [`category`](#category)
- [`redirectUrl`](#redirectUrl)

<!-- ### <a name="setupConfig"></a> `setupConfig`

This optional configuration object is used as a way to load the Connect Widget directly to an institution login page.

```js
const config = {
  selectedInstitution: {
    id: "5f2d08c060b92e2888287706", // the id of the institution to load
    auth_method: "internet_banking", // internet_banking or mobile_banking
  },
};

connect.setup(config);
``` -->

### <a name="key"></a> `key`

**Required**  
This is your Zilla public API key from the [Zilla merchant dashboard](https://merchant.usezilla.com). It is required for both `openNew()` and `openById()` method

```js
const config = { key: "public_key" };
```

### <a name="onSuccess"></a> `onSuccess`

**Required**
This function is called when a user has successfully completed a transaction. it takes in an optional parameter and returns a data object containing `status` `zillaOrderCode` and `clientOrderReference`

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data),
};
```

### <a name="onClose"></a> `onClose`

The optional function is called when the user exits the application or checkout flow(i.e. the widget is not visible to the user). It does not take any arguments.

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  onClose: () => console.log("widget has been closed"),
};
```

### <a name="onLoad"></a> `onLoad`

This callback is invoked when the widget has been successfully loaded or mounted on the DOM

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  onLoad: () => console.log("widget loaded successfully"),
};
```

### <a name="onEvent"></a> `onEvent`

This optional callback is called when certain events are performed on the application e.g when a user completes a transaction or when he closes an widget etc

<!-- See the [data](#dataObject) object below for details. -->

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  onEvent: (eventName, data) =>
    console.log(eventName);
    console.log(data);

};
```

#### <a name="eventName"></a> `eventName`

Event names correspond to the `type` key returned by the raw event data. Possible options are in the table below.

| Event Name   | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| OPENED       | Triggered when the user opens the Connect Widget.                                                       |
| LOADED       | Triggered when the widget has successfully mounted on the DOM.                                          |
| ORDER_VALID  | Triggered when we have validated the orderCode is a valid i.e exists on our system or hasn't been used. |
| ERROR        | Triggered when there's an error at certain stages in the application e.g when `orderCode` is invalid.   |
| CLOSE_WIDGET | Triggered when the user closes the widget.                                                              |
| SUCCESS      | Triggered when the user successfully makes a payment.                                                   |
| EVENT        | Triggered when some general events occur on the widget.                                                 |

### <a name="clientOrderReference"></a> `clientOrderReference`

This required string in `openNew()` is used as a reference to the current instance of Zilla Connect. It's recommended to pass a random string.

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  clientOrderReference: "some_random_string",
};
```

### <a name="orderCode"></a> `orderCode`

This parameter is `required` if you're using the `openById()` method, it is the order code generated from your backend before passing it as a parameter

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  orderCode: "Zilla OrderCode",
};
```

### <a name="title"></a> `title`

This parameter is `required` if you're using the `openNew()` method which requires you to create the order from your front end, It is the title of your order you want to create

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  title: "Zilla order title",
};
```

### <a name="amount"></a> `amount`

This parameter is `required` if you're using the `openNew()`. This parameter contains the amount for an order you want to create

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  amount: "Zilla order amount",
};
```

### <a name="category"></a> `category`

This optional parameter is used if you're using the `openNew()`. This parameter contains the category for which your product or order belongs

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  category: "Zilla order category",
};
```

### <a name="redirectUrl"></a> `redirectUrl`

This optional parameter is used if you're using the `openNew()` method. This parameter contains the redirectUrl which you would want your customer to be taken to upon successfully completing a payment or closing the widget

```js
const config = {
  key: "public_key",
  onSuccess: (data) => console.log(data)
  redirectUrl: "Merchant redirectUrl",
};
```

## Support

If you're having general difficulties with Zilla Connect or your Sdk integration, please reach out to us at <boost@zilla.africa> or come chat with us on Slack. We're more than happy to help you out with your integration to Zilla.

## License

`MIT`