Documentation

Counterparties (Merchants)

Suggest Edits

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=V3 when 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:

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:

GET global-counterparties

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 13 days ago