Counterparties (Merchants)
A counterparty refers to any entity or individual that is involved in a financial transaction with a user. This could include merchants, service providers, or any other party that a user interacts with financially. Counterparties are identified and categorised to help users better understand and manage their financial activities.
The Moneyhub platform uses counterparties to provide insights into spending patterns, categorize transactions, and enhance financial management for users.
Our API automatically detects counterparties when transactions are aggregated as part of connecting a financial institution or when manually sending them to our API. We do this by analysing transaction descriptions and any other relevant information that we can retrieve from the Financial institutions
This enable us to to provide insights into spending patterns, categorize transactions, and enhance financial management for users.
Counterparties V3
This new version only has global counterparty detection for transactions.
Each transaction has the property counterpartyId which can be mapped to the list of global counterparties. If a transaction is missing this field it means that we were not able to detect a counterparty.
Note: For personal Account 65% of all non-transfer category transactions have a counterparty associated with them
JSON Schema
{
"additionalProperties": false,
"type": "object",
"example": {
"id": "a7920ee2-62f4-5465-84eb-af6ef1f7074a",
"name": "J P Morgan Chase",
"parentId": null,
"parentName": null,
"fullCompanyName": "J P MORGAN CHASE & CO.",
"logoUrl": "https://s3.eu-west-1.amazonaws.com/mft-counterparty-logos-prod/55faa0f4226fe84c78e011df.svg",
"website": "https://www.jpmorganchase.com/",
"merchantCategoryCode": null,
"merchantCategoryDescription": null,
"registeredLocation": "25 Bank Street, London, United Kingdom",
"categoryId": "bank",
"analyticalCategory": "bank",
"transactionCategoryId": "std:2f3e2df7-827b-449d-a085-909c042d7f41",
"transactionCategory": "investment"
},
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for the counterparty.",
"format": "uuid",
"example": "a2c7b1e3-b9ce-5c61-9eb1-be897c04cee0"
},
"name": {
"type": "string",
"description": "Name of the counterparty",
"example": "Tesco Mobile"
},
"parentId": {
"type": "string",
"description": "The unique identifier for the counterparty parent",
"example": "26c417bc-248f-5e3f-9835-3cd9c2842f50",
"x-nullable": true
},
"parentName": {
"type": "string",
"description": "Name of the counterparty parent",
"example": "Tesco",
"x-nullable": true
},
"fullCompanyName": {
"type": "string",
"description": "Company name",
"example": "Tesco Stores Limited",
"x-nullable": true
},
"logoUrl": {
"type": "string",
"description": "Logo Url of counterparty",
"example": "https://s3.eu-west-1.amazonaws.com/mft-counterparty-logos-prod/7e43257eac60348110bd15cc.svg",
"x-nullable": true
},
"website": {
"type": "string",
"description": "Website url of counterparty",
"example": "https://www.tescomobile.com",
"x-nullable": true
},
"merchantCategoryCode": {
"type": "string",
"description": "",
"example": "",
"x-nullable": true
},
"merchantCategoryDescription": {
"type": "string",
"description": "",
"example": "",
"x-nullable": true
},
"registeredLocation": {
"type": "string",
"description": "Registered address of company",
"example": "17-21 Wenlock Road, London N1 7G",
"x-nullable": true
},
"categoryId": {
"type": "string",
"description": "Category used to group similar counterparties",
"example": "mobile-phone",
"x-nullable": true
},
"analyticalCategory": {
"type": "string",
"description": "DEPRECATED. Category used to group similar counterparties",
"example": "mobile-phone",
"x-nullable": true
},
"transactionCategoryId": {
"type": "string",
"description": "Most appropriate transaction category id for transactions to this counterparty",
"example": "std:4b0255f0-0309-4509-9e05-4b4e386f9b0d",
"x-nullable": true
},
"transactionCategory": {
"type": "string",
"description": "Most appropriate transaction category name for transactions to this counterparty",
"example": "telephone",
"x-nullable": true
}
},
"required": [
"id",
"name",
]
}
In order to use this new version of counterparties in v2.0 of Moneyhub's API it is necessary to use the query param
counterpartiesVersion=V3when retrieving transactions and counterparties. In v3.0 of Moneyhub's API this is the only version available of counterparties
Some of the fields are optional but name, categoryId, transactionCategoryId and transactionCategory will always be present
Migration from Counterparties V2 to V3
Below is a list of breaking changes going from Counterparties V2 to V3
- Counterparty payload has changed significantly e.g. (
label->name) - Local counterparties are not supported
- Transactions do not always have
counterpartyId - GET /accounts/{accountId}/counterparties is deprecated
In order to migrate to V3 we recommend the following:
- Update mapping of counterparties to cater for schema changes
- Handle the scenario when transactions do not have
counterpartyId - Retrieve the full list of global counterparties from GET global-counterparties instead of GET /accounts/{accountId}/counterparties
Counterparties V2 (Deprecated)
Counterparties V2 is the default version when retrieving transactions but there is no active development for this version. We encourage clients to transition to V3
We have 2 types of counterparties:
local: This type of counterparties are unique per user. Think of standing orders, transfers, local shops.global: This type of counterparties are shared among all users and contain more information about the merchant such as logo and website. Think of groceries shops and merchants stores.
Each transaction has the property counterpartyId which can be mapped to the list of counterparties that can be retrieved for each user's account using the following endpoint:
GET /accounts/{accountId}/counterparties
Global counterparties
This type of counterparties allow you to group transactions from certain merchants or providers. You can use the extra information that we provide for each of this counterparties to show their logo or generate more insights for your users.
You can retrieve the full list of global counterparties that we support in the following endpoint:
JSON Schema
{
"additionalProperties": false,
"type": "object",
"example": {
"id": "global:13dbb5c043ee5fb759d26e33eead84d499e184bcf5d786f6e4ab38f9a1b4682d",
"label": "Amazon",
"companyName": "Amazon UK Services Ltd",
"logo": "https://upload.wikimedia.org/wikipedia/commons/a/a9/Amazon_logo.svg",
"website": "https://www.amazon.co.uk",
"mcc": {
"code": "5399",
"name": "Miscellaneous General Merchandise"
},
"type": "global"
},
"properties": {
"id": {
"description": "The unique identifier for the counterparty.",
"example": "global:13dbb5c043ee5fb759d26e33eead84d499e184bcf5d786f6e4ab38f9a1b4682d",
"type": "string"
},
"label": {
"description": "A label describing the counterparty",
"example": "Amazon",
"type": "string"
},
"type": {
"description": "The type of counterpary (specific to an account, or globally recognoised accross all users)",
"example": "local",
"type": "string",
"enum": [
"global",
"local"
]
},
"companyName": {
"description": "The full name of the company (only for global counterparties)",
"example": "Amazon",
"type": "string"
},
"logo": {
"description": "The url to the company logo (only for global counterparties)",
"example": "https://upload.wikimedia.org/wikipedia/commons/a/a9/Amazon_logo.svg",
"type": "string"
},
"website": {
"description": "The url to the company website (only for global counterparties)",
"example": "https://www.amazon.co.uk",
"type": "string"
},
"mcc": {
"type": "object",
"properties": {
"code": {
"description": "The merchant category code (only for global counterparties)",
"example": "5399",
"type": "string"
},
"name": {
"description": "The merchant category code name (only for global counterparties)",
"example": "Miscellaneous General Merchandise",
"type": "string"
}
}
}
},
"required": [
"id",
"label",
"type"
]
}
Updated about 2 months ago