Getting started with enrichment

What you'll need to do to be able to start using Genify APIs

Overview of Transaction Data API

This guide will help you get started on using Genify's suite of Transaction Data API.

Transaction Categorization and Enrichment: automatic categorization of transactions, addition of merchant logos and websites, clean merchant names, and even carbon footprint estimates, making financial data more informative and visually appealing.

📘

Why does transaction data enrichment matter?

1. For customers: users can now easily identify whether a transaction is valid or not - based on the additional data such as correct merchant name, logo, geo-location etc.
2. For fintechs and banks: massively reduce chargebacks, improve user experience and open up for new use cases (early fraud detection, subscription management, carbon footprint calculation, etc.)

How does the transactions API/ API suite work?

• Authentication is via API keys added to the request headers; key, authorization
• User identification is applied through request header keys username and account_id
• The unified API can be used to collectively or individually out categories, sub-categories, merchant logos, merchant websites and the carbon footprint of each transaction
• Parameters would include the transaction details including raw descriptions, amounts, dates and country; with additional functionality such as direct categorizing using bank codes (client codes) or merchant category codes (MCC).

---

Testing Transaction Enrichment via Postman

An Online Postman collection to follow through this guide for testing Genify's transaction enrichment.

Collection Set-up and Authorization

The variables fields should be filled with your credentials

• variable: username value :  XXX
• variable: auth_key value : authorization
• variable: auth_value value :  YYY
• variable: url value: https://pfm.genify.ai/

The URL and authorization variables are static to the values provided.

• Example

  

• The Authorization tab in the collection should be configured as

  

Request Headers and Parameters

Headers

• Some or all enrichment fields have been activated for your credentials ➡️ make sure to (de)activate them (1️⃣ or 0️⃣) accordingly when making API calls to avoid errors
• There are 4 enrichment fields to be activated:
  • category
  • logo
  • carbonfootprint
  • website
• There are also 3 essential headers that should be filled out:
  • username: to be filled by the variable that has been set-up previously
  • account_id:
    • Can be filled by 0 during your testing
    • In production, you should send an end-user pseudo-ID (1 person using your app ⇒ 1 unique pseudo-ID)

Parameters

There are 4 mandatory parameters that should be filled when making requests:

• The description of the merchant in the description field

• The right country in the country field

  • E.g.: ae for United Arab Emirates, be for Belgium, sa for KSA
  • Full list of ISO country codes: link

• The amount spent by transaction in the amount field

  • Negative ➖ for expenses

• The date of the transaction in the date field

  • The date format is YYYY-MM-DD

  

  
  

Considerations

• There's a limited number of API calls made available to you during your initial testing

• Negative ➖ amounts are expenses, positive ➕ amounts are incoming (i.e., income) transactions

  Transaction type	Example amount
  Expense	-10.86
  Incoming	21.34

• For superior performance, it generally helps to remove from transaction descriptions any tokens not carrying information (often used for bank-internal purposes)

  • See examples below:

    Raw transaction description	Processed transaction descriptions
    KINOKUNIYA DUBAI ARE	KINOKUNIYA
    DUBAI TAXI DUBAI ARE	DUBAI TAXI
    NATIONAL TAXI DUBAI ARE	NATIONAL TAXI
    CAREEM NETWORKS FZ LLC DUBAI ARE	CAREEM NETWORKS FZ LLC

  • A lot of such tokens are already learnt by Genify’s engine (and considered noise) but we keep encountering new ones every now and then—so, flagging 🚩 still

Response

Sample Response

json

{
    "Transaction UUID": "7e993040-ad52-4646-98af-64d53b1835e2",
    "Merchant ID": "00005af3107a87ca",
    "Carbon Footprint": 26.316,
    "Category ID": "1002",
    "Category Name": "Restaurant",
    "Subcategory Name": "American restaurant",
    "Clean Description": "KFC Jumeirah Lake Towers",
    "Country": "UNITED ARAB EMIRATES",
    "Logo": "https://pfm.genify.ai/api/v1.0/txn-data/logo/KFC.png",
    "Merchant Website": "https://www.kfc.com",
    "Display Description": "Kfc"
}

As seen in the JSON object. There are 5 enrichment fields.

1. Category Name
2. Logo
3. Merchant Website
4. Carbon Footprint
5. Description is separated in 2 outputs:
   • Clean Description
   • Display Description

Category Levels

Categorization hierarchy: Genify's Transaction Data API offers 3️⃣ category levels

Genify's Category Tree

• Parent Category
  • Each category maps to a single parent category in Genify's standard hierarchy, so the API does not return the parent category. Knowing the category implies the parent.
• Category
  • Displayed in the API under Category Name. Unknown expenses use Category ID = 0 and unknown income uses Category ID = 10007.
• Subcategory
  • It is a very granular and gradually expanding free-text-like field shown in the API as Subcategory Name. Some subcategories may initially appear unmapped, and their name will also appear in the Category Name field with Category ID = 0.
  • These unmapped subcategories are gradually mapped to their appropriate Genify's categories over time.
• Full list of categories: link (Subcategories not included as they are free text).