Upload Statement (Extraction)

Upload consumer, till and paybill mpesa statement for analysis and credit scoring

Upload Statement Mpesa Statments

POST {{BASE_URL}}/api/v1/statement/mfi/mpesa/upload

This endpoint allows you to upload Mpesa Statements for extraction, analysis and scoring

Headers

Name	Type	Description
Authentication*	string	Authentication token to track down API usage.

Request Body

Name	Type	Description
national_id*	String	User's national ID
file*	String	Base64 encoded file string
file_name*	String	Unchanged Mpesa Statement Name
callback_url*	String	Where to send result
statement_type*	String	Statement being uploaded only one of three user_statement, paybill_statement, till_statement
kyc_data*	Object	User KYC data
gender*	String	Customer gender (Male or Female)
name*	String	Customer name
location*	String	customer location
dob*	String	Customer date of birth (1999-06-28)

200 Statement saved successfully

{
   "status": 202,
   "message": "Statement saved successfully. Extraction process initiated",
   "data":{
      "reference_id": "22050643-73b9-4eec-ac73-4572d643ac1c",
      "name": "ANTHONY KAMAU",
      "phone_number": "254700123456"
      "statement_type": "user_statement",
       "short_code": null,
       "statement_period": "17 Oct 2022 - 17 Jan 2023"
   }
}

400 In case of error

{
   "status":400,
   "message":"Fraud flags detected",
   "errors":[
      {
         "message":"Author is not available"
      },
      {
         "message":"Creation Date is not available"
      },
      {
         "message":"Creator is not available"
      },
      {
         "message":"Title is not available"
      },
      {
         "message":"Subject is not available"
      },
      {
         "message":"Invalid producer: www.ilovepdf.com"
      }
   ]
}

Statement upload request Example

{
  "national_id": "546444747",
  "file_name": "MPESA_Statement_2022-12-07_to_2023-03-07_254707888888_54646.pdf",
  "callback_url": "https://webhook.site/45349498-57fc-4ab1-bcdb-0b0b1a657932",
  "statement_type": "user_statement",
  "file":"base 64 file string",
    "kyc_data": {
    "name": "ANTHONY KAMAU",
    "gender": "Male",
    "location": "Nairobi",
    "dob": "1987-08-06"
    }
}

Statement Callback Response Example

{
  "reference_id": "2a9a22f2-a593-4b32-ab67-9dd84adfa077",
  "status": 200,
  "message": "Statement analytics callback successfully fetched",
  "phone_number": "254712039804",
  "name": "ANTHONY MATHENGE",
  "statement_data": {
    "id": 0,
    "national_id": "390132",
    "created_at": null,
    "jsonurl": "_ANTHONY_MATHENGE1_01Jan2023_to_08Jun2023_943537.json",
    "ref_id": "2a9a22f2-a593-4b32-ab67-9dd84adfa077",
    "output_data": {
      "id": null,
      "national_id": "390132",
      "first_transaction_date": "2023-02-01",
      "last_transaction_date": "2023-02-22",
      "statement_days": "22",
      "total_received_amount": "57128.729999999996",
      "total_spent_amount": "49274.020000000004",
      "no_of_credit_transactions": "16",
      "no_of_debit_transactions": "143",
      "opening_balance": "284.4",
      "closing_balance": "8973.46",
      "average_balance": null,
      "limit": null,
      "total_borrowed_amount": null,
      "operational_cost": null,
      "unique_customers_served": null,
      "count_of_loans": "2",
      "total_loan_repayment_amount": "1122.22",
      "count_of_loan_repyments": null,
      "debt_income_ratio": "0.0",
      "debit_credit_ratio": "1.0",
      "average_monthly_received": "2597.0",
      "mpesa_type": null,
      "no_debit_credit_ratio": "8.94",
      "borrowing_vs_income_ratio": "0.0",
      "gender": "Male",
      "dob": "1970-10-12",
      "name": "Test",
      "location": "Nairobi",
      "age": "52",
      "inactive_days": "150",
      "max_sent": "13000.0",
      "mean_sent": "286.4768604651163",
      "max_received": "13000.0",
      "z_sent": "0.2007752118001289",
      "z_received": "0.19636785120493544",
      "z_balance": "0.5950363788591533",
      "n_received": "16",
      "n_sent": "143",
      "unemployment": "5.74",
      "inflation": "8",
      "fx": "140",
      "gas": "1.8",
      "food_inflation": "10",
      "Total": "0.8",
      "avg_balance": "1551.679069767442",
      "total_borrowed_mpesa": "251.73",
      "count_of_loan_repayments": "5",
      "repayment_rate": "Good",
      "bank_rate": "10.5",
      "mean_received": "332.1437790697674",
      "spending_rate": "Moderate",
      "spending_rate_ratio": "1.0",
      "repayment_rate_ratio": "2.5",
      "repayment_rate_ratio_n": "2.5",
      "total_savings": "0.0",
      "total_shopping": "1720.0",
      "total_gaming": "0.0",
      "total_eat_drink": "0.0",
      "total_betting": "0.0",
      "total_education": "0.0",
      "total_technology_electronics": "0.0",
      "total_groceries": "0.0",
      "total_airtime_internet_topups": "0.0",
      "total_mobile_loans": "0.0",
      "total_electricty": "0.0",
      "total_water": "0.0",
      "total_fuel": "0.0",
      "debt_ratio": "0.16",
      "mobiLoansScore": null,
      "score": "347.5840620944491",
      "score_cat": "Fair",
      "credit_history": null,
      "default_probability": "0.8193669589848304",
      "npa": null,
      "npa_closed": null,
      "borrowing_vs_income": "Good",
      "pezesha_mpesa_credit_score": "347.5840620944491",
      "pezesha_mpesa_crb_credit_score": null,
      "crb_mobile_loan_score": null,
      "pezesha_average_score": "347.5840620944491"
    }
  }
}