POST "/transaction"

To have a smooth and simple integration, while also benefiting from any future product we will be releasing, Zizy implemented only one API endpoint which handles all products in one place.

Enrich transaction

Enrich transactions, identify user subscriptions, track CO2 emissions

POST https://api.zizy.io/transaction

Processes transaction data.

Headers

Name	Type	Description
x-api-key*	string	The API Key used to authenticate the request

Request Body

Name	Type	Description
merchant_name*	string	The merchant name or description
merchant_city	string	The city of the merchant
merchant_country	string	The country of the merchant
merchant_category_code	string	The MCC of the transaction
merchant_zip_code	string	The postal code of the merchant
merchant_address	string	The address of the merchant
merchant_additional_data	string	Wildcard field for any other data regarding the merchant
transaction_type*	string	The type of transaction; Available fields: CARD_TRANSACTION or BANK_TRANSFER
transaction_timestamp	string	The UTC timestamp of the transaction
transaction_id	string	The id of the transaction as it is in your own database
transaction_amount	number	The amount of the transaction
transaction_currency	string	The currency from the transaction
transaction_reference_text	string	The reference text of the transaction. Only for bank transfers.
transaction_additional_data	string	Wildcard field for any other data regarding the transaction
user_id	string	The id of the user making the transaction
account_id	string	The id of the account of the user
card_id	string	The id of the card of the user

200: OK Transaction successfully enriched

{
    "visual_enrichments": {
        "merchant_clean_name": "Amazon",
        "merchant_logo_link": "https://storage.googleapis.com/zizy_feeds/1194.png",
        "merchant_category": "Shopping"
    },
    "subscriptions": {
        "is_recurring": false
    },
    "co2_footprint": {
        "emissions": "241"
    }
}

401: Unauthorized Unauthorized

{
    "error": "Unauthorized"
}

400: Bad Request Request failed due to providing bad input

{
    "error": "Wrong request body"
}

Response fields explained

When subscribed to all products, the API response will be similar to the one below.

{
    "visual_enrichments": {
        "merchant_clean_name": string,
        "merchant_logo_link": string,
        "merchant_category": string,
        "merchant_website": string,
        "google_places_id": string
    },
    "merchant_location": {
        "enabled": boolean,
        "address": {
            "street": string,
            "city": string,
            "zip_code": string,
            "country": string
        },
        "coordinates": {
            "lat": number,
            "lon": number
        }
    },
    "subscriptions": {
        "enabled": boolean,
        "is_recurring": boolean
    },
    "co2_footprint": {
        "enabled": boolean,
        "emissions": string
    }
}

Visual Enrichments - Response Breakdown

For a successful response when all fields are being returned, the JSON would be similar to the one below:

{
    "visual_enrichments": {
        "merchant_clean_name": "Amazon",
        "merchant_logo_link": "https://storage.googleapis.com/zizy_feeds/1194.png",
        "merchant_category": "General",
        "merchant_website": "www.amazon.com",
        "google_places_id": "123456789"
    }
}

However, there are cases when the merchant has no online presence, and no google place id. For this example, we could have something such as:

{
    "visual_enrichments": {
        "merchant_clean_name": "NOT_FOUND",
        "merchant_logo_link": "NOT_FOUND",
        "merchant_category": "NOT_FOUND",
        "merchant_website": "NOT_FOUND",
        "google_places_id": "NOT_FOUND"
    }
}

Keep in mind, there are cases when we may return data for some fields, as well as "NOT_FOUND" for the others. We are always working to improve our algorithm, however, there are times when transaction data is not reliable enough and the results are not accurate.

Subscriptions - Response Breakdown

We are tracking every transaction and should we identify one as being a recurring one (i.e.: possible subscription), we will return the following response:

{
    "subscriptions": {
        "enabled": true,
        "is_recurring": true
    }
}

In case the subscription is not available for you, we would return the following:

{
    "subscriptions": {
        "enabled": false
    }
}

CO2 footprint - Response Breakdown

Our algorithm is calculating the quantity of carbon emissions (grams) for each transaction.

{
     "co2_footprint": {
          "enabled": true,
          "emissions": "241"
    }
}

Should there be no availabilty for the emission for a certain transaction, the response would look something like:

{
     "co2_footprint": {
          "enabled": true
    }
}

Merchant location - Response Breakdown

For location we return not only the address (street and number, zip code, city and country) but also the coordinates (lat, long).

    "merchant_location": {
        "enabled": true,
        "address": {
            "street": "Kurfürstendamm 26",
            "city": "Berlin",
            "zip_code": "10719",
            "country": "Germany"
        },
        "coordinates": {
            "lat": 52.5035478,
            "lon": 13.328715
        }
    }

If any field is not available, we will return NOT_FOUND

    "merchant_location": {
        "enabled": true,
        "address": {
            "street": "NOT_FOUND",
            "city": "Berlin",
            "zip_code": "NOT_FOUND",
            "country": "Germany"
        },
        "coordinates": {
            "lat": "NOT_FOUND",
            "lon": "NOT_FOUND"
        }
    },