Overview

Welcome to the Mida developers documentation portal. This is a complete guide to intergrating with the Mida collection platform. To start you need to get your organisation API key here

Intergrations

Create loan

To use Mida collections, you start buy creating a loan record.

Feild description
# Field Description Type
1 loanAccountNumber Unique loan account identifer from lenders system string
2 loanAmount Total value of the loan in minor string
3 email lender's client's email string
3 isNewLoan true if loan is a new loan boolean
3 customer lenders client's details object
3 address lenders client's address details object
3 nok (optional) lenders client's next of kin details object
3 schedule loan schedule array
Customer Object
# Field Description Type
1 fullname lender's client's fullname string
2 BVN lender's client's BVN string
3 Sex lender's client's Sex string
4 phoneNumber lender's client's Phone Number string
Address Object
# Field Description Type
1 address lender's client's full address string
2 state lender's client's state of residence string
3 lga lender's client's lga of residence string
NOK Object
# Field Description Type
1 nokFullname client's next of kin's fullname string
2 nokBVN (optional) client's next of kin's BVN string
3 nokPhoneNumber client's next of kin's Phone Number string
3 nokAddress client's next of kin's full address string
3 nokState client's next of kin's state of residence string
3 nokLga client's next of kin's lga of residence string
Account Object
# Field Description Type
1 bankName Name of bank string
2 accountNumber clients account number string
3 accountName Name associated with the account numner string
Security

The API security is a bearer token using your organisation API Key gotten here

Sample Request:

{
 "loanAccountNumber":"423456789",
 "loanAmount": "50000",
 "email": "daveomo@gmail.com",
"isNewLoan": false,
 "customer":{
    "fullname": "Dave Omo",
    "BVN": "2323232322",
    "sex": "male",
    "phoneNumber": "08055309113,08055623778"
 },
 "address": {
    "address" : "2a stong iron steet surulere",
    "state" : "lagos",
    "lga" : "lagos mainland"
 },
 "nok": {
    "nokFullname" : "Jane Omo",
    "nokBVN" : "2390857192",
    "nokPhoneNumber" : "0987768899",
    "nokAddress" : "15 maryland avenue, off thomson street.",
    "nokState" : "lagos",
    "nokLga" : "ikeja"
 },
 "account": {
    "bankName" : "Providus MFB",
    "accountNumber" : "2390857192",
    "accountName" : "John Doe",
 },
 "schedule":[
   {
      "dueDate": "2023-08-01",
      "amount": "15000",
      "status": "pending"
   },{
      "dueDate": "2023-09-01",
      "amount": "15000",
      "status": "pending"
   },{
      "dueDate": "2023-10-01",
      "amount": "15000",
      "status": "pending"
   },{
      "dueDate": "2023-11-01",
      "amount": "15000",
      "status": "pending"
   }
  ]
}

Repayment instrument call-back

To get notified on successful payment instrument collection, expose an endpoints collect the following variables via call back:

Feild description
# Field Description Type
1 status status where 00 = success and other numbers represent a type of failure string
2 message message describing status string
3 email lenders client's email string
4 loanAccountNumber Unique loan account identifer from lenders system string
5 instrumentStatus status of each repayment instrument type array
Repayment instrument call-back :

{
 "status":"00",
 "message": "card instrument successful",
 "email": "daveomo@gmail.com",
 "loanAccountNumber": "123456789",
 "instrumentStatus":{
    "card": "successful",
    "dd": "successful"
 }
}

Collection status call-back

To get notified on successful collections, expose an endpoint to collect the following variables via call back:

Feild description
# Field Description Type
1 status status where 00 = success and other numbers represent a type of failure string
2 message message describing status string
4 loanAccountNumber Unique loan account identifer from lenders system string
4 amountCollected Value successfully collected in minor string
Collections status call-back :

{
 "status":"00",
 "message": "card instrument successful",
 "loanAccountNumber": "123456789",
 "collectedAmount": "5000000"
}

Sample Codes

JavaScript Code Example

<script> 
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer test");

var raw = JSON.stringify({
  "loanAccountNumber": "423456789",
  "loanAmount": "50000",
  "email": "daveomo@gmail.com",
  "isNewLoan": false,
  "customer": {
    "fullname": "Dave Omo",
    "BVN": "2323232322",
    "phoneNumber": "08055309113,08055623778"
  },
  "address": {
    "address": "2a stong iron steet surulere",
    "state": "lagos",
    "lga": "lagos mainland"
  },
  "nok": {
    "nokFullname": "Jane Omo",
    "nokBVN": "2390857192",
    "nokPhoneNumber": "0987768899",
    "nokAddress": "15 maryland avenue, off thomson street.",
    "nokState": "lagos",
    "nokLga": "ikeja"
  },
  "schedule": [
    {
      "dueDate": "2023-08-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-09-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-10-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-11-01",
      "amount": "15000",
      "status": "pending"
    }
  ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://fetch-api-staging.up.railway.app/external/loan", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
</script>
Python Code Example

import http.client
import json

conn = http.client.HTTPSConnection("fetch-api-staging.up.railway.app")
payload = json.dumps({
  "loanAccountNumber": "423456789",
  "loanAmount": "50000",
  "email": "daveomo@gmail.com",
  "isNewLoan": false,
  "customer": {
    "fullname": "Dave Omo",
    "BVN": "2323232322",
    "phoneNumber": "08055309113,08055623778"
  },
  "address": {
    "address": "2a stong iron steet surulere",
    "state": "lagos",
    "lga": "lagos mainland"
  },
  "nok": {
    "nokFullname": "Jane Omo",
    "nokBVN": "2390857192",
    "nokPhoneNumber": "0987768899",
    "nokAddress": "15 maryland avenue, off thomson street.",
    "nokState": "lagos",
    "nokLga": "ikeja"
  },
  "schedule": [
    {
      "dueDate": "2023-08-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-09-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-10-01",
      "amount": "15000",
      "status": "pending"
    },
    {
      "dueDate": "2023-11-01",
      "amount": "15000",
      "status": "pending"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer test'
}
conn.request("POST", "/external/loan", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
PHP Code Example
<?php 
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://fetch-api-staging.up.railway.app/external/loan',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "loanAccountNumber":"423456789",
    "loanAmount": "50000",
    "email": "daveomo@gmail.com",
    "customer":{
        "fullname": "Dave Omo",
        "BVN": "2323232322",
        "phoneNumber": "08055309113,08055623778"
    }, 
    "address": {
        "address" : "2a stong iron steet surulere",
        "state" : "lagos",
        "lga" : "lagos mainland"
    },
    "nok": {
        "nokFullname" : "Jane Omo",
        "nokBVN" : "2390857192",
        "nokPhoneNumber" : "0987768899",
        "nokAddress" : "15 maryland avenue, off thomson street.",
        "nokState" : "lagos",
        "nokLga" : "ikeja"
    },
    "schedule":[
        {
            "dueDate": "2023-08-01",
            "amount": "15000",
            "status": "pending"
        },{
            "dueDate": "2023-09-01",
            "amount": "15000",
            "status": "pending"
        },{
            "dueDate": "2023-10-01",
            "amount": "15000",
            "status": "pending"
        },{
            "dueDate": "2023-11-01",
            "amount": "15000",
            "status": "pending"
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer test'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>