Tutorial: Getting Categorisation

This tutorial walks you through each of the steps required to obtain Categorisation.

Prerequisites

Before retrieving data from the Categorised Transactions endpoints, you will first need to follow these steps:

1. Obtain a Consent from the user
2. Get Accounts for the user
3. Register a Webhook for notification events when categorisation is done or failed

Webhook Registration

Please follow our Webhook Registration Guide in order to register a webhook for your application.

Webhook Events

In order to get notified when a categorisation request has finished successfully or failed you will have to subscriber to the following webhook events:

• transactions.categorisation.completed - is the event triggered when a categorisation request finishes successfully and the data is ready to be picked up.
• transactions.categorisation.failed - is the event triggered when a categorisation request fails to categorise the data successfully.

Categorisation Request

Categorisation works asynchronously and therefore the flow requires you to have a registered webhook on for your application.

In order to trigger a categorisation process follow the steps:

• Call POST /accounts/{accountId}/transactions/categorisation endpoint.
  • Define categorisationType (consumer or business) according to your use case.
• The response of the endpoint will return a categorisationId parameter.
• Store the categorisationId since all further API calls will require it.

Please check API Reference for an up to date specification of the API.

Setting Boundaries for Efficient Data Categorization

To enhance the efficiency of data categorisation requests via the POST /accounts/{accountId}/transactions/categorisation endpoint, it is crucial to set specific time frame boundaries using the from and before query parameters. This approach helps to minimise system overloads and improve success rates by dividing extensive data requests into smaller, manageable intervals. For instance, to categorise three years of transaction data, we recommend submitting six separate requests, each covering a six-month period.

Wait for webhook event

A webhook event will be sent to registered webhook in all situations success or failed.

Categorisation Success Event

When categorisation has finished successfully then an event is triggered on the topic transactions.categorisation.completed

{
  "id": "41285f64-5717-4562-b3fc-2c961236afa6",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "transactions.categorisation.completed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
    "metadata": {
      "key": "value"
    }
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010"
  }
}

Categorisation Fail Event

When categorisation request processing failed then an event is triggered on the topic transactions.categorisation.failed

{
  "id": "41285f64-5717-4562-b3fc-2c961236afa6",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "transactions.categorisation.failed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
    "metadata": {
      "key": "value"
    },
    "error": {
      "issues": [
        {
          "code": 12345,
          "message": "error message"
        }
      ]
    }
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010"
  }
}

How to Handle Failure Event

We recommend that you build your app's error handling around Error Codes, which would give you the best explanation of why your request has failed.

Retrieve Categorised Data

In order to retrieve categorised data call GET /accounts/{accountId}/transactions/categorisation/{categorisationId} endpoint.

Please check API Reference for an up to date specification of the API.

Elements

Where possible we return the following:

• categories e.g. childcare
• merchantName e.g. Netflix
• recurrenceType e.g one-off, subscription, recurring
• paymentProcessor e.g. Paypal

As with categories, the merchant and category of a transaction may change as we improve the accuracy of our merchant service and add new merchants.

Transaction Categories

To see the latest list of categories, use the GET /transactions/categorisation/categories/{accountType} endpoint

Categories definition

The definition for all the incoming and outgoing categories can be found here