Upload Statement (Extraction)

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

Upload Mpesa Statments

POST {{BASE_URL}}/api/v1/statements/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	Customer'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
passcode*	String	The file's passcode

200 Statement saved successfully

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

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",
  "passcode": "12345"
}

Callback Response

{
   "data": {
       {
           "national_id": 1001,
           "phone_number": "M12345",
           “other_details”: { ... },
           
            "statement_details": [
                    {
                        "transaction_id": "PLV6XV3WK2",
                        "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                        "received_amount": 575.65,
                        "sent_amount": 0,
                        "balance_then": 236363.31,
                        "transaction_datetime": "2024-09-28T00:00:00"
                    },
                    {
                    "transaction_id": "PLV6XV3WK3",
                    "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                    "received_amount": 575.65,
                    "sent_amount": 0,
                    "balance_then": 1000.31,
                    "transaction_datetime": "2024-09-28T00:00:00"
                }
            ],
            
              "total_fuliza_betting_6m": 0,
              "total_fuliza_loan_repayment_6m": 0,
              "total_fuliza_airtime_6m": 0,
              "total_fuliza_bill_payment_6m": 0,
              "total_fuliza_merchant_payment_6m": 0,
              "total_fuliza_p2p_transfer_6m": 0,
              "total_fuliza_agent_withdrawal_6m": 0,
              "total_fuliza_debit_count_6m": 0,
              "total_fuliza_debit_sum_6m": 0,
              "total_mobile_loan_received_6m": 0,
              "total_mobile_loan_repaid_6m": 0,
              "total_mshwari_loan_repayment_6m": 0,
              "total_mshwari_loan_deposit_6m": 0,
              "total_mshwari_withdrawal_6m": 0,
              "total_mshwari_savings_deposit_6m": 0,
              "total_p2p_received_6m": 18100,
              "total_p2p_sent_6m": 696447,
              "mobile_loan_count_6m": 0,
            
           "score_output": {
               "reason_code_1": "Low number of transactions",
               "reason_code_2": "Low frequency of transactions",
               "reason_code_3": "Customer inactive for a long period",
               "reason_code_4": "Low transaction volumes",
               "probability": "45.56",
               "grade": "GG",
               "credit_score": "412"
           },           
          "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           },
           "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           }

        },
        
        "fraud_data": {
          "message": "successfully obtained IPRS data",
          "national_id": "550000055",
          "statement_name": [
            "JOHN",
            "ALPHA",
            "DOE"
          ],
          "customer_name": [
            "Peter",
            "Marangi"
          ],
          "similarity_score": 0,
          "verified_status": "no match"
        },
    }
}