Transaction Metadata Guide
Last updated Jun 7th, 2024
Overview
The Transaction Metadata API enriches transactions with additional details, providing a more comprehensive view of each financial activity. This can include merchant information, geographical data, and transaction types.
Integration Endpoints
Kindly note that there are three endpoints under under the Transaction metadata API, these are:
- Initiate Transactions Metadata: Starts the process of updating existing transactions in a connected bank account with meta information Initiate Transaction Metadata Upload
- Metadata Upload Batch: Allows you to upload a batch of transactions that you want to receive updated transaction metadata for.
- Retrieve Metadata Records: Fetches the list of transactions that have been updated with transaction metadata, from the uploaded transaction batch.
Initiate Transactions Metadata
This endpoint updates all the transactions linked to the provided account id with the transaction metadata
To initiate the endpoint, send a GET request to the following endpoint:
Request
GET https://api.withmono.com/v1/enrichments/:id/transaction-metadata
Request Path Parameter
- id (required): This field expects the id of a connected bank account linked from mono connect
cURL Sample Request
Request
curl --request GET \
--url https://api.withmono.com/v1/enrichments/:id/transaction-metadata \
--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
{
"status": "successful",
"message": "Transaction metadata are currently being processed, and
the data will be sent to you through your webhook",
"timestamp": "2024-05-21T10:38:02.376Z",
"data": null
}
Please note that once the API request above is successful, our system updates each transaction with the relevant metadata information in the background. Once this process is done, you will receive a webhook notification confirming the update.
Sample Webhook Response
Request
{
"data": {
"event": "mono.events.transaction_metadata",
"data": {
"account": "663e505883ca1bb05e41a6c8",
"status": "available",
"message": "Account transactions have been updated with their metadata.",
"action": "Make a call to the transactions endpoint for updated account transactions"
}
}
}
With the above webhook mono.events.transaction_metadata received, you can then proceed to call the transactions endpoint to confirm the updated metadata for each transaction record. Shared below is a sample of a transaction record with no metadata before initiating, and a sample of a transaction record with updated metadata after initiating
Sample Transaction Response Before Metadata is added
Request
{
"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"
},
],
"meta": {
"total": 307,
"page": 1,
"previous": null,
"next": "https://api.withmono.com/v2/66141b98aaa34e17e8cfdb76/transactions?page=2"
}
}
Sample Transaction Response After Metadata is completed
Request
{
"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",
"metadata": {
"category": "bank_charge",
"channel": "N/A",
"payee": "N/A",
"payment_method": "N/A",
"ref_num": "N/A",
"payment_processor": "N/A",
"location": "N/A",
"reason": "Stamp Duty"
}
},
],
"meta": {
"total": 307,
"page": 1,
"previous": null,
"next": "https://api.withmono.com/v2/66141b98aaa34e17e8cfdb76/transactions?page=2"
}
}
Note Regarding Metadata Object
For the metadata field to return all details, the following conditions must be met:
category: This will always be present for every transaction.
channel: For this field to be returned, the transaction narration must include NIP, NEFT, POS/WEB, POS, or WEB.
payee: There must be an individual or organization receiving the funds for this field to be returned.
payment_method: The transaction narration must contain pstk/paystack, flutterwave/flw/rave, or interswitch/isw for this field to be returned.
ref_num: A properly structured reference number must be present in the transaction for it to be captured.
location: Any known or popular location mentioned in the transaction narration, such as where an ATM withdrawal was made, will be captured and returned.
reason: This could be VAT, transfer commission, or any other capturable reason documented in the transaction narration. If no such information is present, this field will be empty.