Integration Guide

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

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: Exchange the Customer's authorisation token for an Account ID.
Step 4: Initiate the first API call via the User’s 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. Exchange the Customer's Account ID via temporary authorisation token.

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

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. Initiate the first API call via the User’s Account ID.

With Steps 1 to 3 out of the way, we can now proceed to make our First API call

API Reference

curl --request GET \
     --url https://api.withmono.com/accounts/5feec8ce95e8dc6a52e53257 \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: test_sk_adasdsadasddasd'
{
    "meta": {
        "data_status": "AVAILABLE", // Available, Processing, Failed
        "auth_method": "mobile_banking" // mobile_banking, internet_banking
    },
    "account": {
        "_id": "5feec8ce95e8dc6a52e53257",
        "institution": {
            "name": "GTBank",
            "bankCode": "058",
            "type": "PERSONAL_BANKING" // or BUSINESS_BANKING
        },
        "name": "HASSAN ABDULHAMID TOMIWA",
        "accountNumber": "0131863463",
        "type": "SAVINGS ACCOUNT",
        "balance": 538786,
        "currency": "NGN",
        "bvn": "1595"
    }
}

📘

Note 1: On Expiry Period

A. The Authorisation Token: 10 minutes.
B. The Account ID: Indefinite.

🚧

Note 2: On Webhooks

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

b. After the authorisation token has been exchanged for the connected Account ID, a webhook event (mono.events.account_updated) gets sent. The payload contains important information such as the current account balance, customer's name, customer's bank, account number, account type, the currency, the last 4 digits of the BVN, etc.

This could take between 0.1 seconds to 1 minute depending on the speed and uptime with the linked bank before this event gets sent.

❗️

Note 3: On data status

It is important to wait for the account_updated event above to come in and confirm that the data_status in the payload is set to AVAILABLE, before calling our Statement, Transactions, Identity and Income Endpoints. Failure to wait will result in empty data returned on all endpoints.

Alternatively, the Information endpoint can be queried with the Account ID, to also confirm that the data_status in the payload is set to AVAILABLE.**


Resources

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


What’s Next
Did this page help you?