Egress Message Format
Schema for enriched transaction messages produced to the Kafka egress topic.
Egress message schema
| Field | Type | Optional | Description |
|---|---|---|---|
| transactionId | String (max 36) | No | Unique identifier for the transaction. |
| accountId | String (max 36) | No | Unique identifier for the account. |
| userId | String (max 36) | Yes | Unique identifier for the customer/user. |
| accountType | String (max 10) | No | The account type. Permitted values: cash, card, savings, investment, loan, mortgage, pension. |
| txCode | String (max 64) | Yes | The transaction code. The code is defined by the provider to describe the transaction type. |
| date | String (max 35) | No | The date and time of the transaction in ISO 8601 format. |
| description | String (max 256) | No | The transaction description which is commonly a combination of the merchant name and merchant location. |
| amount | Number | No | The transaction amount in major units of the currency. |
| currency | String (max 3) | No | The currency of the transaction, e.g. GBP, EUR. Defaults to GBP. |
| status | String (max 7) | Yes | The status of the transaction: either pending or posted. |
| merchantCategoryCode | String (max 4) | Yes | MCC code for the merchant's primary activities. A maximum 4 digit string. |
| meta | Object | Yes | Additional data for storage/pass-through. |
| mhInsights | Object | Yes | Contains the insights from Moneyhub's Data Enrichment Engine. See mhInsights fields below. |
mhInsights Fields
| Field | Type | Optional | Description |
|---|---|---|---|
| l1CategoryGroupId | String (max 2) | No | The level 1 category group to which the category belongs. |
| l1CategoryGroupName | String (max 13) | No | The name of the level 1 category group. |
| l1CategoryType | String (max 12) | No | The type of the level 1 category group. One of: expense, income, investment, transfer, pension, transfer_savings, uncategorised. |
| l2CategoryId | String (max 3) | No | The ID of the level 2 category. |
| l2CategoryName | String (max 21) | No | The name of the level 2 category. |
| l3Counterparty | Counterparty | Yes | The L3 counterparty of the transaction. See Counterparty Schema. |
| geotags | Array<Geotag> | Yes | Array of geotags for the transaction. Geotags for up to 3 candidate locations where the transaction could have taken place are ordered from most likely to least likely. See Geotag Schema. |
| cardPresent | Boolean | Yes | Indicates if the cardholder was present when the transaction occurred. Note that, online purchases are considered card holder not present. Only card holder present transactions are eligible for geotagging. We estimate this field from the transaction data. |
| timestampCreated | String (max 24) | Yes | Timestamp of when message containing the transaction was created on the Kafka raw ingest topic i.e. the topic that the Data Enrichment Engine retrieves messages from. For the API interface, this is effectively when the transaction was sent to the API. |
| timestampIngress | String (max 24) | Yes | Timestamp of when a transaction started being processed. |
| timestampEgress | String (max 24) | Yes | Timestamp set on transaction when processing has finished and it is about to be sent to the egress topic, and in the API case, sent back as the response. |
| errors | Array <Error> | Yes | An array of errors that occurred during enrichment of transaction. |
Example
Based on the example ingress message.
{
"transactionId": "123456",
"accountId": "5382358854398",
"userId": "5382358854398",
"accountType": "cash",
"txCode": ")))",
"date": "1970-01-01T00:00:00Z",
"description": "Tesco BriLL 293484 SS",
"amount": -10.99,
"currency": "GBP",
"status": "posted",
"merchantCategoryCode": "5411",
"meta": {
"sourceSystem": "hex",
"authorisedBy": "PStibbons",
"yearOfCreation": "Year of the Luminous Lemur"
},
"mhInsights": {
"l1CategoryGroupId": "4",
"l1CategoryGroupName": "shopping",
"l1CategoryType": "expense",
"l2CategoryId": "22",
"l2CategoryName": "groceries",
"l3Counterparty": {
"l3CounterpartyId": "030a7556-e17d-432d-8afb-7a9f71128152",
"l3CounterpartyName": "Tesco Express - Redcliffe, Bristol",
"parentId": "b3e0c142-1377-4e7d-b434-37b64d34a008",
"parentName": "Tesco Groceries",
"fullCompanyName": "Tesco Stores Limited",
"logoUrl": "examplelogo.com",
"website": "example.com",
"registeredLocation": null,
"l2CategoryName": "groceries",
"l3CounterpartyCategory": "convenience-shop",
"l4LoanType": null
},
"geotags": [
{
"geotagId": "39828184-5334-4ec5-ba65-8985912542dc",
"counterpartyName": "Tesco Express",
"counterpartyLabel": "Tesco Express, Redcliffe, Bristol, United Kingdom",
"houseNumber": "45",
"street": "Redcliffe Street",
"neighbourhood": "Redcliffe",
"locality": "Bristol",
"city": "Bristol",
"county": "Bristol",
"region": "South West England",
"postcode": "BS1 6NP",
"latitude": 51.4477,
"longitude": -2.5903,
"l3CounterpartyCategory": "convenience-shop",
"postcodeEstimated": false,
"postcodeErrorKm": null
},
{
"geotagId": "b4a9bf43-2b54-45d9-9bbd-a0aa1286e302",
"counterpartyName": "Tesco Express",
"counterpartyLabel": "Tesco Express, Victoria Street, Bristol, United Kingdom",
"houseNumber": null,
"street": "Victoria Street",
"neighbourhood": null,
"locality": "Bristol",
"city": "Bristol",
"county": "Bristol",
"region": "South West England",
"postcode": "BS1 6AH",
"latitude": 51.4493,
"longitude": -2.5878,
"l3CounterpartyCategory": "convenience-shop",
"postcodeEstimated": true,
"postcodeErrorKm": 0.21
},
{
"geotagId": "669c42a7-632c-43e4-b9f8-7f2b9f797e5e",
"counterpartyName": "Tesco Express",
"counterpartyLabel": "Tesco Express, Park Street, Bristol, United Kingdom",
"houseNumber": "12",
"street": "Park Street",
"neighbourhood": null,
"locality": "Bristol",
"city": "Bristol",
"county": "Bristol",
"region": "South West England",
"postcode": "BS1 5JA",
"latitude": 51.4539,
"longitude": -2.6019,
"l3CounterpartyCategory": "convenience-shop",
"postcodeEstimated": true,
"postcodeErrorKm": 0.08
}
],
"cardPresent": true,
"timestampCreated": "1970-01-01T00:00:00Z",
"timestampIngress": "1970-01-01T00:00:01Z",
"timestampEgress": "1970-01-01T00:00:02Z",
"errors": [
{
"source": "counterparty",
"code": "COUNTERPARTY_DETECTION_ERROR",
"cause": {
"message": "Counterparty detection error",
"type": "Error"
}
}
]
}
}