Partners API (Connect)

Overview

To integrate the Partners' API for Mono connect into your current software solution, you will need to:

1. Fetch available Financial Institutions

The first step in implementing the Mono Connect White Label API is to get the list of all the supported financial institutions. Here’s how to do this.

Make a Get request to this endpoint

https://api.withmono.com/v1/institutions

Response

[
    {
        "_id": "5f2d08be60b92e2888287702",
        "name": "GTBank",
        "type": "PERSONAL_BANKING",
        "auth_methods": [
            {
                "type": "internet_banking",
                "name": "Internet Banking",
                "ui": {
                    "title": "Log in to GTBank",
                    "form": [
                        {
                            "type": "elements.input",
                            "name": "username",
                            "hint": "UserID or Account Number",
                            "contentType": "string"
                        },
                        {
                            "type": "elements.input",
                            "name": "password",
                            "hint": "Password",
                            "contentType": "password"
                        }
                    ]
                },
                "_id": "60d071acf73e6468062ae8de"
            }
        ],
        "icon": "https://mono-public-bucket.s3.eu-west-2.amazonaws.com/images/gtbank-icon.png",
        "identifier": "mono.connections.gtbank",
        "primaryColor": "#E24407",
        "country": "ng",
        "ui": {
            "title": "Log in to GTBank",
            "form": [
                {
                    "type": "elements.input",
                    "name": "username",
                    "hint": "UserID or Account Number",
                    "contentType": "string"
                },
                {
                    "type": "elements.input",
                    "name": "password",
                    "hint": "Password",
                    "contentType": "password"
                }
            ]
        }
    },

From the response above, _id refers to the institution ID, while ****the auth_methods array contains the different authentication method types and the UI object available for a financial institution. These two parameters, alongside the app ID which you can find on the Apps page on your Mono dashboard, will be used in the next step to create a Mono-Connect session.

2. Create a mono-connect session

The next step is to create a Mono-Connect session by making a POST request to the endpoint below with the institution ID, auth_method, and app ID.

https://api.withmono.com/v1/connect/session

Ensure that you pass the mono-sec-key (secret key) in the headers for a successful request to be made. Here is a guide on how to generate your secret key on the Mono dashboard.

Body Parameters

{
        "app": "61e96db488900076f46fka2",
    "institution": "5f2d08be60b92e2888287702",
    "auth_method": "internet_banking"
}

Response

{
    "id": "session_qfa6PH7bBH",
    "app": "61fd1e96db488bb09f46f1a2",
    "institution": "5f2d08be60b92e2888287702",
    "auth_method": "internet_banking",
    "expiresAt": 1648193002017,
    "ui": {
        "title": "Log in to GTBank",
        "form": [
            {
                "type": "elements.input",
                "name": "username",
                "hint": "UserID or Account Number",
                "contentType": "string"
            },
            {
                "type": "elements.input",
                "name": "password",
                "hint": "Password",
                "contentType": "password"
            }
        ]
    }
}

3. Login user to Financial institution

To log in, you need to get the x-session-id returned from the response above in step two and pass it in the headers along with the mono-sec-key. Afterward, make a POST request to the login endpoint with the user’s credentials.

Endpoint

https://api.withmono.com/v1/connect/login

Body Parameters

{
    "username": "user_good",
    "password": "123456" 
}

Response

// Successfully logged in.

{
  "status": 200,
    "responseCode": 99,
    "data": {
      "code": "code_euTJM7yOuohSpSFVoBtc"
    }
}

// Requires user input to select the account. [200]

{
  "status": 200,
  "responseCode": 101,
    "data": [
        {
            "accountNumber": "0001557338",
            "name": "NAME ON ACCOUNT",
            "type": "CURRENT_ACCOUNT",
            "currency": "NGN",
            "status": "active",
            "balance": 14457
        },
        ...accounts
  ]
}

// Requires an answer to a Security question
{
    "status": 200,
    "responseCode": 102,
    "data": {
      "title": "Kindly Answer Your Security Question",
      "form": [
      {
        "type": "elements.input",
        "name": "answer",
        "hint": "Which city were you born in ?",
        "contentType": "string"
      }
      ]
    }
}

4. Understand next steps for the returned response

It is important to note that an institution might need multiple levels of authorization flow before granting user access. For this reason, the next steps for the authorization flow are determined by the responseCode received from the login response above in step three.

If the status returned is 200, you will obtain a response code of either 99, 101, or 102.

'99' indicates that the user has successfully signed in. You will be given a temporary authorization code, which you can use to access your Account ID through our Exchange token endpoint.

'101' indicates that your user has several accounts. The user would be required to pick the desired account to be enrolled. An array containing all of the discovered accounts will be returned in the response.

'102' indicates that an input is required from the user to proceed, this may be a security question, OTP, token, etc.

5. Re-commit session again if required

This is the final step in the authorization flow if a user’s input is required during the process (e.g account selection, OTP, security answer).

Also, before you make a POST request to the endpoint, ensure you pass the x-session-id and mono-sec-key in the headers.

Endpoint

https://api.withmono.com/v1/connect/commit

Body Parameters

{

 "account": ""  //index of selected account
 "answer": "" 
 "otp":""
}

The body parameter could be either one of the following (account, answer, OTP) depending on the response code received after a successful login attempt.

Response

{
  "status": 200,
  "responseCode": 99,
  "data": {
    "code": "code_q1i8VHYoAnZo5OZEBkmK"
  }
}

Errors

In case a session does not need to be committed and a commit request is made. the server will respond with 400 Bad Request response.

{
    "status": 400,
    "message": "Invalid operation or the operation isn't allowed yet."
}

Once the code has been retrieved in the authorization flow, proceed to the Exchange token endpoint to request an Account ID that will be used in making requests to Mono financial data endpoints.

You can also watch this short tutorial video to see how to implement the Mono Connect White Label API via Postman.

Note: This API is available to select partners only. To request access to the Mono Connect White Label API, log into the Mono dashboard and navigate to Add-Ons.