general
Errors
The API can return multiple errors for any operation, each having its meaning and usage.
Error attributes
error_class
string
The class of the error, one of the listed below
error_message
string
A message describing the error
request
object
The body of the request that caused the error
error_class
string
The class of the error, one of the listed below
error_message
string
A message describing the error
request
object
The body of the request that caused the error
Error codes
[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
Sample response
{
"error_class": "BatchSizeLimitExceeded",
"error_message": "Batch size limit (100 transactions) was exceeded."
}
List
ActionNotAllowed
The client has no access to the required route
BatchSizeLimitExceeded
More than 100 objects were sent in the request (100 is the limit)
CategorizationLimitReached
One client can categorize at most 1000 transactions per day
ClientDisabled
The client has been disabled. You can find out more about the disabled status on Disabled guides page
ClientNotFound
The API key used in the request does not belong to a client
InternalServerError
An internal error has occurred
JsonParseError
We have received some other request format instead of JSON, or the body could not be parsed
WrongRequestFormat
The JSON request is incorrectly formed
ActionNotAllowed
The client has no access to the required route
BatchSizeLimitExceeded
More than 100 objects were sent in the request (100 is the limit)
CategorizationLimitReached
One client can categorize at most 1000 transactions per day
ClientDisabled
The client has been disabled. You can find out more about the disabled status on Disabled guides page
ClientNotFound
The API key used in the request does not belong to a client
InternalServerError
An internal error has occurred
JsonParseError
We have received some other request format instead of JSON, or the body could not be parsed
WrongRequestFormat
The JSON request is incorrectly formed
api
Transaction Categorization
Salt Edge API uses an algorithm for automatic categorization of transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.
There are 2 types of categories: personal categories and business categories, which help to categorize transactions, made by physical persons or legal entities.
The categories are represented as strings.
They are structured as parent and child categories, which can be identified by the tree structure sent in the Listing categories request.
How to use
By default transactions are categorized, using the list of personal categories , via parameter categorization set on routes: logins #create, #refresh, #reconnect or tokens #create, #refresh, #reconnect, as you need.
We also expose an API route for your applications to improve the categorization process based on your user’s behaviors.
List
You can get the list of all the categories that we support.
The API can return multiple categories for any operation, each having its meaning. The categories are 2 types:
- Business Categories
- Personal Categories
Possible Errors
URL
https://www.saltedge.com/api/v4/categories
https://www.saltedge.com/api/v4/categories
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/categoriescurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/categoriesSample Response
{
"data": {
"business": {
"cost_of_goods": [
"raw_materials",
"merchandise"
],
"financials": [
"dividends",
"donations",
"interest",
"fees",
"fines"
],
"human_resources": [
"wages",
"bonus",
"social_security",
"education_and_trainings",
"staff_outsourcing"
],
"income": [
"investment",
"sales",
"returns"
],
"insurance": [
"business_insurance",
"liability_insurance",
"health_insurance",
"equipment_insurance",
"professional_insurance"
],
"office": [
"office_rent",
"equipment",
"software",
"office_supplies"
],
"services": [
"contractors",
"accounting",
"legal",
"consultancy",
"storage",
"marketing",
"online_subscriptions"
],
"taxes": [
"vat",
"federal_taxes",
"property_taxes",
"income_taxes",
"duty_taxes",
"tax_return"
],
"transport": [
"shipping",
"leasing",
"gas_and_fuel",
"taxi"
],
"uncategorized": [],
"utilities": [
"internet",
"phone",
"water",
"gas",
"electricity"
]
},
"personal": {
"auto_and_transport": [
"car_rental",
"gas_and_fuel",
"parking",
"public_transportation",
"service_and_parts",
"taxi"
],
"bills_and_utilities": [
"internet",
"phone",
"television",
"utilities"
],
"business_services": [
"advertising",
"office_supplies",
"shipping"
],
"education": [
"books_and_supplies",
"student_loan",
"tuition"
],
"entertainment": [
"amusement",
"arts",
"games",
"movies_and_music",
"newspapers_and_magazines"
],
"fees_and_charges": [
"provider_fee",
"loans",
"service_fee",
"taxes"
],
"food_and_dining": [
"alcohol_and_bars",
"cafes_and_restaurants",
"groceries"
],
"gifts_and_donations": [
"charity",
"gifts"
],
"health_and_fitness": [
"doctor",
"personal_care",
"pharmacy",
"sports",
"wellness"
],
"home": [
"home_improvement",
"home_services",
"home_supplies",
"mortgage_and_rent"
],
"income": [
"bonus",
"investment_income",
"paycheck"
],
"insurance": [
"car_insurance",
"health_insurance",
"life_insurance",
"property_insurance"
],
"kids": [
"allowance",
"babysitter_and_daycare",
"baby_supplies",
"child_support",
"kids_activities",
"toys"
],
"pets": [
"pet_food_and_supplies",
"pet_grooming",
"veterinary"
],
"shopping": [
"clothing",
"electronics_and_software",
"sporting_goods"
],
"transfer": [],
"travel": [
"hotel",
"transportation",
"vacation"
],
"uncategorized": []
}
}
}
Business
Business Categories include:
cost_of_goods
Refers to equipment and materials intended for consumption in the production process
raw_materials
Raw materials, as wood, textil, glass, plastic
merchandise
Various consumer goods
financials
Covers company’s financial operations
dividends
Sums of money paid by companies to their shareholders
donations
Gifts made to a nonprofit organization, charity, private foundation
interest
Interests paid or received
fees
Financial institutions fees
fines
Local council fines, traffic offences, other offences
human_resources
Used for transactions, linked to human resources issues and includes subcategories:
wages
Paychecks, wages
bonus
Bonuses, rewards added to wages for good performance
social_security
Various types of non-wage compensation provided to employees
education_and_trainings
Training providers, educational institutions, learning centers, learning apps
staff_outsourcing
Outsourcing of specialists from different domains: manufacturing, HR, accounting, developers; project-based outsourcing
income
Covers different types of income and includes subcategories:
investment
Money investments to investment funds, saving deposits, mutual funds
sales
Sales income
returns
Sales returns, online orders returns
insurance
Implies deals with insurance companies
business_insurance
Business insurance; business interruption insurance
liability_insurance
Liability insurance
health_insurance
Health insurance medical plans
equipment_insurance
Inventory insurance, furniture insurance, tools insurance
professional_insurance
Professional liability insurance policies, civil liability insurance
office
Implies products and services for office
office_rent
Rental of a property used for business purposes
equipment
Equipment and materials, used by a company
software
Any software or set of computer programs
office_supplies
Stationery, office supplies, printing paper
services
Implies miscellaneous services for business
contractors
Services delivered by contractors
accounting
Accounting, auditing, bookkeeping services
legal
Legal support services; attorneys
consultancy
Consulting services
storage
Warehousing services; goods storage
marketing
Marketing and media services; advertising
online_subscriptions
Online subscriptions, web hosting, data storage
taxes
Covers different types of taxes
vat
Value added tax
federal_taxes
Federal taxes; estate tax, gift tax
property_taxes
Property taxes; land property tax
income_taxes
Income taxes
duty_taxes
Duty taxes; taxes on imported goods
tax_return
Tax return
transport
Used for transactions, related to cars and other modes of transport
shipping
Motor freight carriers; logistics; delivery; courier services
leasing
Operational or financial leasing of transport
gas_and_fuel
Filling stations, gas, fuels, lubricants
taxi
Taxicabs; limousines; taxi apps
uncategorized
Uncategorized
utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
water
Water supplies
gas
Natural Gas supplies
electricity
Electricity, enegry supplies
cost_of_goods
Refers to equipment and materials intended for consumption in the production process
raw_materials
Raw materials, as wood, textil, glass, plastic
merchandise
Various consumer goods
financials
Covers company’s financial operations
dividends
Sums of money paid by companies to their shareholders
donations
Gifts made to a nonprofit organization, charity, private foundation
interest
Interests paid or received
fees
Financial institutions fees
fines
Local council fines, traffic offences, other offences
human_resources
Used for transactions, linked to human resources issues and includes subcategories:
wages
Paychecks, wages
bonus
Bonuses, rewards added to wages for good performance
social_security
Various types of non-wage compensation provided to employees
education_and_trainings
Training providers, educational institutions, learning centers, learning apps
staff_outsourcing
Outsourcing of specialists from different domains: manufacturing, HR, accounting, developers; project-based outsourcing
income
Covers different types of income and includes subcategories:
investment
Money investments to investment funds, saving deposits, mutual funds
sales
Sales income
returns
Sales returns, online orders returns
insurance
Implies deals with insurance companies
business_insurance
Business insurance; business interruption insurance
liability_insurance
Liability insurance
health_insurance
Health insurance medical plans
equipment_insurance
Inventory insurance, furniture insurance, tools insurance
professional_insurance
Professional liability insurance policies, civil liability insurance
office
Implies products and services for office
office_rent
Rental of a property used for business purposes
equipment
Equipment and materials, used by a company
software
Any software or set of computer programs
office_supplies
Stationery, office supplies, printing paper
services
Implies miscellaneous services for business
contractors
Services delivered by contractors
accounting
Accounting, auditing, bookkeeping services
legal
Legal support services; attorneys
consultancy
Consulting services
storage
Warehousing services; goods storage
marketing
Marketing and media services; advertising
online_subscriptions
Online subscriptions, web hosting, data storage
taxes
Covers different types of taxes
vat
Value added tax
federal_taxes
Federal taxes; estate tax, gift tax
property_taxes
Property taxes; land property tax
income_taxes
Income taxes
duty_taxes
Duty taxes; taxes on imported goods
tax_return
Tax return
transport
Used for transactions, related to cars and other modes of transport
shipping
Motor freight carriers; logistics; delivery; courier services
leasing
Operational or financial leasing of transport
gas_and_fuel
Filling stations, gas, fuels, lubricants
taxi
Taxicabs; limousines; taxi apps
uncategorized
Uncategorized
utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
water
Water supplies
gas
Natural Gas supplies
electricity
Electricity, enegry supplies
Personal
Personal Categories include:
auto_and_transport
Used for transactions, related to cars and other modes of transport
car_rental
Carsharing; car rentals; bicycle rentals
gas_and_fuel
Filling stations, gas, fuels, lubricants
parking
Parking spaces; parking apps
public_transportation
Public transportation of passengers; bus lines, train, metro
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
taxi
Taxicabs; limousines; taxi apps
bills_and_utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
television
Cable, satellite and other television services
utilities
Water, electricity, natural gas, heating, garbage disposal
business_services
Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design
advertising
Outdoor adverstisig; digital ads; social media marketing
office_supplies
Stationery, office supplies, printing paper
shipping
Logistics and delivery; courier services
education
Applied for transactions with colleges, universities, schools, learning centers
books_and_supplies
Books, periodicals, eBook apps, e-readers
student_loan
Student loans
tuition
Tuition grants and scholarships; tuition fees
entertainment
Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters
amusement
Amusement parks
arts
Art dealers, art galleries
games
Video games, gambling, betting, casinos, lotteries
movies_and_music
Movie streaming services, audio streaming platforms, radio, cinemas and music festivals
newspapers_and_magazines
Newspapers, magazines and their distributors
fees_and_charges
Covers fees and charges
provider_fee
Banking fees
loans
Money lending
service_fee
Photo studio services; laundry; repairs and restoration
taxes
Different types of taxes, as income taxes, property taxes
food_and_dining
Applied for transactions related to food and beverage products, dining, catering
alcohol_and_bars
Alcohol sellers, bars, pubs, nightclubs
cafes_and_restaurants
Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
groceries
Grocery stores, supermarkets
gifts_and_donations
Refers to gifts and donations
charity
Donations, charitable services
gifts
Greetings cards, gift and souvenir shops
health_and_fitness
Covers goods and services for the maintenance or improvement of health and well-being
doctor
Hospitals; dental clinics; medical services
personal_care
Personal hygiene and beautification
pharmacy
Drugstores products, medicaments
sports
Sportclubs, gyms, fitness centers, swimming pools
wellness
Beauty spas; hair services; nail salons; massage parlors
home
Applied for household goods, services for building or maintenance of houses
home_improvement
Furniture, interior design services, improvements to outdoor structures
home_services
Home maintenance and repair, cleaning, laundry, ironing
home_supplies
Building materials, household hardware, cookware, domestic appliances
mortgage_and_rent
Real estate purchases and rentals, estate sale, mortgage loans
income
Covers different types of earnings
bonus
Bonuses, rewards, cashback
investment_income
Capital gains, dividends, interest
paycheck
Salaries, wages
insurance
Implies deals with insurance companies
car_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
health_insurance
Health insurance medical plans
life_insurance
Life insurance
property_insurance
Fire, theft and some weather damage property insurance
kids
Includes various child care activities
allowance
Child allowance
babysitter_and_daycare
Babysitting, kids daycare services
baby_supplies
Baby products, baby food
child_support
Child support
kids_activities
Amusement parks for kids, theme parks for kids
toys
Different types of toys
pets
Refers to pet stores, animal care
pet_food_and_supplies
Products and food for pets
pet_grooming
Pet grooming services
veterinary
Pet health care including veterinary clinics, pharmacies
shopping
Covers shopping malls, e-commerce marketplaces, retail of particular goods
clothing
Clothing, shoes, jewelry, sunglasses
electronics_and_software
Electronics, software, hardware, computers
sporting_goods
Equipment that completes the sport, as gym clothing, motorcycle gear
transfer
Includes money transfers; ATM cash withdrawals
travel
Covers travelling, travel agencies, tourism, excursions
hotel
Accommodation, hotels, motels, resorts
transportation
Air transportation, yachts
vacation
Holiday companies, specific trips or journies
uncategorized
Uncategorized
auto_and_transport
Used for transactions, related to cars and other modes of transport
car_rental
Carsharing; car rentals; bicycle rentals
gas_and_fuel
Filling stations, gas, fuels, lubricants
parking
Parking spaces; parking apps
public_transportation
Public transportation of passengers; bus lines, train, metro
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
taxi
Taxicabs; limousines; taxi apps
bills_and_utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
television
Cable, satellite and other television services
utilities
Water, electricity, natural gas, heating, garbage disposal
business_services
Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design
advertising
Outdoor adverstisig; digital ads; social media marketing
office_supplies
Stationery, office supplies, printing paper
shipping
Logistics and delivery; courier services
education
Applied for transactions with colleges, universities, schools, learning centers
books_and_supplies
Books, periodicals, eBook apps, e-readers
student_loan
Student loans
tuition
Tuition grants and scholarships; tuition fees
entertainment
Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters
amusement
Amusement parks
arts
Art dealers, art galleries
games
Video games, gambling, betting, casinos, lotteries
movies_and_music
Movie streaming services, audio streaming platforms, radio, cinemas and music festivals
newspapers_and_magazines
Newspapers, magazines and their distributors
fees_and_charges
Covers fees and charges
provider_fee
Banking fees
loans
Money lending
service_fee
Photo studio services; laundry; repairs and restoration
taxes
Different types of taxes, as income taxes, property taxes
food_and_dining
Applied for transactions related to food and beverage products, dining, catering
alcohol_and_bars
Alcohol sellers, bars, pubs, nightclubs
cafes_and_restaurants
Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
groceries
Grocery stores, supermarkets
gifts_and_donations
Refers to gifts and donations
charity
Donations, charitable services
gifts
Greetings cards, gift and souvenir shops
health_and_fitness
Covers goods and services for the maintenance or improvement of health and well-being
doctor
Hospitals; dental clinics; medical services
personal_care
Personal hygiene and beautification
pharmacy
Drugstores products, medicaments
sports
Sportclubs, gyms, fitness centers, swimming pools
wellness
Beauty spas; hair services; nail salons; massage parlors
home
Applied for household goods, services for building or maintenance of houses
home_improvement
Furniture, interior design services, improvements to outdoor structures
home_services
Home maintenance and repair, cleaning, laundry, ironing
home_supplies
Building materials, household hardware, cookware, domestic appliances
mortgage_and_rent
Real estate purchases and rentals, estate sale, mortgage loans
income
Covers different types of earnings
bonus
Bonuses, rewards, cashback
investment_income
Capital gains, dividends, interest
paycheck
Salaries, wages
insurance
Implies deals with insurance companies
car_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
health_insurance
Health insurance medical plans
life_insurance
Life insurance
property_insurance
Fire, theft and some weather damage property insurance
kids
Includes various child care activities
allowance
Child allowance
babysitter_and_daycare
Babysitting, kids daycare services
baby_supplies
Baby products, baby food
child_support
Child support
kids_activities
Amusement parks for kids, theme parks for kids
toys
Different types of toys
pets
Refers to pet stores, animal care
pet_food_and_supplies
Products and food for pets
pet_grooming
Pet grooming services
veterinary
Pet health care including veterinary clinics, pharmacies
shopping
Covers shopping malls, e-commerce marketplaces, retail of particular goods
clothing
Clothing, shoes, jewelry, sunglasses
electronics_and_software
Electronics, software, hardware, computers
sporting_goods
Equipment that completes the sport, as gym clothing, motorcycle gear
transfer
Includes money transfers; ATM cash withdrawals
travel
Covers travelling, travel agencies, tourism, excursions
hotel
Accommodation, hotels, motels, resorts
transportation
Air transportation, yachts
vacation
Holiday companies, specific trips or journies
uncategorized
Uncategorized
Learn
You can change the category of some transactions, thus improving the categorization accuracy.
Custom category will be applicable only for customer’s new transactions, which have similar description. It will be located in transaction extra as customer_category_code or customer_category_name.
Post body
transaction_id
required
The id of the transaction
category_code
required
The new category code of the transaction
immediate
boolean optional
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the same category
transaction_id
required
The id of the transaction
category_code
required
The new category code of the transaction
immediate
boolean optional
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the same category
Possible Errors
URL
https://www.saltedge.com/api/v4/categories/learn
https://www.saltedge.com/api/v4/categories/learn
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"transaction_id\": \"124\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
}" \
https://www.saltedge.com/api/v4/categories/learncurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"transaction_id\": \"124\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
}" \
https://www.saltedge.com/api/v4/categories/learnSample Response
{
"data": {
"learned": true
}
}
Transaction Enrichment
Categorizes your transactions by the given parameters.
Request body
The request body is an array of objects wrapped in the data field.
Each object has a description, currency_code and identifier fields.
The API accepts batches of at most 100 objects.
Parameters
description
string, required
The description which you wish to categorize (max 4000 chars)
action
string, optional
Learn - will create or update a rule, remove - will remove a previous created rule. Note: category is required when action is learn
additional
string
Additional information (recommended to use in concatenation with original description, if present)
amount
decimal, optional
The amount of the transaction
categorization
string, optional
The type of categorization applied. Possible values: none, personal, business. Default: personal
category
string, optional
The new category code for the description, used with action: learn
country_code
string, optional
The code of the country, present in Salt Edge API
currency_code
string, optional
The code of the currency, present in Salt Edge API
identifier
string, optional
A unique identifier of the transaction object (max 255 chars).
identify_merchant
boolean, optional
Whether merchant identification was enabled
information
text, optional
Information about the transaction
mode
string, optional
Possible values are: normal, fee, transfer
original_category
string, optional
The original category of the transaction
original_subcategory
string, optional
The original subcategory of the transaction
payee
string, optional
To whom money is paid
status
string, optional
Possible values are: posted, pending
tags
array of strings, optional
The original tags of the transaction
description
string, required
The description which you wish to categorize (max 4000 chars)
action
string, optional
Learn - will create or update a rule, remove - will remove a previous created rule. Note: category is required when action is learn
additional
string
Additional information (recommended to use in concatenation with original description, if present)
amount
decimal, optional
The amount of the transaction
categorization
string, optional
The type of categorization applied. Possible values: none, personal, business. Default: personal
category
string, optional
The new category code for the description, used with action: learn
country_code
string, optional
The code of the country, present in Salt Edge API
currency_code
string, optional
The code of the currency, present in Salt Edge API
identifier
string, optional
A unique identifier of the transaction object (max 255 chars).
identify_merchant
boolean, optional
Whether merchant identification was enabled
information
text, optional
Information about the transaction
mode
string, optional
Possible values are: normal, fee, transfer
original_category
string, optional
The original category of the transaction
original_subcategory
string, optional
The original subcategory of the transaction
payee
string, optional
To whom money is paid
status
string, optional
Possible values are: posted, pending
tags
array of strings, optional
The original tags of the transaction
Note: Custom categories will be located in transaction’s extra, see: customer_category_code and customer_category_name
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions/categorize
https://www.saltedge.com/api/v4/transactions/categorize
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"description\": \"Amazon\", \
\"action\": \"learn\", \
\"category\": \"Online shopping\" \
}, \
{ \
\"description\": \"Tesco\", \
\"action\": \"remove\" \
}, \
{ \
\"description\": \"Itunes\", \
\"currency_code\": \"USD\", \
\"identifier\": \"d5bb8cf037aa7f069\" \
}, \
{ \
\"description\": \"Ebay\", \
\"country_code\": \"US\", \
\"amount\": 100 \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/categorizecurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"description\": \"Amazon\", \
\"action\": \"learn\", \
\"category\": \"Online shopping\" \
}, \
{ \
\"description\": \"Tesco\", \
\"action\": \"remove\" \
}, \
{ \
\"description\": \"Itunes\", \
\"currency_code\": \"USD\", \
\"identifier\": \"d5bb8cf037aa7f069\" \
}, \
{ \
\"description\": \"Ebay\", \
\"country_code\": \"US\", \
\"amount\": 100 \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/categorizeSample Response
{
"data": [
{
"description": "Itunes",
"identifier": "d5bb8cf037aa7f069",
"currency_code": "USD",
"category": "electronics_and_software",
"made_on": "2016-08-16",
"amount": 1,
"mode": "normal",
"status": "posted",
"extra": {}
},
{
"description": "",
"identifier": null,
"currency_code": "EUR",
"category": "uncategorized",
"made_on": "2016-08-16",
"amount": 1,
"mode": "normal",
"status": "posted",
"extra": {},
"errors": [
"Description can't be blank"
]
}
]
}
Merchants Identification
Merchant represents a company, that sells goods or provides services to the Customer.Identification
Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.
This option is country based and currently is available in 17 countries - UK, Ireland, Italy, Netherlands, Germany, Czech Republic, Austria, Hungary, Poland, Romania, Latvia, Spain, Portugal, Australia, Russia, India, Singapore and the list will continue to grow.
Also, you can test it, using the fakebank_simple_xf provider, available for the fake XF country.
How to use
To start using this option, all you need to do is:
- pass
identify_merchant: trueon logins #create, #refresh, #reconnect or tokens #create, #refresh, #reconnect. When the login creation succeeds and only if the merchant is identified, you will receive amerchant_idin theextrafield of the transaction; - send all the
merchant_idsyou want to fetch the additional info for, to merchants.
Also, you can test it, using the fakebank_simple_xf provider, available for the fake XF country.
Show
To fetch the name and additional info, available for identified merchants, pass the desired merchant_ids in an array to route https://www.saltedge.com/api/v4/merchants.
Please note, that the first priority of this feature is to identify merchant name, that’s why arrays with name and transliterated_name are always presented.
Sometimes, in transaction’s descriptional fields, can be presented additional information about merchant, as: shop number, or address of sale point, with city, post code and street numbers. In this case, it’s possible to identify the exact place, where the Customer’s transaction was done. If we found point of sale, corresponding to transaction, in our database, we can return more granular information with contact and address details, including geo-coordinates.
The API accepts batches of at most 100 objects.
Attributes
id
string
Merchant id
names
array of objects
Merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: name, transliterated_name, alternative_name, brand, operator
address
object
Merchant address may include the next location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, as building_name, shop_number and so on.
contact
array of objects
Contact information, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube
id
string
Merchant id
names
array of objects
Merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: name, transliterated_name, alternative_name, brand, operator
address
object
Merchant address may include the next location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, as building_name, shop_number and so on.
contact
array of objects
Contact information, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube
Possible Errors
URL
https://www.saltedge.com/api/v4/merchants
https://www.saltedge.com/api/v4/merchants
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v4/merchantscurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v4/merchantsSample Response
{
"data": [
{
"id": "f6dabf8bb3e1cbc7cce2f4571...",
"names": [
{
"mode": "name",
"value": "Amazon"
},
{
"mode": "transliterated_name",
"value": "amazon"
}
],
"contact": [
{
"mode": "website",
"value": "www.amazon.com"
}
],
"address": {
"country_code": "GB"
}
},
{
"id": "ae316a83508ecaa8897e90321...",
"names": [
{
"mode": "name",
"value": "Boots"
},
{
"mode": "transliterated_name",
"value": "boots"
},
{
"mode": "operator",
"value": "Boots Uk Limited"
}
],
"contact": [
{
"mode": "phone",
"value": "+44 20 73818651"
},
{
"mode": "website",
"value": "http://www.boots.com/stores/773-london-fulham-palace-road-w6-9pa"
}
],
"address": {
"country_code": "GB",
"city": "London",
"transliterated_city": "london",
"street": "Fulham Palace Road",
"transliterated_street": "fulham palace road",
"post_code": "W6 9Pa",
"coordinates": {
"latitude": "51.48467107",
"longitude": "-0.220126411"
},
"extra": {
"building_number": "198-200",
"shop_number": "773",
"type_of_shop": "Chemist"
}
}
}
]
}