Tutorial: Getting Enrichment Only

This tutorial walks you through each of the steps required to obtain Categorisation using your own transaction data.

The Yapily Plus categorisation product is available as a Beta version.

Prerequisites

Before retrieving data from the Categorised Transactions endpoints, you will first need to 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 subscribe 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 /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.

Wait for webhook event

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

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 /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