Integration Guide
Last updated July 17th, 2024
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).
Request
curl --request POST \
--url https://api.withmono.com/v2/telecom/auth \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm' \
--data '
{
"phone": "07082109281",
"provider": "airtel"
}
'
Request
{
"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.
Request
curl --request POST \
--url https://api.withmono.com/v2/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"}'
Request
{
"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.
On Expiry Period
- The Authorisation token expires after 10 minutes.
- The Account ID cannot expire excep if unlinked.
Request
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"
}
Request
{
"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.
Request
curl --request GET \
--url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd \
--header 'Accept: application/json' \
--header 'mono-sec-key: live_sk_opweasdmfdfdsm'
Request
{
"meta": {
"data_status": "AVAILABLE",
"auth_method": "mobile_banking"
},
"account": {
"_id": "630484cdca8f9f1a91234567",
"institution": {
"name": "Mtn",
"type": "PERSONAL_BANKING"
},
"name": "SAMUEL OLAMIDE",
"accountNumber": "+2347012345678",
"type": "telecom_account",
"balance": 7659,
"currency": "NGN",
"bvn": null
}
}
Balances Details
Request
curl --request GET \
--url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/balances \
--header 'Accept: application/json' \
--header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'
Request
[
{
"_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
Request
curl --request GET \
--url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/transactions \
--header 'Accept: application/json' \
--header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'
Request
{
"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
Request
curl --request GET \
--url https://api.withmono.com/accounts/62f15763982abb0d25e1fefd/identity \
--header 'Accept: application/json' \
--header 'mono-sec-key: live_sk_opwe2fwk23asdmfdfdsm'
Request
{
"fullName": "SAMUEL OLAMIDE NOMO",
"phone": "+2347033445599",
"gender": "male",
"bvn": null,
"dob": "1997-08-07T00:00:00.000Z",
"created_at": "2024-07-17T11:16:49.632Z",
"updated_at": "2024-07-17T11:16:49.632Z"
}