Overview of Transaction Data API

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

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

📘
Why does transaction data enrichment matter?

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.

For fintechs and banks: massively reduce chargebacks, improve user experience and open up for new use cases (early fraud detection, subscription management, 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, and merchant websites 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).

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 3 enrichment fields to be activated:
- category
- logo
- 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 Zafin’s engine (and considered noise) but we keep encountering new ones every now and then—so, flagging 🚩 still

Response

Sample Response

{
    "Transaction UUID": "7e993040-ad52-4646-98af-64d53b1835e2",
    "Merchant ID": "00005af3107a87ca",
    "Category ID": "1002",
    "Category Name": "Restaurant",
    "Subcategory Name": "American restaurant",
    "Clean Description": "KFC Jumeirah Lake Towers",
    "Country": "UNITED ARAB EMIRATES",
    "Logo": "https://api.zafin.com/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 4 enrichment fields.

Category Name
Logo
Merchant Website
Description is separated in 2 outputs:
- Clean Description
- Display Description

Category Levels

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

Parent Category
- Each category maps to a single parent category in Zafin'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 Zafin's categories over time.
Full list of categories: link (Subcategories not included as they are free text).