Tutorial: Categorisation

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

Categorisation product is available as a Private Beta version.


Before retrieving data from the Get Account Transactions endpoint, you will first need to follow these steps:

  1. Obtain a Consent from the user
  2. Get Accounts for the user
  3. Get Account Transactions adding the optional parameter with=categorisation

Categorisation Schema

When the with=categorisation parameter is added, the account transactions endpoint supplements transactions with the enrichment. An example of the merchant identification can be seen below:


curl -L -X GET 'https://api.yapily.com/accounts/{account-id}/transactions?with=categorisation' \
 -H 'Content-Type: application/json' \
 -H 'consent: {consentToken}' \

Response (with Categorisation enrichment):

	"data": [{
		"transactionInformation": "TESCO PFS BASINGSTOKE 2020/07/30 3803",
		"bookingDateTime": "2020-08-01 00:00:00",
	   	"transactionAmount": {
			"amount": 10,
			"currency": "GBP"
		"proprietaryBankTransactionCode": "DEB",
			"isoBankFamilyCode": "CCRD",
			"isoBankSubFamilyCode": "POSD"
		"enrichment": {
			"categorisation": {
				 "categories": [“TRANSPORT”],
				 "source": "MERCHANT"
			"transactionHash": {
				"hash": "b0781fd71caa48c75039ec01c0ffb011.1"
			"merchant": {
				 "merchantName": "TESCO PETROL",
				 "parentGroup": "TESCO"
			"location": "BASINGSTOKE",
			"correctedDate": "2020-07-30T00:00:00.000Z"


Where possible we return the following:

  • merchantName
  • correctedDate This is extracted from the transaction string, which is likely to be the date the transaction took place on. The bookingDateTime can refer to the post-clearing value
  • location
  • paymentProcessor e.g. Paypal

Where we find a merchant, we return it with its associated category. For organisations selling a diverse range of products that don't fit within a single category, we assign multiple merchants with different categories and add a parentGroup to gather those merchants together. So Sainsbury's and Sainsbury's Bank are merchants with appropriate categories that also have Sainsbury's as their parentGroup.

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.

Fees and Cash

Yapily’s Categorisation engine will identify whether certain transactions are cash withdrawals or bank fees, based on the transaction codes or description. In the case of bank fees, we set the merchantName to the institution that manages the account. For cash withdrawals, we also parse merchantName from the description to gain more insights.

Please note

Transactions marked with subcategory ATM Withdrawal, indicate ATM withdrawals or cashback at merchant, not a transaction with that merchant.

Transaction Categories

To see the latest list of categories, use the Get Categories endpoint

Please note:

Where the model cannot identify a merchant we omit the merchant field entirely.