GuidesAPI ReferenceHelp CenterStatus PageBlogGet API Keys

Integration Guide

A comprehensive step by step process on how to integrate Mono Connect.

Suggest Edits

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, please note that there are two stages for completing the integration process:

  1. SDK Implementation (Front-end) Stage
    In this stage, you will be implementing a Mono SDK which allows your user or customer to log in to their selected or desired financial institution using the Mono widget on your mobile platform.
  2. API Implementation (Back-end) Stage
    This is where you can start calling Mono's API for the user's bank account details, transactions, identity etc after a successful account authentication process.

We will be breaking down both stages in further detail below. For the sake of this guide, we will be integrating with our Inline Connect SDK.

A. SDK Implementation (Front-end) Stage

This stage aims to ensure that you have set up your desired Mono SDK in your mobile or web platform, so your users can successfully link their accounts on your platform. This can be achieved in three simple steps shared below:

Step 1: Mono Connect Widget setup

Depending on the Mono SDK that you want to implement from our SDK directory here, be sure to go through the GitHub read-me doc for the installation and set up on your web or mobile platform as applied. Once done, update the key parameter to have your Mono application public key which you can retrieve from your dashboard.

It is this public key that identifies your mono dashboard app, to the front-end widget.

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

Step 2: Handle the temporary authorization (auth) token

In this step, please note that once your user has signed into the widget successfully through their desired bank, the onSuccess parameter gets fired which we send a temporary authorization token.

N.B: Please note that this temporary authorization token expires after 10 minutes.

Once this temporary auth token has been received, it is required to forward this token to your back-end server to tokenise the account and get a permanent Account ID which is explained in the next integration stage. 

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

📘

NOTE

If you are working with JavaScript, you can easily send this temporary auth token to your backend with the fetch or axios npm package, depending on your preference.

B. API Implementation (Back-end) Stage

At this point, the objective is to receive the temporary token from the front end, get your permanent Account ID and fetch the financial data APIs. All of these are explained in the steps below:

Step 1: Fetch the Customer's Account ID

With our authorization token received from your front end, the next step to take here will be to call our Exchange Token API to fetch an Account ID for this user.

Please note that this Account ID is a permanent identifier to this user’s connected bank account. Also note that this Account ID doesn’t have an expiry time as the time to live is indefinite.

With this information at hand, it is important to save this Account ID into your database (which of course will be associated with this user linking) so that you can make future API calls as desired.

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"
}

N.B: Kindly also note that once an account has been linked successfully on the Mono connect widget, an account connected (mono.events.account_connected) event is fired to your webhook URL, which you have setup on your dashboard, which informs you in real-time the account that has been linked.

You can visit here for more details about this webhook.

{
  event: "mono.events.account_connected",
  data: {
    "id": "5f171a530295e231abca1153"
  }
}

📘

NOTE 1:

Regarding the expiry period

  • The Authorization token expires after 10 minutes.
  • The Account ID doesn't expire except if unlinked via API.

📘

NOTE 2:

If you are integrating on the Web, please endeavor 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 back-end with your payload and from there, you can now make an API call to Mono with your request.

Step 2: 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 ready via the data_status field by ensuring that this is AVAILABLE, before going ahead to call the desired financial API endpoints for data.

All the possible values of a 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 on the webhook URL that you have set up on your dashboard. Once received, the data status is provided in the meta-object of your JSON response.

Account updated webhook payload:

{
  "event": "mono.events.account_updated",
  "data": {
    "meta": {
      "data_status": "AVAILABLE",
      "auth_method": "mobile_banking" //or internet_banking
    },
    "account": {
      "_id": "5f171a530295e231abca1153",
      "name": "Samuel Olamide",
      "currency": "NGN",
      "type": "SAVINGS_ACCOUNT", // or BUSINESS_BANKING 
      "accountNumber": "0131883461",
      "balance": 100000,
      "institution": {
						"name": "GTBank",
            "bankCode": "058",
            "type": "PERSONAL_BANKING" 
			},
      "liveMode": false,
      "created_at": "2023-08-29T16:00:45.516Z",
      "updated_at": "2023-08-29T16:00:45.516Z",
      "__v": 0,
      "bvn": '9422'
    }
  }
}

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 field gets returned in the data_status field as well, with other bank information relating to the user's bank account.

API Reference ➡

curl --request GET \\
     --url <https://api.withmono.com/v1/accounts/65203b27f6323a96a4a83779> \\
     --header 'Accept: application/json' \\
     --header 'mono-sec-key: test_sk_adasdsadasddasd'

{
  "status": "successful",
  "message": "Successfully fetched account",
  "data": {
    "id": "65203b27f6323a96a4a83779",
    "name": "Samuel Olamide",
    "type": "SAVINGS_ACCOUNT",
    "account_number": "1234567890",
    "balance": 206119,
    "currency": "ngn",
    "data_status": "available",
    "institution": {
      "name": "Zenith Bank",
      "type": "personal_banking",
      "bank_code": "057",
      "auth_method": "mobile_banking"
    },
    "created_at": "2023-10-06T16:51:51.818Z",
    "updated_at": "2023-10-09T01:41:21.558Z"
  }
}

📘

NOTE ON WEBHOOKS;

In the integration flow seen above, please note that only the two webhooks below are sent to your dashboard URL. If you don’t have this configured, you can follow our guide here.

a. Account connected webhook event (mono.events.account_connected): The payload of this request contains the account id of the user. With this trigger, you can send an acknowledgement email to the user that the account has been linked successfully. Please visit here for more details here.

b. Account updated webhook event (mono.events.account_updated):
The payload in this request contains the data status of the connected account which informs when financial data is available or not. Please visit here for more details here.

Step 3: Access the Financial Data of your user

With the above steps out of the way, we can now get the financial data of your user's connected account as data will be readily available.

For instance, you can fetch a user's financial transactions by calling our Transactions API via their Account ID.

API Reference ➡

curl --request GET \\
     --url <https://api.withmono.com/v1/accounts/65203b27f6323a96a4a83779/transactions> \\
     --header 'Accept: application/json' \\
     --header 'mono-sec-key: test_sk_adasdsadasddasd'


{
  "status": "successful",
  "message": "Successfully fetched transactions",
  "data": {
    "paging": {
      "page": 1,
      "total": 35,
      "previous": null,
      "next": "https://api.withmono.com/accounts/65203b27f6323a96a4a83779/transactions?page=2"
    },
    "transactions": [
      {
        "id": "652052349d3a9e0484891f28",
        "type": "credit",
        "amount": 9000,
        "narration": "NIP/KUDA/SAMUEL OLAMIDE/TRANSFER 1",
        "date": "2023-10-06T18:08:50.000Z",
        "balance": 0,
        "currency": "NGN"
      }
    ]
  }
}

Resources

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

Updated 2 days ago

What’s Next