Guides
Postman collections ↗Bud Console ↗

Transactions

Suggest Edits

The transaction entity is one of the main resources Bud collects to serve all the different use cases for our Clients: it represents a bank transaction, so money moving from one bank account to another or in some cases an active card check.

There are different ways to ingest transactions with Bud, the two main sources are Open Banking (please, check our "Intro to Connect" guide here) and First Party Ingestion (more information here).

The transaction entity

Each transaction is represented in Bud by two main sections: the main list of attributes and the enrichments.

Here you can see an example of the main attribute set of a transaction:

{
  "transaction_id": "fbdc28e82f0f137586a526a88ec4a6be",
  "account_id": "5bd9ecaf31fc2d5172fd89cb61b89fc6",
  "provider": "BankOfBud",
  "description": "paypal* specialty coffee",
  "credit_debit_indicator": "debit",
  "status": "booked",
  "amount": {
    "value": "10.99",
    "currency": "GBP"
  },
  "date_time": "2022-05-28T10:00:00Z",
  "posted_date_time": "2022-05-29T00:00:00Z",
  "merchant_category_code": ""
}

These are the main pieces of information we retrieve from our data sources (eg: Open Banking, or First Party Ingestion) which we then normalise, and store. They give you the basic information about the bank transaction, like its identifier, the account they refer to, the transaction description, amount and dates.

It's important to note that we store two dates for each transaction:

  • date_time: This represents the date and time when the transaction took place.
  • posted_date_time: This represents the date and time when the amount was moved in or out of the account. For credits, this is the date that the asset becomes available, for debits, this is the date that the asset ceases to be available.

The two different dates are reported to allow Clients to know when the resource changed from status pending to status booked. Until this happens, the two dates are identical.

📘

Transaction ID

The Bud transaction identifier is an immutable ID that doesn't always match the ID provided at the ingestion time (for both Open Banking and First Party Data). When the data source doesn't guarantee the immutability of the transactions and their identifiers, Bud generates the transaction_id starting from the information known to be immutable.

The list of attributes used can vary based on the data source and provider.

The Bud transaction ID can be considered immutable even when the transaction change its status from pending to booked.

Another attribute that Bud normalises is the description: This is not always reported as the description received at ingestion time when the transaction comes from Open Banking, we normalise the description to ensure we always provide one thanks to logic that involves the original description, the recognised merchant, and the transaction date. This ensures Clients always have a way to describe the transactions to the end user.

The provider attribute included in the transaction model refers to the provider (the Financial Institution) associated with the Account the transaction refers to. In the case of transactions ingested using Open Banking, the provider information is always present and represents the Provider data source we fetched the transactions from. Instead, when transactions are ingested through First Party Ingestion, the provider is populated only if the related account entity was ingested before ingesting the transactions, and it represents the provider we received at that time. If no account is ingested with the same account ID, the provider attribute remains empty.

The suggested_description and suggested_logo fields are derived from the enrichments that have been run against the transaction. The purpose of these fields is to inform Clients of how Bud suggests transactions should be shown to customers to give the best possible experience. They strike a balance between visual cleanliness and comprehensibility. The suggested_description is a required field and will always be populated, whereas the suggested_logo is optional and will not be present in the response if we haven't found a merchant or processor match in our database. Therefore, clients are advised to implement logic to handle dealing with transactions where Bud is unable to provide a logo.

📘

Please note whenever displaying a transaction to a customer, Bud would always advise Clients to let a customer 'click in' to the transaction in order to be able to see more information including the full transaction description.

The transaction Enrichments

The second part of the transaction entity is formed by the enrichments object and the tagslist.

{
  "transaction_id": "fbdc28e82f0f137586a526a88ec4a6be",
  "account_id": "5bd9ecaf31fc2d5172fd89cb61b89fc6",
  "provider": "BankOfBud",
  "description": "paypal* specialty coffee",
  "credit_debit_indicator": "debit",
  "status": "booked",
  "amount": {
    "value": "10.99",
    "currency": "GBP"
  },
  "date_time": "2022-05-28T10:00:00Z",
  "posted_date_time": "2022-05-29T00:00:00Z",
  "enrichments": {
    "categories": {
      "l1": {
        "slug": "eating_out",
        "confidence": "0.99"
      },
      "l2": {
        "slug": "cafes_and_eating_out",
        "confidence": "0.98"
      }
    },
    "merchant": {
      "id": "01cc2d49-6144-46f1-9414-67c99b139a95",
      "slug": "specialty_coffee",
      "display_name": "Specialty Coffee Supplier Ltd.",
      "logo": "http://url/specialty_coffee_supplier_logo.jpeg",
      "website": "http://www.url.com",
      "tokens": [
        {
          "value": "speciality coffee",
          "confidence": "0.98"
        }
      ]
    },
    "processor": {
      "id": "18f63293-0217-4520-bbf0-071dca7a9d04",
      "slug": "paypal",
      "display_name": "PayPal",
      "logo": "http://url/paypal_logo.jpeg",
      "website": "https://www.paypal.com",
      "tokens": [
        {
          "value": "paypal",
          "confidence": "0.92"
        }
      ]
    },
    "regularity": {
      "frequency": "monthly",
      "predicted_date_times": [
        "2022-06-28T15:00:00Z",
        "2022-07-28T15:00:00Z",
        "2022-08-28T15:00:00Z"
      ],
      "group_label": "a_group_id"
    },
    "location": {
      "street_address":"Shepherds Bush Rd",
      "city":"London",
      "region":"London",
      "postal_code":"W6 7NL",
      "country":"UK",
      "geolocation":{
         "longitude": 51.497678,
         "latitude": -0.223766
      },
      "address_lines":[
         "180",
         "Shepherds Bush Rd",
         "London",
         "W6 7NL",
         "United Kingdom"
      ],
      "tokens":[
         "Shepherds Bush Rd",
         "London",
         "uk"
      ]
    },
    "transaction_types": [
      "card",
      "debit"
    ],
    "names": [
      "jane doe"
    ]
  },
  "tags": [
    "regular-transaction"
  ]
}

Bud provides a complete list of enrichments for all the transactions ingested (no matter what the ingestion method was). They are all generated at ingestion time, and they will be available for Clients to retrieve as soon as the ingestion process is completed.

Each enrichment is the result of years of AI model training and tweaking our data intelligence algorithm to ensure Clients and End Users get a complete list of information added to each transaction.

Some of Bud's enrichments are described below. Please also look at our API documentation here for more information about each enrichment.

Categories

{
  "l1": {
    "slug": "eating_out",
    "confidence": "0.99"
  },
  "l2": {
    "slug": "cafes_and_eating_out",
    "confidence": "0.98"
  }
}

Categories associated with a transaction, as generated by Bud's artificial intelligence models. Currently two levels of category are supported, with l1 being higher level and category level and l2 being more refined and specific. Typically we would expect l1s to be of sufficient detail to present back to customers in personal finance management apps and l2s to be used for more detailed analysis such as affordability analysis and monitoring.

Each category level is represented by a slug that can be used to uniquely identify a category, and a confidence that is a value between 0.50 and 1.00 indicating the level of confidence behind the category match.

Bud uses different models depending on the region and use case. You can find the full list of models available in your region by calling the endpoint documented here, and the full list of categories available for each model by calling the Retrieve Categories endpoint as documented here.

Merchant

{
  "id": "01cc2d49-6144-46f1-9414-67c99b139a95",
  "slug": "specialty_coffee",
  "display_name": "Specialty Coffee Supplier Ltd.",
  "logo": "http://url/specialty_coffee_supplier_logo.jpeg",
  "website": "http://www.url.com",
  "tokens": [
    {
      "value": "speciality coffee",
      "confidence": "0.98"
    }
  ]
}

Merchant enrichment associated with a transaction, as generated using a combination of Bud's artificial intelligence models and our proprietary database of known merchants.

The logo and website information are not always present, they are populated only when the recognised merchant is part of our database. This happens for the majority of the merchants recognised by our models, and we constantly improve the data set to ensure the best possible coverage.

The merchant logo is often included by our Clients when showing the transactions in a list as it helps the End User to visualise and recognise transactions.

Processor

{
  "id": "18f63293-0217-4520-bbf0-071dca7a9d04",
  "slug": "paypal",
  "display_name": "PayPal",
  "logo": "http://url/paypal_logo.jpeg",
  "website": "https://www.paypal.com",
  "tokens": [
    {
      "value": "paypal",
      "confidence": "0.92"
    }
  ]
}

Processor enrichment associated with a transaction, as generated using a combination of Bud's artificial intelligence models and a database of known payment processors.

The logo and website information are not always present, they are populated only when the recognised processor is part of our database. This happens for the majority of the processors recognised by our models, and we constantly improve the data set to ensure the best possible coverage.

Regularity

{
  "frequency": "monthly",
  "predicted_date_times": [
    "2022-06-28T15:00:00Z",
    "2022-07-28T15:00:00Z",
    "2022-08-28T15:00:00Z"
  ],
  "group_label": "a_group_id"
}

Bud uses a number of algorithms to recognise the regularity of each transaction. We are able to recognise a number of different regular frequencies: daily, weekly, biweekly, monthly, quarterly, six_monthly, and annually.

Please note, in most cases, for a transaction to be considered regular the model needs to have 3 separate instances of it. This means for a new weekly transaction it will take 3 weeks before the transactions regularity is identified and 3 months for monthly transactions.

When a transaction is recognised as regular, we also associate a list of dates and times when the transaction is expected to happen again. These dates can be in the past or in the future based on when the transaction happened and its regularity.

The group_label returned as part of the regularity enrichment helps to group regular transactions together, as the same group_label is returned for each iteration of the same regular transaction over time.

Location

{
  "street_address":"Shepherds Bush Rd",
  "city":"London",
  "region":"London",
  "postal_code":"W6 7NL",
  "country":"UK",
  "geolocation":{
    "longitude": 51.497678,
    "latitude": -0.223766
  },
  "address_lines":[
    "180",
    "Shepherds Bush Rd",
    "London",
    "W6 7NL",
    "United Kingdom"
  ],
  "tokens":[
    "Shepherds Bush Rd",
    "London",
    "uk"
  ]
}

The location enrichment represents the place where the transaction took place. Its definition includes a list of attributes that define the location as a human-readable address, and its geolocation representation that allows Clients to represent transactions on a map.

For online transactions such as with Amazon or a Netflix subscription, we will add an online tag to the transaction so that you know there is no physical address associated with the transaction.

For more information about the location enrichment please don't hesitate to get in touch with your Bud representative.

Transaction Types

[
  "card",
  "debit"
]

A list of transaction types based on what is provided by the data source and normalised by Bud.

Names

[
  "jane doe"
]

A list of possible names of people as found in the transaction description. This is often present when the transaction represents an exchange of money between people that doesn't involve a public entity such as a bank transfer.

Tokens

In many of Bud's enrichment entities we include an attribute name tokens that represents a list of strings correlated to the enrichment itself. This can often be used as a support to represent the enrichment result to the End User or to internally classify it.

Tags

A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.

Please, refer to the API documentation here for the list of available tags.

How to retrieve transactions

There are multiple ways for Clients to fetch transactions from Bud based on the use case.

You can for example use the Retrieve Transactions V2 endpoint documented here to fetch a specific set of transactions filtering by dates, tags, and more. This endpoint gives you the flexibility to retrieve data based on your use case.

For many of the possible use cases though, Bud already provides a simplified way of retrieving transactions thanks to the many endpoints documented under the Smart Finder API section of our API documentation where Clients can find APIs to retrieve transactions and additional data for various use cases. A few examples are:

  • Retrieve Regular Transactions
  • Retrieve Future Transactions
  • Retrieve Income Transactions
  • Retrieve Loan Transactions
  • And more...

All our endpoints used to retrieve transactions support filtering by dates to ensure high performance on retrieval and to limit the amount of data exchanged on request.

Financial Data Correction

It happens that for some End Users the category of their transaction can be a personal concept, and they prefer to group their transactions under a different category. To allow this flexibility, Bud supports the concept of Correction that can be used by Clients to communicate to Bud how a transaction should be enriched for a specific Customer. You can find the API documentation here.

Corrections can be applied to one specific transaction, or to all the transactions recognised as similar to the specified one. This allows End Users to quickly re-categorise a set of regular transactions instead of having to change the category for each one of them.

The same concept is also available in order to allow End Users to specify a different Merchant for their transactions.

Deleting transactions

When transaction data is no longer needed, Clients can delete it by sending a request to the Remove Provider Data endpoint documented here.

When calling this endpoint, Bud deletes all the financial data stored for the specified Customer, including transactions, accounts, balances, and more.

It's important to note that once the data is deleted it cannot be restored.

📘

Deleting transactions ingested through Open Banking

When transactions are ingested through Open Banking, deleting the transactions by using the Remove Provider Data endpoint doesn't affect the Open Banking Consent stored for the Customer. This means that if an Open Banking data Refresh is initiated for that customer, the last 90 days of transactions will be stored again.

For these customers you will also need to revoke the customer's Open Banking Consent, please, refer to the related guide here.



If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.

Updated about 1 month ago