Getting started with Tapix
Welcome to Tapix - a simple REST API ecosystem designed to provide detailed data about card transactions or bank transfers. You can easily transform your raw payment data into a merchant name, logo, its postal address, GPS coordinates, URL, or Google Place ID.
In the following lines you will learn the ins and outs of Tapix in areas such as the terminology, data structure, technical details and where to head next.
This guide covers the standard API version and does not apply to the Tapix Lite API version.
So let's dive into it!
What can Tapix help you with
Tapix helps you enrich card payment, transfer, and other payment data for additional information about the merchant and shop. Let’s take the example that your user makes a purchase in a Tesco supermarket in Slavia, Prague 10. But all the information you get from card associations is:
- identifier of the terminal within the shop (e.g. 832216, in Tapix terminology named posId)
- the merchant identifier (e.g. 180520062, in Tapix terminology named merchantId)
- simple description of the merchant (e.g. TESCO PRAHA EDEN)
- city where the payment happened, if applicable
- country where the payment took place, if applicable
- MCC (merchant category code) which is a four-digit code that describes the category of the merchant's business
Luckily for you, this information is often enough for Tapix to provide you with more information such as the exact shop address, GPS location, logo, Google Places ID, rough categorization and additional tags that bring detailed insight on the type of goods or services that the shop provides.
Keep in mind that the more information provided the better the results.
How it works in a nutshell
Tapix API is designed with aim to provide enrichment data with minimum intervention into your infrastructure while keeping full data control up to you. Once payment is created and raw payment data are stored in your database all you need to do is to call Tapix API to obtain a link between raw data and the shop. Once data are enriched and stored. You have access to it under your control and you can freely build required use cases and move them across your systems.
Terminology and data structures
In Tapix, for every request you send us, we return as much information as possible.
We distinguish between many specific levels of information for which you will receive different data you can use in your application.
Merchant
Merchants are the owners of the shops such as Tesco, Shell, Amazon, or your local convenience store. Merchants own one or more shops.
For this level you receive merchant's exact name and their high resolution up-to-date logo that is ready for use in a circular as well as regular square frame.
Specific merchants are referred to under a specific merchant.uid from responses at the shop level.
Shop
Shops, either physical or online, have at least one POS terminal or payment gateway. In other words, for a merchant with multiple shops, this refers to the specific one where your user has made a purchase or transferred money to. An ATM is also considered a shop.
At the shop level you find all the information about the shop - namely, address, GPS location, Google Places ID, whether it is an online shop or a physical one, website URL, merchant's category and tags for detailed categorization.
Every shop has at least one POS terminal, payment gateway, or represents a bank account of the merchant.
Specific shops are referred to under a specific shop.uid from responses on transaction or transfer level.
POS terminal or payment gateway
POS terminals or payment gateways have a specific identifier unique to them and the shop itself. These terminals always belong to a specific shop.
Specific shop handles are referred to under a specific handle from responses on transaction or transfer level.
To better understand these concepts, have a look at this visual representation below.
Thus, enriched data to each payment is combination of an information about the merchant and the shop
Handle
There is a special word in Tapix terminology - a handle. Handles are used to ease working with invalidations (a mechanism used to refresh outdated enrichment information), breaking transactions, transfers and payments related to a single shop into smaller and more manageable pieces / batches - meaning that one shop may have several handles. These batches, identified by handles, are easier to keep up to date.
Payments and data sources
In Tapix we distinguish between two main types of payment flows - namely card transactions and bank transfers. You can have direct data access to both of them or via Open data interface. Let's have a look at each of the options and see how to use Tapix in each case.
Card transactions
Card transactions are the money transfers that happen when you move money around using your credit or debit card. These transactions always happen on a POS terminal or an online payment gateway. To learn how to integrate APIs that enrich data of transactions, head to Enrich card payment data tutorial for more information.
Bank transfers
Bank transfers on the other hand happen when you transfer money from one bank account to another using, for example, internet banking.
Note that different countries use different standards of bank transfers - for example Great Britain, Austria and Czech Republic all use a different system for bank transfers. To learn how to integrate APIs that enrich data of bank transfers, head to Enrich bank transfer data tutorial for more information.
Other payment methods
Tapix is able to enrich also other types of payments following local standards. Contact us to learn more about possibility to enrich data for a particular standard.
Data received through Open Data providers
You may have access to payment data (e.g. through a PSD2 AISP licence) from a different subject (e.g. bank or a fintech). Data arriving in this manner can be essentially anything, a card payment or a transfer to a bank account. These data are often in different formats from the data available directly to banks, and often some fields are missing, thus requiring a different approach when identifying data.
Always check with Dateio about missing parameters in order to make sure the quality of the service is not harmed and continuously improves. If any parameters are missing please contact support@tapix.io.
If you want to integrate APIs that enrich data from Open Data providers, head to Enrich Open Data tutorial.
The picture below shows what endpoints to use for each of your specific use cases, whether it is enriching data about payments or transfers in your databases, or data coming through Open Data.
API sequence - 3-API-calls
Tapix provides data in structured way which also minimises data flows. Therefore all aforementioned endpoints provide you with a shop.uid instead of all information about the payment. In order to get missing enrichment information about shop / merchant you need to call /shop/{shop.uid} / /merchant/{merchant.uid} endpoints. Don't worry you need to call these endpoints only if information about the shop or merchant is missing in your database.
To learn more about data structure and API head to our documentation where we will go through the best practices for working with Tapix API.
Using Tapix API
Tapix API is designed to be used for various use cases starting from improvement of customer experience in your client applications to analytical purposes. Thus, the ideal is to enrich data as soon as you load them to your DWH / database and keep the enrichment data in your database from which data can be shared with other systems within your organization. However, calling Tapix directly from front-ends for instant usage is also possible.
Keeping data up-to-date
In case any data change in Tapix - such as an address being added or some information having been incorrectly mapped (for example when the shop moves the terminals from a closed shop to a newly open one) - we provide you with a mechanism to update the information in your systems.
This system is called invalidations and it is not necessary to use it, but it is highly recommended. We will go through it in Data update mechanism tutorial.
Technical details
No matter how tech savvy you are, you should go through our documentation in order to avoid problems with integration in the future. There you will learn about caching, security and API versioning.