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.

Requirements

Node 10 or higher.

Getting Started

1. Register on your Zilla Merchant dashboard to get your public and secret keys.

Installation

You can install the package using NPM or Yarn;

npm install  @usezilla/zilla-connect

or

yarn add @usezilla/zilla-connect

Then import it into your project;

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

or use our CDN

<script src="https://cdn.jsdelivr.net/npm/@usezilla/[email protected]/index.js"></script>

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

const connect = new Connect();

Methods

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

• openById() You can use this if have your own server and choose to create your order from your server (see how) to generate an id(orderCode) that you can pass as a parameter to your zilla connect instance.

• 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

openById

These are the required parameters for openById()

• publicKey
• onSuccess
• orderCode

e.g

const connect = new Connect();

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

connect.openId(config)

openNew

These are the required parameters for openNew()

• publicKey
• onSuccess
• clientOrderReference
• title
• amount

e.g

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);

Parameters

• publicKey
• onSuccess
• onClose
• onLoad
• onEvent
• clientOrderReference
• orderCode
• title
• amount
• category
• redirectUrl

key

Required
This is your Zilla public API key from the Zilla merchant dashboard. It is required for both openNew() and openById() method

const config = { key: "public_key" };

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

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

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.

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

onLoad

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

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

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

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

};

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

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.

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

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

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

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

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

amount

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

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

category

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

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

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

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 [email protected] or come chat with us on Slack. We're more than happy to help you out with your integration to Zilla.

License

MIT