API Store

Production and Sandbox Endpoints

Production and Sandbox URLs:

Description

  <a href="/tapix-original-doc/tapix_api_v5_samples.postman_collection.json" class="postman-collection" download>Download Postman Collection</a> Transform card transaction's or bank transfer's raw data into structured and human understandable data. # How to use TapiX is a simple REST API designed to provide detailed data about places where any card transaction or bank transfer happened. You can easily transform your raw data into a merchant name, logo, its postal address, GPS coordinates, URL, or Google Place ID. Call API for every transaction / transfer and store results internally. If anything changes (information gets updated, extended) we let you know via invalidation framework. In order to try TapiX out via cURL you must acquire access token. You can find your own access token in <a href="/myaccount">My account</a> after you <a href="/login">log in</a>. In case you do not have an account yet, please <a href="/register">register here</a>. Contact [email protected] to get the full TapiX URL. ## Data Content Data in request / response body always use JSON. Camel case notation is used for all parameter and attribute names. ### Request data Most card transactions are processed within the same interface which is defined by the ISO standard ISO 8353. Thus data you send to the API are standardized and follow this ISO norm. It may happen that you do not store all specified parameters in the database and cannot send them to the API. In such a case, simply omit these parameters (but do not send them as empty fields). 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 [email protected]. Please note that if some parameters do not seem relevant for you while testing the service (the API is replying correctly even when some parameters are being omitted), this may not be the case for all API calls. Always include as much information as possible for the best results. In case any parameter has an empty value (null or empty string), still send it as a parameter with an empty value. The reason for this is that empty values are correct and useful information about the payment and we need to distinguish between correctly sent empty value and “no information”. You might just not have the parameter for the specific payment, transaction, or transfer but you should always include it in your calls. Contrary, if you do not have access to a parameter, omit this parameter completely in your requests - if you do not use that field at all (you choose not to or you do not have it in your databases), you should not send the parameter at all. The URL request must be URL-Encoded (percent-encoded). ### Response data At times, the information about a shop or a merchant may be incomplete. If we do not have certain information, we do not include it in the response. Please note that it is possible that any value may not be present. We are continuously working on providing as much data, as we can. ### Data structure and API The data provision is broken down into two steps gathering information about the shop and gathering information about the merchant. Any merchant may have more shops so information shared between individual shops is part of the merchant object, shop specific information is part of the shop object. <table border="0"> <tr> <th><img src="https://pics.dateio.cz/data-structure-api.svg" width="275"/></th> </tr> </table> Depending on the source of data and type of data (bank transfer or card transaction) we distinguish various APIs for getting the shop ID. <table border="0"> <tr> <th><img src="https://pics.dateio.cz/apis-to-use.svg" width="700"/></th> </tr> </table> ### Data compression #### Request The API does not support request decompression (e.g. `Content-Encoding` HTTP header will be ignored). #### Response The API does not support response compression (e.g. `Accept-Encoding` HTTP header will be ignored). ## Examples Check out the <a href="tapix_api_v5_samples">examples</a> to see TapiX in use. # Technical details ## Caching ### Request caching Caching of requests of transactions or payments (i.e. not calling the API for every single transaction) is forbidden. It would make it impossible to provide high data quality and improve service quality in time. Caching requests for shops and merchants is allowed and recommended. ### Result caching Bear in mind that all provided data may become obsolete over time. Details about shops and merchants are not changed often and there is no need to request data for each shop uid / merchant uid after every call returning a link to them. In case you implement invalidations (`/invalidations`) you can cache the results of endpoints `/shops/{id}` and `/merchants/{id}` until they get invalidated. If you choose not to implement invalidations, cache the results for only a limited time (no longer than a week) and then again, recall the API for shops and merchants you are using. ## Availability TapiX is fast and reliable. It can handle heavy loads. It works in a high availability mode. ## Security TapiX API is available only through HTTPS (TLS 1.2+), hence all the traffic is encrypted. All API endpoints are secured by **OAuth 2.0** (`client credentials`, i.e. `application` flow) or alternatively by **Basic-Auth**. You will get your credentials upon request. With every request you need to provide a JWT access token or authenticate by HTTP Basic-Auth. ### OAuth 2.0 A JWT access token can be retrieved by performing the `client credentials` (i.e. `application`) flow. To do so, you need to authenticate using `clientId` and `clientSecret` by sending a HTTP request to a token url (`POST <tapixURL>/auth/protocol/openid-connect/token`). Example: ``` curl --request POST \ --url '<tapixURL>/auth/protocol/openid-connect/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id=<your clientId> \ --data client_secret=<your clientSecret> ``` The retrieved JWT access token has a lifetime of 5 minutes (300 seconds) and has to be provided with every request to API in `Authorization` header that contains the `Bearer` word followed by a space and an access token (e.g. `Authorization: Bearer <token>`). OAuth 2.0 is safe, robust and recommended for backend-to-backend traffic. ### Basic authentication Provide your username and password with every request in the `Authorization` header that contains the `Basic` word followed by a space and a base64-encoded string `username:password` (e.g. `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`). This simple authentication comes in handy when calling the API manually. ## Versioning TapiX API is versioned, currently running in version 5 with all the older versions still being fully supported as long as they are used. You need not worry about the older version being shut down. The API version is always included in the URI. Example: `<tapixURL>/v5/` ## Environments Test environment is used only on special occasions, we will grant you access upon request. Testing typically happens in the production environment using testing credentials. Production - `<tapixURL>` In case you do not have your credentials yet, fill in the register form to claim yours. ## Migration guide ### v4 → v5 #### `/shops/findBy*` * Response field `uid` has been renamed to `handle`. It represents an identifier of the reference between the transaction and the find result. * New response field `shop` represents a nested object and contains the identifier (`uid`) of the found shop. #### `/invalidations/item/range` * New API endpoint to get a numeric ID range of all items invalidated from the moment it is provided in the parameters. #### `/invalidations` * API now works with the numeric IDs of the invalidated items and provides a pagination feature. * Removed parameter `from`. * New parameter `fromId` defines the start ID (exclusive) of the invalidated items to be returned. * New parameter `toId` defines the end ID (inclusive) of the invalidated items to be returned. * New parameter `level` represents the comma separated set of levels to be included in the response. * New parameter `pageSize` defines the maximum number of items to be returned. * Response property `uids` of the nested `batches[*]` object has been renamed to `ids`. * Response fields `currentTime` and `batches` have been moved into the nested `data` object. * New response field `paging` represents a nested object and contains the information about the current result page. ## HTTP status codes `200` (Success) - the query was successful and the response contains the data `400` (Error) - bad input `401` (Error) - unauthorized access `403` (Error) - forbidden `404` (Error) - not found `405` (Error) - method not allowed `415` (Error) - unsupported media type `501` (Error) - not implemented `5xx` (Error) - server error, please report to us ## HTTP headers Every request has to contain your credentials to access, as well as the desired format of data. In order to successfully access the API, you will always have to have `Authorization` and `Accept` correctly set up in headers. * For OAuth2 use `Authorization: Bearer <token>` * For Basic-Auth use `Authorization: Basic <base64(username:password)>` * For Accept usually use `Accept: application/json`

Business Information

Business Owner : Marián Bačák [[email protected]]

Technical Owner : Pavel Kahle [[email protected]]

Comments