Integration Guide

Overview

This guide will put you through the necessary steps to take when trying to Integrate Mono Connect into your software solution. Please check out our populated list of SDKs in our documentation here for whichever platform you will want to integrate with, be it Android, Flutter, IOS or the Web.

For the sake of this guide, we will be integrating with our Inline Connect SDK.

Prerequisites

To get started, please ensure to:

• Sign up on the Mono Dashboard ➡
• Create an App and fetch the generated Public and Secret Key ➡

Integration Guide

With the above prerequisite steps already taken, we can now proceed with the integration steps below, which are:

Step 1: Update your Mono Connect Widget with your App’s Public Key.
Step 2: Get the temporary authorisation token in your onSuccess callback.
Step 3: Fetch the Customer's Account ID and save it to your database.
Step 4: Confirm the Data status of the Connected Account.
Step 5: Get the Financial Data of your user via their Account ID.

Step 1. Update your Mono Connect Widget with your App’s Public Key

With your App’s public key fetched from your dashboard, please endeavour to update the key parameter in your config object as seen below. It is this public key that binds/associate your Mono App to the widget on the frontend.

<script type="application/javascript">
  var connect;
  var config = {
    key: "YOUR_APPS_PUBLIC_KEY_HERE"
  };
  connect = new Connect(config);
  connect.setup();
</script>

Step 2. Get the temporary authorisation token in your onSuccess callback

In this step, please note that once your user has signed into the widget successfully through their desired bank, the onSuccess callback gets fired in which we send a temporary authorisation token. Please note that this token expires after 10 minutes.

<script type="application/javascript">
  var connect;
  var config = {
    key: "YOUR_APPS_PUBLIC_KEY_HERE", 
    onSuccess: function (response) {
      var authorisationToken = response.code; // The returned token when bank login is successful.
      copyToClipboard(authorisationToken);
      console.log(authorisationToken);
    },
    onClose: function () {
      console.log('user closed the widget.')
    }
  };
  connect = new Connect(config);
  connect.setup();
</script>

Step 3. Fetch the Customer's Account ID and save it to your database

With our authorisation token now in hand, the next step to take will be to call the Exchange Token API to now get an Account ID for this user. Please note that this Account ID is a permanent identifier to this user’s connected bank account. On this note, this Account ID doesn’t have an expiry time as the time to live is indefinite. With this information at hand, you can now proceed to save this Account ID into your database which of course will be associated with this User.

<script type="application/javascript">
  var connect;
  var config = {
    key: "YOUR_APPS_PUBLIC_KEY_HERE", 
    onSuccess: function (response) {
      var authorisationToken = response.code;
      copyToClipboard(authorisationToken);
      console.log(authorisationToken));
      alert(authorisationToken);
      /**
       response : { "code": "code_xyz" }
       you can send this code back to your server to get this
       authenticated account and start making requests.
       */
    },
    onClose: function () {
      console.log('user closed the widget.')
    }
  };
  connect = new Connect(config);
  connect.setup();
</script>

API Reference ➡

curl --request POST \
     --url https://api.withmono.com/account/auth \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: test_sk_adasdsadasddasd' \
     --data '
{
     "code": "code_hgvh46dejqtjvkjk"
}
'

{
  "id": "5f171a530295e231abca1153"
}

📘

NOTE: On Expiry Period

1. The Authorisation token expires after 10 minutes.
2. The Account ID doesn't expire except if unlinked.

❗️

NOTE

If you are integrating on the Web, please endeavour not to make this API request to Mono directly on your front end as you will be at risk of exposing your App Secret Key.

Instead, make an API request to your backend with your payload and from there, you can now make an API call to Mono with your request.

Step 4. Confirm the Data status of the Connected Account

At this stage, it is important to verify the data availability of your connected account to be available via the data_status field, before going ahead to call the desired financial API endpoints for data. Other possible values that can be received in the data status are AVAILABLE, PROCESSING or FAILED.

📘

NOTE

Please note that if you proceed to call our Financial APIs (e.g Transactions, Statements etc) without confirming your data status as AVAILABLE, you will receive an empty payload in your API response.

There are two approaches to getting the data status of a connected account. This can be done,

• Via the Account Updated Webhook
• Via the Account Details API

Via the Account Updated Webhook

Depending on the speed and uptime of the linked bank, it can take roughly 0.1 seconds to a couple of minutes to receive this webhook event. Once received, the data status is provided in the meta-object of your JSON response.

Via the Account Details API

With the Account ID in hand, you can manually query an account's data status by calling our Account Details API. Upon successful response, the data status gets returned in the meta-object as well, with other bank information relating to the user's bank account.

Step 5. Get the Financial Data of your user via their Account ID

With steps 1 to 4 out of the way, we can now get the financial data of your user's connected account. In this case, for instance, you can get a user's financial transactions by calling our Transactions API.

API Reference ➡

curl --request GET \
     --url https://api.withmono.com/accounts/5feec8ce95e8dc6a52e53257/transactions \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: test_sk_adasdsadasddasd'

{
  "paging": {
    "total": 190,
    "page": 2,
    "previous": "https://api.withmono.com/accounts/:id/transactions?page=2",
    "next": "https://api.withmono.com/accounts/:id/transactions?page=3",
  },
  "data": [
    {
      "_id": "62a05bc04112ea670bd09812",
      "type": "debit",
      "amount": 147085,
      "narration": "VC POS Loc-215016609012--BOLA NURAT YUSUFF OY NG",
      "date": "2022-05-30T16:03:00.000Z",
      "balance": 1021841,
      "currency": "NGN",
      "category": "online_transactions"
    },
    {
      "_id": "62a05bc04112ea670bd13465",
      "type": "credit",
      "amount": 300009,
      "narration": "NIP/FCMB/DANIEL AFOLABI/App food o To Zenith Bank FUNKE OJO",
      "date": "2022-05-30T15:44:00.000Z",
      "balance": 1168926,
      "currency": "NGN",
      "category": "transfer"
    }
  ]
}

🚧

NOTE : On Webhooks

a. After a successful login to a financial institution, these webhook events (mono.events.account_connected and mono.events.account_updated ) is sent with an Account ID present in the payload. With this, you can send an acknowledgment email to the user that the account has been linked successfully.

b. The webhook event (mono.events.account_updated) payload contains important information such as the data status, the current account balance, customer's name, customer's bank, account number, account type, the currency, the last 4 digits of the BVN, etc.

Resources

a. Mono Connect SDKs ➡
b. Mono Connect Libraries ➡
c. Mono Connect Callbacks ➡
d. Mono Callback Events Tracking ➡
e. Mono Connect APIs ➡