Zeeh Connect-js

Zeeh Connect is a drop-in framework that handles connecting a financial institution to your app (e.g credential validation, multi-factor authentication, error handling, etc). It works with all major javascript frameworks. Zeeh Connect-js is simply a quick and secure way to link bank accounts to Zeeh from within your app.

If you are longing to acessss customer accounts (Identity, Transactions, etc) and wants to interact with Zeeh's API , please read the documentation on how to use the server-side Zeeh API.

Documentation

For a complete information about Zeeh Connect-js, click here to read our comprehensive documentation to that regards.

Requirements

Node 10 or higher.

Getting Started

1. Register/Sign-up on the Zeeh website and get your *public and secret keys. (This publicKey is required in setting up the Zeeh Connect-js Widget)

2. Create an App with the *company name of your choice that your want your customers to be linking to. (This companyName is also required in setting up the Zeeh Connect-js Widget). Please read more here creating an App.

Installation

To install the package you can use NPM or Yarn;

npm install zeeh-connect-js

or

yarn add zeeh-connect-js

Then import it into your project;

import ZeehConnect from 'zeeh-connect-js'

Usage

Click the links below for detailed examples on how to use zeeh-connect-js with your favourite framework;

• React
• Angular
• Next.js

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

Parameters

• key
• companyName
• onSuccess
• onLoad
• onClose
• onEvent
• reference
• setupConfig

key

Required
This is your Zeeh public API key from the Zeeh dashboard gotten from the App you intend to use in onboarding your customers.

new ZeehConnect({ key: 'zeeh_public_key' });

companyName

Required
This is otherwise the appName accociated with the App you intend to use in onboarding your customers. (you might have more than one app for different purpose - e.g Connect, KYC etc - hense, you need both the companyName & publicKey to set-up the Zeeh Connect-js Widget.

new ZeehConnect({ companyName: 'app_name' });

onSuccess

Required This function is called when a user has successfully onboarded their account.

new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({ code }) => console.log(`Linked successfully: ${code}`),
});

onLoad

This function is invoked when the widget has been mounted unto the DOM. You can handle toggling your trigger button within this callback.

new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({ code }) => console.log(`Linked successfully: ${code}`),
  onLoad: () => console.log("widget loaded successfully")
});

onClose

The optional closure is called when a user has specifically exited the Zeeh Connect-js flow (i.e. the widget is not visible to the user). It does not take any arguments.

new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onClose: () => console.log("widget has been closed")
});

onEvent

This optional function is called when certain events in the Zeeh Connect-js flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into the Zeeh Connect onboarding flow.

See the data object below for details.

new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({ code }) => console.log(code),
  onEvent: (eventName, data) => {
    console.log(eventName);
    console.log(data);
  }
});

reference

This optional string is used as a reference to the current instance of Zeeh Connect-js. It will be passed to the data object in all onEvent callbacks. It's recommended to pass a random string.

new Connect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({code}) => console.log("code", code),
  reference: "some_random_string"
});

setupConfig

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

const config = {
  selectedInstitution: {
    id: "7g5d08c060b92e2888284419", // the id of the institution to load
    method: "internet_banking" // internet_banking or mobile_banking
  }
}

connect.setup(config);

API Reference

setup(config: object)

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

const connect = new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({code}) => console.log("code", code),
  onLoad: () => console.log("widget loaded successfully"),
  onClose: () => console.log("widget has been closed"),
  onEvent: (eventName, data) => {
    console.log(eventName);
    console.log(data);
  },
  reference: "random_string"
});

const config = {
  selectedInstitution: {
    id: "7g5d08c060b92e2888284419",
    method: "internet_banking"
  }
}

connect.setup(config);

open()

This method makes the widget visible to the user.

const connect = new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({code}) => console.log("code", code),
});

connect.setup();
connect.open();

close()

This method programatically hides the widget after it's been opened.

const connect = new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({code}) => console.log("code", code),
});

connect.setup();
connect.open();

// this closes the widget 5seconds after it has been opened
setTimeout(() => connect.close(), 5000)

onEvent Callback

The onEvent callback returns two paramters, eventName a string containing the event name and data an object that contains event metadata.

const connect = new ZeehConnect({
  key: 'zeeh_public_key',
  companyName: 'app_name',
  onSuccess: ({code}) => console.log("code", code),
  onEvent: (eventName, data) => {
    if(eventName == "OPENED"){
      console.log("Widget opened");
    }else if(eventName == "INSTITUTION_SELECTED"){
      console.log("Selected institution: "+data.institution.name);
    }
    console.log(eventName)
    console.log(data)
  }
});

eventName

Event names corespond 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. | | EXIT | Triggered when the user closes the Connect Widget. | | INSTITUTION_SELECTED | Triggered when the user selects an institution. | | ACCOUNT_LINKED | Triggered when the user successfully links their account. | | ERROR | Triggered when the widget reports an error.|

Support

If you're having general trouble with Zeeh Connect-js or your Zeeh integration, please reach out to us at [email protected] or come chat with us on Slack. We're proud of our level of service, and we're more than happy to help you out with your integration to Zeeh.

Contributing

If you find any issue using this package please let us know by filing an issue right here.

If you would like to contribute to the Zeeh Connect-js, please make sure to read our contributor guidelines.

License

MIT for more information.