Before you begin with this guide, you should have the basic knowledge from Getting started with Tapix tutorial.
In this guide you will learn how to integrate Tapix APIs to enrich your payment data coming from card transactions. This use case is the most common one since most transactions in the B2C segment stem from card payments done by users. However, the data provided by card associations are not structured and clean enough for direct usage.
To learn what input data is required, and its ideal structure used to enrich the card payment data – refer to this link
For every transaction you will have to use an API to get information about shop.uid. For this use case you have four different endpoints you can use:
/shops/findByCardTransaction/shops/findByCardTransactionBatch/shops/complete/findByCardTransaction/shops/complete/findByCardTransactionBatchGET /shops/findByCardTransaction
POST /shops/findByCardTransactionBatch
GET /shops/complete/findByCardTransaction
POST /shops/complete/findByCardTransactionBatch
The first mentioned endpoint is optimal for testing but can also be used for real-time enrichment of transaction data.
The latter is recommended to use in the high load production environment, however, implementation is up to you. For example, you can batch your data and call this end point every few seconds, every minute, or when you reach the limit of objects in the query (such implementation borders with real-time data enrichment and decreases load of the infrastructure significantly).
Keep in mind that /shops/findByCardTransactionBatch is limited to 500 request entries (objects) in a batch.
For each endpoint there are many parameters you can use. Head to documentationto get the full grasp of what parameters you can use.
Note that for these endpoints you should never cache requests nor responses!
Note that in case any parameter has an empty value (null or empty string), still send it as a parameter with an empty value. Contrary, if you do not have access to a parameter omit this parameter completely in your requests. 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 just want to try the API out, find the cURL option next to the API request in the documentation. Keep in mind you have to be registered for the testing.
For purposes of this guide, we will be working with the context of GET endpoint /shops/findByCardTransaction. Analogically you can use the batch endpoint, with the only difference being that the parameters being sent are in a JSON object.
Please note that whenever the record is invalidated through invalidations, you should take the appropriate action given the level and type. After that you should call the respective endpoint for the transactions previously mapped to the invalidated records, with a parameter refresh = true.
You can also use sandbox with samples from this guide or try the API on your own.
In an ideal world you should provide as much information as possible. The query, in such case, should look something like this:
/v6/shops/findByCardTransaction?posId=820014&merchantId=180520001&description=TESC0%20PRAHA%20ZLICIN%20PRAHA%20CZ&city=PRAHA&country=CZ&refresh=false
Response to such query should look like this:
{
"result": "found",
"handle": "$QI5aQQ4AZmZxQn2iuvc5qz",
"shop": {
"uid": "MmPdedgnvjXiRZnBJzJQKb"
}
}You can also use sandbox with samples from this guide or try the API on your own.
As you can see, you successfully retrieved information necessary to proceed with getting information about the shop. To learn more, head to the Get shop and merchant information tutorial.
Sometimes you may find yourself in a situation where you don't have all the information needed or Tapix just does not know the correct answer.
Note that providing the most data possible is the way to success. You can attempt to get information using only posId or merchantId, but the results can be affected and incomplete. 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.
A shop can still be found by using only certain set of parameters.
Tapix offers a wide variety of parameters you can work with to find a shop. You don't always have all of the parameters available and thus using only a certain set of information is the only way to go with. Luckily, even with limited information about the payment you are very likely to find what you are looking for (this might be affected by the market coverage).
For example, sometimes all you have is posId and merchantId. Your query would in such case look like this:
/v6/shops/findByCardTransaction?posId=820014&merchantId=180520001&refresh=false
And the response should look like this:
{
"result": "found",
"handle": "$0GG5ILs2p6icZ5ymBSqbSV",
"shop": {
"uid": "MmPdedgnvjXiRZnBJzJQKb"
}
}As you can see, the shop was still found and thus you can proceed to the next step - Get shop and merchant information tutorial. Keep in mind that you should always use all the information you have and which Tapix supports.
You can also use sandbox with samples from this guide or try the API on your own.
Other times you may encounter that the information you provide is not enough to find the respective shop or we don’t have the data yet. Such as for this query:
/v6/shops/findByCardTransaction?merchantId=1290076&refresh=false
Your response would look like this:
{
"result": "unsolved",
"handle": "!fw7yqVlsjo5lEy0RIjT9sj"
}Notice that in this situation we still return HTTP status 200.
Unfortunately, in such cases we cannot provide any information about the shop because the data provided in the request are not sufficient.
Here you have to store the handle anyway as Tapix will refer to it once it knows the correct shop.
You can also use sandbox with samples from this guide or try the API on your own.
In this scenario, even though you provide all the information, you may still receive an unsolved shop in the response. Depending on the market you operate in, this case may be more or less common (new markets have lower coverage contrary to established ones).
Such a query that might lead you to this point could be the following:
/v6/shops/findByCardTransaction?posId=G2NPC638&merchantId=203000126287
The response would look like this:
{
"result": "unsolved",
"handle": "!JHHBYs3RAJZmUvoi34STug"
}Here you have to store the handle anyway as Tapix will refer to it, once it knows the correct shop
You can also use sandbox with samples from this guide or try the API on your own.
Other times you may encounter a different handle and shop.uid in the response. In most cases, handle equals shop.uid - but that doesn't apply every time. You can learn more about handles in Getting started with Tapix tutorial . But back to the use case - such a result would give you this query:
/v6/shops/findByCardTransaction?posId=G2NPC638&merchantId=380203000126286
The response looks like this:
{
"result": "found",
"handle": "$oKg9txIqa51el4nzCTiRgI",
"shop": {
"uid": "2DDWo50Y9XQUGVy5eVjAaY"
}
}In this case you might think you face a puzzle - fear not though. We recommend storing the handle for further possible invalidations (so you do not have to invalidate that many transactions) and use a shop for working with data internally which gives you accurate information about shops of the merchant (looking at handles would lead you to an impression that there are much more shops than is true).
You can also use sandbox with samples from this guide or try the API on your own.
The next step is getting information about shops and merchants which you learn about in Get shop and merchant information tutorial. You can learn more about integrating invalidations which serve to keep your data up-to-date. You can also integrate and enrich Open Data payments or enrich bank transfer transactions for additional data.