Integration Guide

Overview

This guide will put you through the necessary steps on how you can set up and get telco data via our APIs.

Prerequisites

To get started, please ensure to:

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

Integration Guide

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

Step 1: Log in a user with their details
Step 2: Verify the OTP of the telco account
Step 3: Fetch telco Account ID
Step 4: Fetch telco account information, balances, transactions and identity data

Step 1: Log in a user with their details

Firstly, it is important to get authorisation from the user's telco phone number. This can be achieved by making an API call to our Telco authentication API by passing the user's phone number and the telco provider (e.g airtel or mtn) to the body request. Also, you would be passing your dashboard application secret key to your headers (mono-sec-key).

API Reference ➡

curl --request POST \
     --url https://api.withmono.com/v1/telecom/auth \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm' \
     --data '
{
     "phone": "07082109281",
     "provider": "airtel"
}
'

{
  "status": "successful",
  "data": {
    "session_id": "4YM7TXtvU1viUWFH",
    "result": {
      "title": "Please enter the OTP sent to your phone",
      "form": [
        {
          "type": "elements.input",
          "name": "otp",
          "hint": "Enter OTP",
          "contentType": "password",
          "minLength": 6,
          "maxLength": 6
        }
      ]
    }
  }
}

Step 2: Verify the OTP of the telco account

In this step, you are to pass the OTP provided by the user to the body request of the telco verification API so as to confirm authorisation to the user's phone number. In your headers, you would be passing the session id received in the API above to the verify API headers via x-session-id, as well as your dashboard application key to mono-sec-key.

API Reference ➡

curl --request POST \
     --url https://api.withmono.com/v1/telecom/verify \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm' \
     --header 'x-session-id: 4YM7TXtvU1viUWFH' \
     --data '{"otp":"123654"}'

{
  "status": "successful",
  "data": {
    "code": "code_AwEo6hTHJtUiKE99r1ca"
  }
}

Step 3: Fetch telco Account ID

At this stage, you are to go ahead to exchange the temporary token received in the step above, so as to get a permanent telco Account ID. In your headers, ensure to pass your dashboard application key to mono-sec-key.

📘
NOTE: On Expiry Period

The Authorisation token expires after 10 minutes.

The Account ID cannot expire except if unlinked.

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: live_sk_asdsadsads' \
     --data '
{
     "code": "code_1234567890"
}
'

{
  "id": "5f171a530295e231abca1153"
}

Step 4: Fetch telco account information, balances, transactions and identity

In this final step, you can now get telco account information, balances, as well as the past, recorded transactions on this telco account. In your headers, ensure to pass only the dashboard application key to mono-sec-key.

Telco Details
API Reference ➡

curl --request GET \
     --url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'

{
  "meta": {
    "data_status": "AVAILABLE",
    "auth_method": "mobile_banking"
  },
  "account": {
    "_id": "630484cdca8f9f1a91234567",
    "institution": {
      "name": "Mtn",
      "type": "PERSONAL_BANKING"
    },
    "name": "KING KUNTA",
    "accountNumber": "+2347012345678",
    "type": "telecom_account",
    "balance": 7659,
    "currency": "NGN",
    "bvn": null
  }
}

Balances Details
API Reference ➡

curl --request GET \
     --url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/balances \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'

[
    {
        "_id": "630df07fefa85f123c84ce84",
        "name": "Main Balance",
        "type": "currency",
        "value": 7659,
        "unit": "ngn"
    },
    {
        "_id": "630df07fefa85f123c84ce85",
        "name": "Roaming Bundle",
        "type": "voice",
        "value": 300,
        "unit": "minutes"
    },
    {
        "_id": "630df07fefa85f123c84ce86",
        "name": "GoodyBag Social Bundle",
        "type": "data",
        "value": 11.15,
        "unit": "gb"
    },
    {
        "_id": "630df07fefa85f123c84ce87",
        "name": "Airtime Bonus",
        "type": "currency",
        "value": 1550000,
        "unit": "ngn"
    },
    {
        "_id": "630df07fefa85f123c84ce88",
        "name": "Data Bundle",
        "type": "data",
        "value": 16.39,
        "unit": "gb"
    }
]

Telco Transactions
API Reference ➡

curl --request GET \
     --url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/transactions \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'

{
  "paging": {
    "total": 25,
    "page": 1,
    "previous": null,
    "next": "https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/transactions?page=2"
  },
  "data": [
    {
      "_id": "62f15769982abb0d25e1ff8b",
      "type": "debit",
      "amount": 500000,
      "narration": "20GB Monthly Plan",
      "balance": 7659,
      "date": "2022-07-26T16:20:37.000Z",
      "currency": "NGN"
    },
    {
      "_id": "62f15769982abb0d25e1ff8c",
      "type": "credit",
      "amount": 500000,
      "narration": "VTU",
      "balance": 507660,
      "date": "2022-07-26T16:16:17.000Z",
      "currency": "NGN"
    },
    {
      "_id": "62f15769982abb0d25e1ff8d",
      "type": "debit",
      "amount": 150000,
      "narration": "6GB Weekly Plan",
      "balance": 7659,
      "date": "2022-07-24T18:47:44.000Z",
      "currency": "NGN"
    }
  ]
}

Identity Details
API Reference ➡

curl --request GET \
     --url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/identity \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'

{
    "fullName": "KING  KUNTA",
    "phone": "+2347012345678",
    "gender": "M",
    "email": "[email protected]",
    "dob": "Thu December 01 1990 00:00:00 GMT+0000",
    "maritalStatus": "M",
    "addressLine1": "2A",
    "addressLine2": "Jameson Street"
}