Transaction Data API

Endpoints used to enrich banking transaction data with categories, merchant logos and the carbon footprint.

The Transaction Data API endpoints require authorization (via API key) as they are hosted by Genify in the cloud. Other endpoints are installed on our clients' cloud or premises.

Enrich Transaction Data

POST https://pfm.genify.ai/api/v1.0/txn-data/

Unified endpoint: this single endpoint can be used for all three features (categorization, merchant logo, carbon footprint), for convenience. This endpoint categorizes a banking transaction from its description and amount, and also returns the corresponding merchant logo and carbon footprint. Any one, two or all three features can be queried (See individual endpoint documentation for more details).

Query Parameters

Headers

{
	"Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
	"Merchant ID": "00005af3107a8964"
	"Carbon Footprint": 0.661,
	"Category ID": "2005",
	"Category Name": "Telephone and internet",
	"Clean Description": "Orange Egypt",
	"Country": "EGYPT",
	"Display Description": "Orange",
	"Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Orange.png",
	"Merchant Website": "www.orange.eg",
	"Subcategory Name": "Telephone and internet"
}

Get Categorized Transaction

GET https://pfm.genify.ai/api/v1.0/txn-data/

The unified endpoint can be used to only categorize a banking transaction (from a credit card, a debit card or a bank account) from its description and amount. The transaction is categorized as one of ~80 categories in Genify's category tree.

Query Parameters

Headers

{
    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": "00005af3107a8964"
    "Carbon Footprint": null,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Country": "EGYPT",
    "Logo": null,
    "Subcategory Name": "Coffee shop",
    "Clean Description": "Starbucks Plaza Central",
    "Display Description": "Starbucks"
}

Get Categorized Transaction ( based on client code )

GET https://pfm.genify.ai/api/v1.0/txn-data/

Query Parameters

Headers

{

    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": null
    "Carbon Footprint": null,
    "Category Confidence": 1,
    "Category ID": "CHD",
    "Category Name": "Banking Service",
    "Country": "egypt",
    "Logo": null,
    "Subcategory Name": null,
    "Clean Description": "CASH DEPOSIT",
    "Display Description": "CASH DEPOSIT"
}

GET https://pfm.genify.ai/api/v1.0/txn-data/

The same endpoint can be used to only obtain the merchant logo corresponding to a transaction. The merchant logo is retrieved from Genify's proprietary database which grows incrementally if an unknown merchant is queried.

Query Parameters

Headers

{
    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": null
    "Carbon Footprint": null,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Clean Description": "Starbucks",
    "Country": "EGYPT",
    "Display Description": "Starbucks",
    "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Starbucks%20round.png",
    "Merchant Website": "locations.starbucks.eg",
    "Subcategory Name": "Coffeeshop"
}

You can visit this link to view the image from the Base64 code.

Get Carbon Footprint

GET https://pfm.genify.ai/api/v1.0/txn-data/

The same endpoint can be used to only calculate the carbon footprint (carbon-equivalent weight in kg) corresponding to a transaction description, amount and category ID/name. The carbon footprint is computed using Genify's curated database of carbon footprint values. When no category is passed as input, the Genify transaction categorizer is used to infer the category.

Query Parameters

Headers

{

    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": "00005af3107a8964"
    "Carbon Footprint": 6.3,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Clean Description": "Starbucks",
    "Country": "EGYPT",
    "Display Description": "Starbucks",
    "Logo": null,
    "Merchant Website": "locations.starbucks.eg",
    "Subcategory Name": "Coffeeshop"
}

Post Classification Error

POST https://pfm.genify.ai/api/v1.0/txn-data/report/error/

Request Body

{
    "message": "error report was received"
}

Batch Transactions

POST https://pfm.genify.ai/api/v1.0/txn-data/

This Endpoint will automatically operate as a batch endpoint whenever it gets a input as "raw body", "csv file", or "json file". The input ideally should contain list of transactions to be processed in batches.

Headers

Request Body

{
    "batch_txn uuid": "22f48412-2fb5-11ee-9863-d281dc259316",
    "txns uuids": [
        "23560778-2fb5-11ee-931c-d281dc259316",
        "235608c2-2fb5-11ee-931c-d281dc259316",
        "23560944-2fb5-11ee-931c-d281dc259316",
        "235609a8-2fb5-11ee-931c-d281dc259316",
        "23560a02-2fb5-11ee-931c-d281dc259316",
        "23560a66-2fb5-11ee-931c-d281dc259316",
        "23560ac0-2fb5-11ee-931c-d281dc259316",
        "23560b24-2fb5-11ee-931c-d281dc259316",
        "23560b88-2fb5-11ee-931c-d281dc259316",
        "23560be2-2fb5-11ee-931c-d281dc259316"
    ]
}

Batch Transactions Demo

Retrieve Batch Transactions

POST https://pfm.genify.ai/api/v1.0/txn-data/retrieve-txn/batch/

In this Endpoint we will make use of the Txns UUIDs generated to retrieve all the Txns or Retrieve any number of txns by specifying their UUIDs

Headers

Request Body

{
    "successful_transactions": {
        "23560778-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8950"
            "Carbon Footprint": null,
            "Category ID": "1002",
            "Category Name": "Restaurant",
            "Clean Description": "Zomato Order",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Zomato",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Zomato.png",
            "Merchant Website": null,
            "Subcategory Name": "Indian restaurant"
        },
        "235608c2-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8951"
            "Carbon Footprint": null,
            "Category ID": "4003",
            "Category Name": "Electronics",
            "Clean Description": "Apple Itunes Store Aed",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Apple",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/apple%20us.png",
            "Merchant Website": null,
            "Subcategory Name": "Electronics"
        },
        "23560944-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8952"
            "Carbon Footprint": null,
            "Category ID": "9005",
            "Category Name": "Software and apps",
            "Clean Description": "Itunes",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/google_logos/Itunes.png",
            "Merchant Website": null,
            "Subcategory Name": "Software and apps"
        },
        "235609a8-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8953"
            "Carbon Footprint": null,
            "Category ID": "1001",
            "Category Name": "Supermarket",
            "Clean Description": "Carrefour Market Alsee",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Carrefour Market",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Carrefour Market.png",
            "Merchant Website": null,
            "Subcategory Name": "Supermarket"
        },
        "23560a02-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8954"
            "Carbon Footprint": null,
            "Category ID": "1001",
            "Category Name": "Supermarket",
            "Clean Description": "Swiss Mart Supermarket",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Al Suwais Supermarket",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Al Suwais Supermarket.png",
            "Merchant Website": null,
            "Subcategory Name": "Supermarket"
        },
        "23560a66-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8955"
            "Carbon Footprint": null,
            "Category ID": "4005",
            "Category Name": "Other shopping",
            "Clean Description": "duty free dfs",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Beirut Duty Free Shops",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Beirut Duty-Free Shops.png",
            "Merchant Website": null,
            "Subcategory Name": "Duty free store"
        },
        "23560ac0-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8956"
            "Carbon Footprint": null,
            "Category ID": "6006",
            "Category Name": "Online activities and subscriptions",
            "Clean Description": "itunes  bill",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes Bill",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/itunes bill.png",
            "Merchant Website": null,
            "Subcategory Name": "Online activities and subscriptions"
        },
        "23560b24-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8957"
            "Carbon Footprint": null,
            "Category ID": "6006",
            "Category Name": "Online activities and subscriptions",
            "Clean Description": "itunes  bill",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes Bill",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/itunes bill.png",
            "Merchant Website": null,
            "Subcategory Name": "Online activities and subscriptions"
        },
        "23560b88-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8958"
            "Carbon Footprint": null,
            "Category ID": "5002",
            "Category Name": "Vehicle purchase, maintenance",
            "Clean Description": "Tensai Tuning Auto Wor",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Tensai",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Tensai.png",
            "Merchant Website": null,
            "Subcategory Name": "Auto tune up service"
        },
        "23560be2-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8959"
            "Carbon Footprint": null,
            "Category ID": "9002",
            "Category Name": "Online services",
            "Clean Description": "Google Services",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Google",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/google_logos/Google.png",
            "Merchant Website": null,
            "Subcategory Name": "Online services"
        },
        "23560c3c-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8960"
            "Carbon Footprint": null,
            "Category ID": "2005",
            "Category Name": "Telephone and internet",
            "Clean Description": "Etisalat Eshop Atg",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Etisalat",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Etisalat.png",
            "Merchant Website": null,
            "Subcategory Name": "Telephone and internet"
        },
        "23560c96-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8961"
            "Carbon Footprint": null,
            "Category ID": "2005",
            "Category Name": "Telephone and internet",
            "Clean Description": "Etisalat eshop",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Etisalat",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Etisalat.png",
            "Merchant Website": null,
            "Subcategory Name": "Telephone and internet"
        }
    }
}

Batch Retrieval Demo

Batch Retrieval Demo Video

Last updated