Counterparties (Merchants)

Suggest Edits

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.

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.

📘

In order to use this new version of counterparties it is necessary to use the query param counterpartiesVersion=V3 when retrieving transactions and counterparties

📘

Some of the fields are optional but name, categoryId, transactionCategoryId and transactionCategory will always be present

Migration from V2 to V3

Below is a list of breaking changes going from 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:

https://moneyhubapi.readme.io/reference#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:

https://api.moneyhub.co.uk/docs/#/counterparties/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 2 months ago