Integration Guide

A comprehensive step-by-step process on how to retrieve telco data from your customers.

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: Get authorisation from the user
Step 2: Verify the OTP of the telco account
Step 3: Pull telco account balances
Step 4: Connect telco Account by getting the telco exchange token
Step 5: Fetch telco Account ID
Step 6: Get telco account information and transactions

Step 1: Get authorisation from the user

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",
    "message": "Successfully verified otp",
    "verified": true
}

Step 3: Pull telco account balances

Here, you can pull the customer's transaction balance data, which includes the main balance, aIrtime bundle, data bonuses etc. In your headers, ensure to pass the session id received in the verification API above via x-session-id, as well as your dashboard application key to mono-sec-key.

API Reference

curl --request GET \
     --url https://api.withmono.com/v1/telecom/accounts \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm' \
     --header 'x-session-id: 4YM7TXtvU1viUWFH'
{
    "status": "successful",
    "message": "successfully fetched accounts",
    "data": [
        {
            "name": "Main Balance",
            "accountNumber": "+2347049284921",
            "type": "CURRENCY",
            "balance": 7659,
            "currency": "NGN",
            "index": 0
        },
        {
            "name": "Roaming Bundle",
            "accountNumber": "+2347049284921",
            "type": "VOICE",
            "balance": 30000,
            "currency": "MINUTES",
            "index": 1
        },
        {
            "name": "GoodyBag Social Bundle",
            "accountNumber": "+2347049284921",
            "type": "DATA",
            "balance": 1191,
            "currency": "GB",
            "index": 2
        } 
    ]
}

Step 4: Connect telco account by getting telco exchange token

At this stage, you are to go ahead to connect the account by fetching the exchange token of the telco account. In your headers, ensure to pass the session id received in the verification API above 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/connect \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm' \
     --header 'x-session-id: 4YM7TXtvU1viUWFH' \
     --data '{"account":0}'
{
  "status": "successful",
  "data": {
    "code": "code_ILQoit2BTRHzNd1LQP5k"
  }
}

Step 5: Fetch telco Account ID

In this step, you are to exchange the temporary received token above for the permanent account ID. In your headers, ensure to pass only your dashboard application key to mono-sec-key.

📘

NOTE: On Expiry Period

  1. The Authorisation token expires after 10 minutes.
  2. 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_opwe2fwk23asdmfdfdsm' \
     --data '
{
     "code": "code_ILQoit2BTRHzNd1LQP5k"
}
'
{
  "id": "5f171a530295e231abca1153"
}

Step 6: Get telco account information and transactions

In this final step, you can now get telco account information 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 POST \
     --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": "62f15763982abb0d25e1fefd",
    "institution": {
      "name": "Mtn",
      "type": "PERSONAL_BANKING"
    },
    "name": "Main Balance",
    "accountNumber": "+2347041967579",
    "type": "CURRENCY",
    "balance": 7659,
    "currency": "NGN",
    "bvn": null
  }
}

Telco Transactions
API Reference

curl --request POST \
     --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"
    }
  ]
}

Did this page help you?