Connect Link Integration Guide
Last updated April 15th, 2024
Overview
This guide will put you through the necessary steps to take when trying to Integrate Mono Connect into your software solution via API. This is made possible via a generated URL that can be sent to users for them to complete the account linking process without a need for setting up SDKs.
Prerequisites
To get started, please ensure to:
- Sign up on the Mono Dashboard.
- Create an App and fetch the generated Secret Key.
Integration Steps
With the above prerequisite steps taken, please note that there are three stages for completing the integration process:
- Initiate Account Linking: At this stage, an account linking URL is generated which should be sent to your users to complete that account linking stage.
- Retrieve Account ID: The user's account id is retrieved via webhook and saved to your database.
- Data Status confirmation and Data Access: The user's financial data availability is confirmed, for financial data access.
Step 1: Initiate Account Linking
To initiate account linking, send a POST request to the following endpoint:
Request
POST https://api.withmono.com/v2/accounts/initiate
Request Body Parameter
customer(required): This object field expects the user's customer information i.e name and emailcustomer.name(required): Provide the user's namecustomer.email(required): Provide the user's emailscope(required): Specify the scope as "auth"meta(optional): The meta object expects a "ref" key.meta.ref: Specify a unique reference to enable you make ties to the account linked via generated URL.redirect_url(optional): This field requires a valid URL for successful account linking redirection.
Request Headers
Include the following header in your request for authentication:
mono-sec-key(required): Your Mono secret key.
cURL Sample Request
Request
curl --request POST \
--url https://api.withmono.com/v2/accounts/initiate \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: string' \
--data '{
"customer": {
"name": "Samuel Olamide",
"email": "samuel.nomo@mono.co"
},
"meta": { "ref": "99008877TEST"},
"scope": "auth",
"redirect_url": "https://mono.co"
}
'
cURL Sample Response
Request
{
"status": "successful",
"message": "Request was succesfully completed",
"timestamp": "2024-03-18T11:51:41.624Z",
"data": {
"mono_url": "https://link.mono.co/ALGSTO222222WE",
"customer": "65f82acd00000003aa9028d",
"meta": {
"ref": "99008877TEST"
},
"scope": "auth",
"redirect_url": "https://mono.co",
"created_at": "2024-03-18T11:51:41.605Z"
}
}
Step 2: Retrieve Account ID
After a successful account linking process in the previous step, a unique account ID will be sent via webhook in the the following response:
Request
{
"event": "mono.events.account_connected",
"data": {
"id": "65fab3959a3e1f6ad2123456"
}
}
The account id returned in the mono.events.account_connected webhook is a unique permanent identifier to the link financial account. 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.
Step 3: Data Status confirmation and Data Access
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:
Request
{
"event": "mono.events.account_updated",
"data": {
"meta": {
"data_status": "AVAILABLE",
"auth_method": "internet_banking"
},
"account": {
"_id": "5f171a530295e231abca1153",
"name": "Samuel Olamide",
"accountNumber": "0131883461",
"currency": "NGN",
"balance": 22644,
"type": "Tier 3 Savings Account",
"bvn": "9422",
"authMethod": "internet_banking",
"institution": {
"name": "ALAT by WEMA",
"bankCode": "035",
"type": "PERSONAL_BANKING"
},
"created_at": "2024-04-30T17:16:01.171Z",
"updated_at": "2024-04-30T17:16:05.463Z"
}
}
}
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 gets returned in the meta-object as well, with other bank information relating to the user's bank account.
Request
curl --request GET \\
--url https://api.withmono.com/v2/accounts/65203b27f6323a96a4a83779 \\
--header 'Accept: application/json' \\
--header 'mono-sec-key: test_sk_adasdsadasddasd'
Request
{
"status": "successful",
"message": "Request was succesfully completed",
"timestamp": "2024-04-12T06:31:02.289Z",
"data": {
"account": {
"id": "64779d900000000000b3de23aeb8",
"name": "Samuel Olamide Nomo",
"currency": "NGN",
"type": "Digital Savings Account",
"account_number": "1234567890",
"balance": 333064,
"bvn": "0065",
"institution": {
"name": "GTBank",
"bank_code": "058",
"type": "PERSONAL_BANKING"
}
},
"meta": {
"data_status": "AVAILABLE",
"auth_method": "internet_banking"
}
}
}
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.
Request
curl --request GET \\
--url https://api.withmono.com/v2/accounts/65203b27f6323a96a4a83779/transactions \\
--header 'Accept: application/json' \\
--header 'mono-sec-key: test_sk_adasdsadasddasd'
Request
{
"status": "successful",
"message": "Transaction retrieved successfully",
"timestamp": "2024-04-12T06:18:17.117Z",
"data": [
{
"id": "66141bbff58d2687e7d91234",
"narration": "PG00001",
"amount": 500,
"type": "debit",
"balance": 1500,
"date": "2023-12-14T00:02:00.500Z",
"category": "unknown"
},
{
"id": "66141bbff58d2687e7d91235",
"narration": "0000132312091322123456789012345 NIP TRANSFER",
"amount": 1000,
"type": "debit",
"balance": 2000,
"date": "2023-12-09T13:23:00.100Z",
"category": "bank_charges"
},
],
"meta": {
"total": 307,
"page": 1,
"previous": null,
"next": "https://api.withmono.com/v2/66141b98aaa34e17e8cfdb76/transactions?page=2"
}
}
Account Institution Redirection
When initiating an Account linking URL through Mono Connect and you have prior knowledge of the user's bank details, you can include an institution object in the Connect Link Initiation API request. This object includes:
id: This field expects the user's institution ID, obtainable from our bank listing endpoint here.auth_method: Here, specify the authentication method of the institution, such as mobile_banking or internet_banking.
Upon calling the Account Initiation API with the institution object included in the payload, a URL is generated. Users can use this URL to complete the account linkinp process. Opening the URL displays the login page for the preconfigured institution.
API request
Request
curl --request POST \
--url https://api.withmono.com/v2/accounts/initiate \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: string' \
--data '{
"customer": {
"name": "Samuel Olamide",
"email": "samuel.nomo@mono.co"
},
"meta": { "ref": "99008877TEST"},
"institution": {
"id": "5f2d08bf60b92e2888287704",
"auth_method": "internet_banking"
},
"scope": "auth",
"redirect_url": "https://mono.co"
}
'