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
• 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.

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