mono-logo

Transaction Categorisation Guide

Last updated Jun 7th, 2024

Overview

The Transaction Categorisation API simplifies the process of organizing user transactions into predefined categories, thereby improving the ability to analyze and understand spending habits. This service allows you to categorize transactions linked to an already connected bank account that are marked as null. Additionally, you can upload your own transactions for categorization.

Integration Endpoints

Kindly note that there are three endpoints under under the transaction categorisation API, these are:

  1. Initiate Transactions Categorising: Starts the process of categorizing existing transactions in a connected bank account that are currently marked as null.
  2. Categorisation Upload Batch: Allows you to upload a batch of transactions that you want to be categorized.
  3. Retrieve Categorised Transactions: Fetches the list of transactions that have been categorized from the uploaded transaction batch.
1

Initiate Transactions Categorising

This endpoint categorizes transactions that are already linked to a connected bank account and marked as null.

To initiate the endpoint, send a GET request to the following endpoint:

Request

1
GET https://api.withmono.com/v1/enrichments/:id/transaction-categorisation

Request Path Parameter

  • id (required): This field expects the id of a connected bank account linked from mono connect

cURL Sample Request

Request

1234
curl --request GET \
  --url https://api.withmono.com/v1/enrichments/:id/transaction-categorisation \
  --header 'mono-sec-key: string' \
  --header 'accept: application/json'

Request Headers

Include the following header in your request for authentication:

  • mono-sec-key (required): Your Mono secret key.

Success Response

If the initiation request is successful, you will receive the following API response:

Request

1234567
{
    "status": "successful",
    "message": "Categorisation are currently being processed, you will receive a webhook when all
    transactions have been categorised",
    "timestamp": "2024-06-06T07:43:36.955Z",
    "data": null
}

Please note that once the API request above is successful, our system updates the transaction categories in the background. Once this process is done, you will receive a webhook notification confirming the update.

Sample Webhook Response

Request

1234567891011
{
  "data": {
    "event": "mono.events.transaction_categorisation",
    "data": {
      "account": "663e505883ca1bb05e41a6c8",
      "status": "available",
      "message": "Account transactions have been updated with their category.",
      "action": "Make a call to the transactions endpoint for updated account transactions"
    }
  }
}

With the above webhook mono.events.transaction_categorisation received, you can then proceed to call the transactions endpoint to confirm the updated category for each transaction record. Shared below is a sample of a transaction record with empty category before initiating, and a sample of a transaction record with updated category after initiating

Sample Transaction Response Before Categorisation is completed

Request

12345678910111213141516171819202122
{
    "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": null
        },
    ],
    "meta": {
        "total": 307,
        "page": 1,
        "previous": null,
        "next": "https://api.withmono.com/v2/66141b98aaa34e17e8cfdb76/transactions?page=2"
    }
}

Sample Transaction Response After Categorisation is completed

Request

12345678910111213141516171819202122
{
    "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": "bank_charges"
        },
    ],
    "meta": {
        "total": 307,
        "page": 1,
        "previous": null,
        "next": "https://api.withmono.com/v2/66141b98aaa34e17e8cfdb76/transactions?page=2"
    }
}

Transaction Category Types

CategoryTypeDefinitionAPI Format
Betting PayoutcreditAll incoming transactions that are recognized as income from gambling.betting_payout
Betting Depositdebitcategory for all outgoing transactions that are recognized as payments to gambling institutions.betting_deposit
billscreditAll income transactions that are recognized as income from bills.bills
Cash DepositcreditAll cash deposits at an ATM, Bank Counter etc.cash_deposit
Cash withdrawaldebitAll outgoing transactions that are recognized as cash withdrawals at ATM machines.cash_withdrawal
ChequedebitAll outgoing transactions that are recognized as cheque withdrawals.cheque
Cheque depositscreditCheque deposit into accountcheque_deposits
EducationdebitAll outgoing transactions related to education including high schools, universities, online courses, driving school, and similar.education
Entertainmentdebitcategory for all expense transactions that are recognized entertainment, Netflix, and Apple Music.entertainment
Bank ChargesdebitAll outgoing transactions that are recognized as financial services and various commissions, for example, cash withdrawal commission, various card fees and similar.bank_charges
Fooddebitcategory for all expense transactions that are recognized as food-related expenses.food
Gifts and DonationsdebitAll outgoing transactions made to flower shops, jewelry stores, photo shops, and private individual money transfers on birthdays.gifts_donations
GroceriesdebitAll transactions that are recognized as payments to grocery stores, hypermarkets, or supermarkets.groceries
HealthdebitAll outgoing transactions related to health including pharmacies, hospitals and similar.health
Interest receivedcreditAll incoming transactions that are recognized as interest payments. Interest income is money earned by an individual or company for lending their funds, either by putting them into a deposit account in a bankinterest_received
Investment PayoutcreditAll incoming transactions that are recognized as income from investments and currency trading.investment_payout
Investment DepositdebitTransfers to related to investments, for example, transfers to investment platforms.investment_deposit
Leisure activities, travelingdebitcategory for all expense transactions that are recognized as leisure activities and traveling.leisure_activities_traveling
Loanscreditstringcategory for all incoming transactions that are recognized as Loans. eg Payable loansloans
Loan Repaymentsdebitcategory for all outgoing transactions that are recognized as Loans. eg Payable loansloan_repayments
Other outgoing paymentsdebitcategory for all outgoing transactions that do not hold enough information to be able categorize with greater granularity.other_outgoing_payments
Online PaymentsdebitOutgoing payments through online payment platforms, like Paypal, Chipper cash, flutterwave.online_payments
Other incoming paymentscreditcategory for all incoming transactions that do not hold enough information to be able categorise with greater granularity.other_incoming_payments
Other incoming payments from employercreditAll other incoming transactions from the employer that is not salary. For example, per diems or reimbursements.other_incoming_payments_from_employer
Personal CaredebitAll outgoing transactions related to active lifestyle, for instance, gym membership, sportswear apparel, and sports nutrition, eden lifepersonal_care
Personal Transfercredit/debitcategory for all incoming transactions that are recognized as personal transfers. Personal transfers are defined as transfers that are received from or sent to a private individual.personal_transfer
Phone & InternetdebitAll transactions that are recognized as payments for mobile phone plans, internet plansloan_repayments
Rent and maintenancedebitAll transactions that are recognized as utility payments for rent and maintenance, property managementrent_maintanence
Returned debitcreditAll income transactions that are return of funds to a private individual (consumer), forcibly initiated by the issuing bank of the instrument used by a consumer to settle a debt.returned_debit
SalarycreditAll incoming transactions that are recognized as salary payments from an employer. Typically these transactions occur with some time period regularity, for example, on monthly or weekly or other time period regularity basissalary
SavingsdebitTransfers related to savings, for example, transfers to savings accounts.savings
Transportdebitcategory for all expense transactions that are recognized transportation-related expenses.transport
Utility Servicesdebitcategory for all expense transactions that are recognized as Utility services. Usually, these transactions occur with some time period regularity, for example, on monthly basis. Light, water, gas etc.utility_services
Unknowncredit/debitAll unrecognised transactionsunknown

Did this page help you?