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:
- Initiate Transactions Categorising: Starts the process of categorizing existing transactions in a connected bank account that are currently marked as null.
- Categorisation Upload Batch: Allows you to upload a batch of transactions that you want to be categorized.
- 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
| Category | Type | Definition | API Format |
| Betting Payout | credit | All incoming transactions that are recognized as income from gambling. | betting_payout |
| Betting Deposit | debit | category for all outgoing transactions that are recognized as payments to gambling institutions. | betting_deposit |
| bills | credit | All income transactions that are recognized as income from bills. | bills |
| Cash Deposit | credit | All cash deposits at an ATM, Bank Counter etc. | cash_deposit |
| Cash withdrawal | debit | All outgoing transactions that are recognized as cash withdrawals at ATM machines. | cash_withdrawal |
| Cheque | debit | All outgoing transactions that are recognized as cheque withdrawals. | cheque |
| Cheque deposits | credit | Cheque deposit into account | cheque_deposits |
| Education | debit | All outgoing transactions related to education including high schools, universities, online courses, driving school, and similar. | education |
| Entertainment | debit | category for all expense transactions that are recognized entertainment, Netflix, and Apple Music. | entertainment |
| Bank Charges | debit | All outgoing transactions that are recognized as financial services and various commissions, for example, cash withdrawal commission, various card fees and similar. | bank_charges |
| Food | debit | category for all expense transactions that are recognized as food-related expenses. | food |
| Gifts and Donations | debit | All outgoing transactions made to flower shops, jewelry stores, photo shops, and private individual money transfers on birthdays. | gifts_donations |
| Groceries | debit | All transactions that are recognized as payments to grocery stores, hypermarkets, or supermarkets. | groceries |
| Health | debit | All outgoing transactions related to health including pharmacies, hospitals and similar. | health |
| Interest received | credit | All 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 bank | interest_received |
| Investment Payout | credit | All incoming transactions that are recognized as income from investments and currency trading. | investment_payout |
| Investment Deposit | debit | Transfers to related to investments, for example, transfers to investment platforms. | investment_deposit |
| Leisure activities, traveling | debit | category for all expense transactions that are recognized as leisure activities and traveling. | leisure_activities_traveling |
| Loans | credit | stringcategory for all incoming transactions that are recognized as Loans. eg Payable loans | loans |
| Loan Repayments | debit | category for all outgoing transactions that are recognized as Loans. eg Payable loans | loan_repayments |
| Other outgoing payments | debit | category for all outgoing transactions that do not hold enough information to be able categorize with greater granularity. | other_outgoing_payments |
| Online Payments | debit | Outgoing payments through online payment platforms, like Paypal, Chipper cash, flutterwave. | online_payments |
| Other incoming payments | credit | category for all incoming transactions that do not hold enough information to be able categorise with greater granularity. | other_incoming_payments |
| Other incoming payments from employer | credit | All other incoming transactions from the employer that is not salary. For example, per diems or reimbursements. | other_incoming_payments_from_employer |
| Personal Care | debit | All outgoing transactions related to active lifestyle, for instance, gym membership, sportswear apparel, and sports nutrition, eden life | personal_care |
| Personal Transfer | credit/debit | category 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 & Internet | debit | All transactions that are recognized as payments for mobile phone plans, internet plans | loan_repayments |
| Rent and maintenance | debit | All transactions that are recognized as utility payments for rent and maintenance, property management | rent_maintanence |
| Returned debit | credit | All 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 |
| Salary | credit | All 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 basis | salary |
| Savings | debit | Transfers related to savings, for example, transfers to savings accounts. | savings |
| Transport | debit | category for all expense transactions that are recognized transportation-related expenses. | transport |
| Utility Services | debit | category 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 |
| Unknown | credit/debit | All unrecognised transactions | unknown |