swagger: '2.0' info: description: |   Download OpenAPI specification Download Postman Collection Transform card transaction's or bank transfer's raw data into structured and human understandable data. Start by reading the Tapix tech intro guide. # 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 My account after you log in. In case you do not have an account yet, please register here. Contact support@tapix.io 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 8583. 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 support@tapix.io. 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.

Refer to this link to see an example of ideally structured Request data and Response Data in the format that works best with Tapix API

### 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.
Depending on the source of data and type of data (bank transfer or card transaction) we distinguish various APIs for getting the shop ID.
### Tapix Lite Accounts using the Tapix Lite API version will receive reduced data on bank transfers, open data and shops in the response. For example, bank uid, other categories, any tags, location, URL and Google Place ID of the shop will not be included. ### 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 sandbox 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. The Tapix API has a timeout period of 300 seconds, which ensures that a response will always be provided within 300 seconds or less. If the application is unable to generate a response within this timeframe, a timeout error will be returned. ## 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). You will get your credentials upon request. With every request you need to provide a JWT access token. ### 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 /auth/realms/tapix-prod/protocol/openid-connect/token`). Example: ``` curl --request POST \ --url '/auth/realms/tapix-prod/protocol/openid-connect/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id= \ --data client_secret= ``` 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 `). There is a rate limit for obtaining a token: you can request a new token a maximum of 100 times per 5 minutes. OAuth 2.0 is safe, robust and recommended for backend-to-backend traffic.

JWT access token can be found in the Developer portal under in My account page, below username.

The URL for the origin in postman, will be provided upon request.

## Versioning Tapix API is versioned, currently running in version 6 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: `/v6/` ## Environments and Credentials The test environment is used only on special occasions. We can grant you access upon request. Testing typically happens in the production environment using testing credentials. The production environment is used for all development, testing and production activity. Production - `` Both test and production credentials point to the production environment. Test credentials are reasonably limited and are to be used for all development / testing activities. Production credentials are to be used for all production activities. ## Migration guide ### v5 → v6 #### `/*` * Basic authentication is deprecated and no longer supported, please consider using OAuth 2.0. #### `/shops/{id}` * `Handle` is no longer supported as value for {id}. Use the `uid` of the shop as the only acceptable value for {id}. * Response property `uid` can now be up to 100 characters long. * New response field `category` represents the category of the shop. * New response field `otherCategories` not directly related to merchant's field of business. * New response field `otherTags` related to `otherCategories`. * The `location.coordinates` response property now includes a new field `type`, representing the accuracy level of the coordinates. * The `location.coordinates` response property now includes a new field `zoom`, representing the zoom level for displaying provided coordinates on a map using Mercator projection. #### `/merchants/{id}` * Response property `uid` can now be up to 100 characters long. * Response property `category` has been removed. #### `/shops/findBy*` * Response property `handle` can now be up to 100 characters long. * Response property `uid` of the nested `shop` object can now be up to 100 characters long. #### `/shops/findByCardTransaction*` * Parameter `cardId` has been renamed to `sourceId`. #### `/shops/complete/findBy*` * New response field `category` of the nested `shop` object represents the category of the shop. * Response property `category` of the nested `shop.merchant` object has been removed. #### `/shops/complete/findByCardTransaction*` * Parameter `cardId` has been renamed to `sourceId`. #### `/banks/{id}` * New API endpoint to get information about the bank. #### `/shops/findByBankTransfer*` * New response field `bank` represents a nested object that contains identifier of the bank `uid`. #### `/shops/complete/findByBankTransfer*` * New response field `bank` represents a nested object that contains identifier of the bank `uid`. #### `/shops/findByOpenDataTransaction*` * New response field `bank` represents a nested object that contains identifier of the bank `uid`. #### `/shops/complete/findByOpenDataTransaction*` * New response field `bank` represents a nested object that contains identifier of the bank `uid`. #### `/atms/complete/findNearby` * New API endpoint to find ATMs by GPS coordinates. ### HTTP headers * New response header `X-Request-ID` is now included in every API request to speed up and simplify the process of resolving claims and reporting errors. ## 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 `429` (Error) - API rate limit exceeded, please slow down your requests `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 OAuth 2.0 use `Authorization: Bearer ` * For Accept usually use `Accept: application/json` Each API request is assigned a unique request identifier. This value can be found in the response header `X-Request-ID` of every request. To speed up and facilitate the process of resolving complaints and bug-reports, please include the request identifier when contacting us about a specific issue. version: 6.0.0 title: Tapix host: / basePath: / tags: - name: Shops description: 'All about stores, e-shops and any other points of sale.' - name: ATMs description: 'All about ATMs. This feature is not enabled by default and can be activated upon request.' - name: Merchants description: 'Merchants are shop owners. Each shop has a single merchant who operates it.

Start with our guide on getting shop and merchant information.' - name: Banks - name: Payment Gateways - name: Invalidations description: 'Start with our guide on how to keep your data up-to-date.

Banks are recommended to invalidate only the transactions from the past 12 months

List all invalidated objects in a given time period' - name: Feedback description: 'Report improvements and corrections. Learn how to use this endpoint in our short guide.' - name: Suggestions description: '

Deprecated. Use the Feedback endpoint instead.

Report improvements and corrections.' - name: Health description: 'Health and status monitoring.' schemes: - https securityDefinitions: oAuth2ClientCredentials: type: oauth2 flow: application tokenUrl: /auth/realms/tapix-prod/protocol/openid-connect/token scopes: user: default scope, optional description: '

JWT access token can be found in the Developer portal under in My account page, below username.

The URL for the origin in postman, will be provided upon request.

' security: - oAuth2ClientCredentials: [] paths: /v6/shops/findByCardTransaction: get: tags: - Shops summary: Find shop by raw transactional data description: | Start with our guide on how to enrich card payment data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if you do not have access to a parameter omit this parameter completely in your requests.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated at some later time (using `/invalidations`). If the shop is found, then its uid is also returned.
**Caching**: Never. operationId: findByCardTransaction produces: - application/json parameters: - name: description in: query description: | necessary

ISO 8583 Field 43 - Card acceptor name / location (1-23 address). Case-insensitive.
Example: TESCO PRAHA ZLICIN type: string - name: merchantId in: query description: | very important

ISO 8583 Field 42 - Card acceptor identification code. Case-insensitive.
Example: 820014 type: string - name: posId in: query description: | very important

ISO 8583 Field 41 - Card acceptor terminal identification. Point-of-sale ID. Card acceptor (merchant) terminal identifier. Case-insensitive.
Example: 18052001 type: string - name: city in: query description: | very important

ISO 8583 Field 43 - Card acceptor name / location (24-36 city). Case-insensitive.
Example: PRAHA type: string - name: country in: query description: | very important

ISO 8583 Field 43 - Card acceptor name / location (39-40 country). Format is defined in ISO 3166-1 alpha-2. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable. Case-insensitive.
Please make sure NOT to just trim the ISO 3166-1 alpha-3 country code to 2 letters!
Example: CZ type: string - name: mcc in: query description: | very important

Merchant category code. ISO 8583 Field 18 - Merchant type.
Note: any non-numeric value will be ignored.
Example: 5411 type: string - name: transactionTimestamp in: query description: | important

Transaction timestamp. Date and time, local transaction. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. If you want to provide information about the date only, without the precise time, use field ignoreTime = true.
Example: 2018-09-19T11:16:36+00:00 type: string format: date-time - name: sourceId in: query description: | important

Randomised number or hash used as a stable identifier linking transactions from the same card / mobile app.
Example: B7T1533692247A type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: ecommerceFlag in: query description: | good to have

ISO 8583 Field 25 - Point of service condition code. True - E-Commerce, false - Physical Payment.
Example: true type: boolean - name: channelCode in: query description: | good to have

"ATM" - Cash Withdrawal (Bankomat), "POS" - Card Payment.
Example: POS type: string - name: zip in: query description: | good to have

ZIP code of location.
Example: 36001 type: string - name: state in: query description: | good to have

ISO 8583 Field 43 - Card acceptor name / location (37-38 state). Case-insensitive.
Example: CO type: string - name: acquirerId in: query description: | good to have

Acquiring institution identification code. ISO 8583 Field 32 Format N…11 (LLVAR).
type: string - name: address in: query description: | good to have

Address of the place. Provided when some information is available (e.g. from own acquiring).
Example: Praha, Vinohradská 2842/104 type: string - name: pairingId in: query description: | good to have

Unique identifier which must be used to group all requests based on a single card transaction. Something like hashed transaction-id may be used. A typical use-case is calling Tapix in the payment authorization phase (in time of customer's payment at the point-of-sale) and afterwards in the settlement phase (minutes / hours / days later). Another use-case is calling Tapix after data invalidation when data of previously processed transactions is refreshed.
Example: 4078296076 type: string - name: acquirerCountryCode in: query description: | good to have

Code of the country where the acquirer is located. ISO 8583 Field 19 Format specified by ISO 3166.
type: string - name: posEntryMode in: query description: | good to have

ISO 8583 Field 22 - Identifier of the method used to obtain the PAN.
Example: 10 type: string - name: posTransactionStatusIndicator in: query description: | good to have

ISO 8583 Field 60.6 - Identifier of the POS Transaction Status Indicator.
Example: R type: string - name: ecommerceIndicator in: query description: | good to have

ISO 8583 Field 126 - Identifier of the Electronic Commerce/MOTO (Mail Order/Telephone Order) Indicator.
Example: 02 type: string - name: associationName in: query description: | optional

Name of card association.
Example: MASTERCARD type: string - name: ignoreTime in: query description: | optional

Set to true, if time from transactionTimestamp should be ignored (however, date will be used).
Example: true type: boolean - name: gpsLat in: query description: | optional

GPS coordinates of the place - latitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 50.049689 type: number format: double - name: gpsLong in: query description: | optional

GPS coordinates of the place - longitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 14.294543 type: number format: double - name: rawParams in: query description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it.
type: string - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithPaymentGatewayAndCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByCardTransaction?posId=820014&merchantId=180520001&description=TESC0%20PRAHA%20ZLICIN%20PRAHA%20CZ&city=PRAHA&country=CZ&mcc=5411"' /v6/shops/findByCardTransactionBatch: post: tags: - Shops summary: Find shops by raw transactional data batch description: | Start with our guide on how to enrich card payment data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if you do not have access to a parameter omit this parameter completely in your requests.
Shop handle is always returned for every request. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.
**Caching**: Never. operationId: findByCardTransactionBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw transactional data.
schema: $ref: '#/definitions/RequestTXBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndPaymentGatewayAndCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"posId": "18052001","merchantId": "820014","description": "TESCO PRAHA ZLICIN","city": "PRAHA","zip": "36001","country": "CZ","mcc": "5411","channelCode": "POS","ecommerceFlag": true,"associationName": "MASTERCARD","acquirerId": "1234567","acquirerCountryCode": "string","transactionTimestamp": "2018-09-19T11:16:36+00:00","ignoreTime": true,"sourceId": "B7T1533692247A","gpsLat": 50.049689,"gpsLong": 14.294543,"address": "Praha, Vinohradská 2842/104","rawParams": "string","pairingId": "4078296076","refresh": true,"customId": "X11FfTr4ma"}]}'' "${TapixURL}/v6/shops/findByCardTransactionBatch"' /v6/shops/complete/findByCardTransaction: get: tags: - Shops summary: Find shop by raw transactional data - complete response description: | Start with our guide on how to enrich card payment data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if you do not have access to a parameter omit this parameter completely in your requests.
If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
**Caching**: Never. operationId: findByCardTransactionComplete produces: - application/json parameters: - name: description in: query description: | necessary

ISO 8583 Field 43 - Card acceptor name / location (1-23 address). Case-insensitive.
Example: TESCO PRAHA ZLICIN type: string - name: merchantId in: query description: | very important

ISO 8583 Field 42 - Card acceptor identification code. Case-insensitive.
Example: 820014 type: string - name: posId in: query description: | very important

ISO 8583 Field 41 - Card acceptor terminal identification. Point-of-sale ID. Card acceptor (merchant) terminal identifier. Case-insensitive.
Example: 18052001 type: string - name: city in: query description: | very important

ISO 8583 Field 43 - Card acceptor name / location (24-36 city). Case-insensitive.
Example: PRAHA type: string - name: country in: query description: | very important

ISO 8583 Field 43 - Card acceptor name / location (39-40 country). Format is defined in ISO 3166-1 alpha-2. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable. Case-insensitive.
Please make sure NOT to just trim the ISO 3166-1 alpha-3 country code to 2 letters!
Example: CZ type: string - name: mcc in: query description: | very important

Merchant category code. ISO 8583 Field 18 - Merchant type.
Note: any non-numeric value will be ignored.
Example: 5411 type: string - name: transactionTimestamp in: query description: | important

Transaction timestamp. Date and time, local transaction. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. If you want to provide information about the date only, without the precise time, use field ignoreTime = true.
Example: 2018-09-19T11:16:36+00:00 type: string format: date-time - name: sourceId in: query description: | important

Randomised number or hash used as a stable identifier linking transactions from the same card / mobile app.
Example: B7T1533692247A type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: ecommerceFlag in: query description: | good to have

ISO 8583 Field 25 - Point of service condition code. True - E-Commerce, false - Physical Payment.
Example: true type: boolean - name: channelCode in: query description: | good to have

"ATM" - Cash Withdrawal (Bankomat), "POS" - Card Payment.
Example: POS type: string - name: zip in: query description: | good to have

ZIP code of location.
Example: 36001 type: string - name: state in: query description: | good to have

ISO 8583 Field 43 - Card acceptor name / location (37-38 state). Case-insensitive.
Example: CO type: string - name: acquirerId in: query description: | good to have

Acquiring institution identification code. ISO 8583 Field 32 Format N…11 (LLVAR).
type: string - name: address in: query description: | good to have

Address of the place. Provided when some information is available (e.g. from own acquiring).
Example: Praha, Vinohradská 2842/104 type: string - name: pairingId in: query description: | good to have

Unique identifier which must be used to group all requests based on a single card transaction. Something like hashed transaction-id may be used. A typical use-case is calling Tapix in the payment authorization phase (in time of customer's payment at the point-of-sale) and afterwards in the settlement phase (minutes / hours / days later). Another use-case is calling Tapix after data invalidation when data of previously processed transactions is refreshed.
Example: 4078296076 type: string - name: acquirerCountryCode in: query description: | good to have

Code of the country where the acquirer is located. ISO 8583 Field 19 Format specified by ISO 3166.
type: string - name: posEntryMode in: query description: | good to have

ISO 8583 Field 22 - Identifier of the method used to obtain the PAN.
Example: 10 type: string - name: posTransactionStatusIndicator in: query description: | good to have

ISO 8583 Field 60.6 - Identifier of the POS Transaction Status Indicator.
Example: R type: string - name: ecommerceIndicator in: query description: | good to have

ISO 8583 Field 126 - Identifier of the Electronic Commerce/MOTO (Mail Order/Telephone Order) Indicator.
Example: 02 type: string - name: associationName in: query description: | optional

Name of card association.
Example: MASTERCARD type: string - name: ignoreTime in: query description: | optional

Set to true, if time from transactionTimestamp should be ignored (however, date will be used).
Example: true type: boolean - name: gpsLat in: query description: | optional

GPS coordinates of the place - latitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 50.049689 type: number format: double - name: gpsLong in: query description: | optional

GPS coordinates of the place - longitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 14.294543 type: number format: double - name: rawParams in: query description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it.
type: string - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithCO2FootprintComplete' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/complete/findByCardTransaction?posId=820014&merchantId=180520001&description=TESC0%20PRAHA%20ZLICIN%20PRAHA%20CZ&city=PRAHA&country=CZ&mcc=5411"' /v6/shops/complete/findByCardTransactionBatch: post: tags: - Shops summary: Find shops by raw transactional data batch - complete response description: | Start with our guide on how to enrich card payment data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if you do not have access to a parameter omit this parameter completely in your requests.
If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 250 entries per request.
**Caching**: Never. operationId: findByCardTransactionBatchComplete consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw transactional data.
schema: $ref: '#/definitions/RequestTXBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndCO2FootprintComplete' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"posId": "18052001","merchantId": "820014","description": "TESCO PRAHA ZLICIN","city": "PRAHA","zip": "36001","country": "CZ","mcc": "5411","channelCode": "POS","ecommerceFlag": true,"associationName": "MASTERCARD","acquirerId": "1234567","acquirerCountryCode": "string","transactionTimestamp": "2018-09-19T11:16:36+00:00","ignoreTime": true,"sourceId": "B7T1533692247A","gpsLat": 50.049689,"gpsLong": 14.294543,"address": "Praha, Vinohradská 2842/104","rawParams": "string","pairingId": "4078296076","refresh": true,"customId": "X11FfTr4ma"}]}'' "${TapixURL}/v6/shops/complete/findByCardTransactionBatch"' /v6/shops/findByOpenDataTransaction: post: tags: - Shops summary: Find shop by open data description: | Start with our guide on how to enrich open data. The transactional data is provided in a custom format which is agreed upon beforehand between you and us.

To start enriching open data such as PSD2, we need you to send us a sample of all combinations of banks and data sources that you have in your database – i.e. (HSBC-Saltedge, HSBC-TrueLayer Erste-Saltedge). We will analyze them and once the parser will be ready on our end, we will inform you about our readiness for automatized enrichment over the API. To start this process, send your data samples to datasupport@dateio.eu.

The shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated at some later time (using `/invalidations`). If the shop is found, then its uid is also returned.

**Caching**: Never. operationId: findByOpenDataTransaction consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing the raw transactional data.
schema: $ref: '#/definitions/RequestCTX' responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2Footprint' '400': description: 'Invalid input or empty request' '501': description: 'Format is not yet supported, or provided data can not be processed yet' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"data": {"description": "STARBUCKS, LONDON 2022-02-02 10 GBP","other": {"note": "caffe americano","city": "London","country": "GB","type": "card payment","category": "cafe"}},"bank": "HSBC","source": "Saltedge","refresh": true}'' "${TapixURL}/v6/shops/findByOpenDataTransaction"' /v6/shops/findByOpenDataTransactionBatch: post: tags: - Shops summary: Find shops by open data batch description: | Start with our guide on how to enrich open data. The transactional data is provided in a custom format which is agreed upon beforehand between you and us.

To start enriching open data such as PSD2, we need you to send us a sample of all combinations of banks and data sources that you have in your database – i.e. (HSBC-Saltedge, HSBC-TrueLayer Erste-Saltedge). We will analyze them and once the parser will be ready on our end, we will inform you about our readiness for automatized enrichment over the API. To start this process, send your data samples to datasupport@dateio.eu.

The shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated at some later time (using `/invalidations`). If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.
**Caching**: Never. operationId: findByOpenDataTransactionBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw transactional data.
schema: $ref: '#/definitions/RequestCTXBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2Footprint' '400': description: 'Invalid input or empty request' '501': description: 'Format of one of the requests from the batch is not yet supported, or the data provided cannot yet be processed' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"data": {"description": "STARBUCKS, LONDON 2022-02-02 10 GBP","other": {"note": "caffe americano","city": "London","country": "GB","type": "card payment","category": "cafe"}},"bank": "HSBC","source": "Saltedge","refresh": true}]}'' "${TapixURL}/v6/shops/findByOpenDataTransactionBatch"' /v6/shops/complete/findByOpenDataTransaction: post: tags: - Shops summary: Find shop by open data - complete response description: | Start with our guide on how to enrich open data. The transactional data is provided in a custom format which is agreed upon beforehand between you and us.

To start enriching open data such as PSD2, we need you to send us a sample of all combinations of banks and data sources that you have in your database – i.e. (HSBC-Saltedge, HSBC-TrueLayer Erste-Saltedge). We will analyze them and once the parser will be ready on our end, we will inform you about our readiness for automatized enrichment over the API. To start this process, send your data samples to datasupport@dateio.eu.

If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
**Caching**: Never. operationId: findByOpenDataTransactionComplete consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing the raw transactional data.
schema: $ref: '#/definitions/RequestCTX' responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2FootprintComplete' '400': description: 'Invalid input or empty request' '501': description: 'Format is not yet supported, or provided data can not be processed yet' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"data": {"description": "STARBUCKS, LONDON 2022-02-02 10 GBP","other": {"note": "caffe americano","city": "London","country": "GB","type": "card payment","category": "cafe"}},"bank": "HSBC","source": "Saltedge","refresh": true}'' "${TapixURL}/v6/shops/complete/findByOpenDataTransaction"' /v6/shops/complete/findByOpenDataTransactionBatch: post: tags: - Shops summary: Find shops by open data batch - complete response description: | Start with our guide on how to enrich open data. The transactional data is provided in a custom format which is agreed upon beforehand between you and us.

To start enriching open data such as PSD2, we need you to send us a sample of all combinations of banks and data sources that you have in your database – i.e. (HSBC-Saltedge, HSBC-TrueLayer Erste-Saltedge). We will analyze them and once the parser will be ready on our end, we will inform you about our readiness for automatized enrichment over the API. To start this process, send your data samples to datasupport@dateio.eu.

If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 250 entries per request.
**Caching**: Never. operationId: findByOpenDataTransactionBatchComplete consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw transactional data.
schema: $ref: '#/definitions/RequestCTXBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2FootprintComplete' '400': description: 'Invalid input or empty request' '501': description: 'Format of one of the requests from the batch is not yet supported, or the data provided cannot yet be processed' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"data": {"description": "STARBUCKS, LONDON 2022-02-02 10 GBP","other": {"note": "caffe americano","city": "London","country": "GB","type": "card payment","category": "cafe"}},"bank": "HSBC","source": "Saltedge","refresh": true}]}'' "${TapixURL}/v6/shops/complete/findByOpenDataTransactionBatch"' /v6/shops/findByBankTransfer/certis: get: tags: - Shops summary: Find shop by raw data of CERTIS bank transfer description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated at some later time (using `/invalidations`). If the shop is found, then its uid is also returned.

**Caching**: Possible and recommended. * Cache key: All request parameters except these: `refresh`, `aggCount`. * Cache value: Complete Tapix response and processed transfers counter. * Cache invalidation: Based on `GET /invalidations` - all cache records containing invalidated handle (in the cache value) must be discarded. * Cache statistics delivery: In order to keep Tapix fresh and smart, it needs to know how the real-world data looks. So, Tapix must be periodically (every 1-7 days) informed about how many real bank transfers has been processed by every item of the cache. It shall be done by calling Tapix with the parameters filled according to the cache key plus additional `aggCount` parameter containing the number of processed transfers since the last call. The same must be done for every cache record upon its removal from the cache (e.g. when invalidation occurs). operationId: findByBankTransferCertis produces: - application/json parameters: - name: accountNumber in: query description: | necessary

The counterpart's (national) bank account number. Format specified in Annex 1 to the Rules of the CERTIS Payment System (10n, the leading zeros may be omitted).
Example: 4159 type: string - name: accountNumberPrefix in: query description: | necessary

The prefix of the counterpart's (national) bank account number. Format specified in Annex 1 to the Rules of the CERTIS Payment System (6n, the leading zeros may be omitted).
Example: 178124 type: string - name: bankCode in: query description: | necessary

Counterpart's national bank code assigned by a central bank, a bank supervisory body or a Bankers Association in a country to all its licensed member banks or financial institutions.
Example: 0710 type: string - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: accountName in: query description: | important

The name of the counterpart's account.
Example: Béďa Trávníček type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: variableSymbol in: query description: | good to have

A variable symbol is used by beneficiary to make identifying a payment simpler especially when many payments are remitted to its account.
Example: 9 type: string - name: specificSymbol in: query description: | good to have

A specific symbol is used to identify a payment. Helps to classify a payment for your invoice, for instance.
Example: 100011 type: string - name: constantSymbol in: query description: | good to have

A constant symbol is non-obligatory payment data solely used for classifying payments.
Example: 0558 type: string - name: message in: query description: | optional

Additional information or message for counterpart.
Example: PREVOD PROSTREDKU type: string - name: note in: query description: | optional

Additional information or note.
Example: WAGE 889Vd6 type: string - name: aggCount in: query description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 type: integer - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS - name: nextPaymentDate in: query type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 - name: recurrenceType in: query type: string description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] - name: paymentTimestamp in: query type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input (wrong account identifier format) or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByBankTransfer/certis?accountNumber=188505042&bankCode=0300&accountName=ALZA.CZ%20A.S.&paymentType=O&message=INVOICE%20PAYMENT¬e=LAPTOP"' /v6/shops/findByBankTransferBatch/certis: post: tags: - Shops summary: Find shops by raw data of CERTIS bank transfer batch description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned for every request. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.

**Caching**: Possible and recommended (see the non-batch version of the endpoint for more details). operationId: findByBankTransferCertisBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw CERTIS bank transfer data.
schema: $ref: '#/definitions/RequestCertisTransferBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"accountNumber": "188505042","bankCode": "0300","accountName": "ALZA.CZ A.S.","paymentType": "O","message": "INVOICE PAYMENT","note": "LAPTOP","customId": "Y22GgUs5nb"}]}'' "${TapixURL}/v6/shops/findByBankTransferBatch/certis"' /v6/shops/findByBankTransfer/sepa: get: tags: - Shops summary: Find shop by raw data of SEPA bank transfer description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.

**Caching**: Possible and recommended. * Cache key: All request parameters except these: `refresh`, `aggCount`. * Cache value: Complete Tapix response and processed transfers counter. * Cache invalidation: Based on `GET /invalidations` - all cache records containing invalidated handle (in the cache value) must be discarded. * Cache statistics delivery: In order to keep Tapix fresh and smart, it needs to know how the real-world data looks. So, Tapix must be periodically (every 1-7 days) informed about how many real bank transfers has been processed by every item of the cache. It shall be done by calling Tapix with the parameters filled according to the cache key plus additional `aggCount` parameter containing the number of processed transfers since the last call. The same must be done for every cache record upon its removal from the cache (e.g. when invalidation occurs). operationId: findByBankTransferSepa produces: - application/json parameters: - name: iban in: query description: | necessary

ISO 13616 - The International Bank Account Number of the counterpart.
Example: BG18RZBB91550123456789 type: string - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: bic in: query description: | important

ISO 9362 - Counterpart's bank code in international format.
Example: AIRACZPP type: string - name: name in: query description: | important

The raw name/description of the recipient counterpart.
Example: 15. přední hlídka Royal Rangers Mariánské Lázně type: string - name: remittanceInfo in: query description: | important

ISO 20022 – Remittance Information. Free-text payment reference provided by the originator to the beneficiary.
Example: Invoice 2023/09 #4581 type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: city in: query description: | optional

The city of the counterpart.
Example: PRAHA type: string - name: zip in: query description: | optional

The postal (ZIP) code of the counterpart.
Example: 36001 type: string - name: postalAddress in: query description: | optional

The specific postal address of the counterpart.
Example: CZ, JUNGMANNOVA 1, PRAHA 1, 110 00 type: string - name: country in: query description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: CZ type: string - name: rawParams in: query description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it.
type: string - name: aggCount in: query description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 type: integer - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS - name: nextPaymentDate in: query type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 - name: recurrenceType in: query type: string description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] - name: paymentScheme in: query type: string description: | important

The specific payment method or local overlay used within the SEPA network. This differentiates between standard credit transfers and regional sub-variants or specialized European payment brands such as iDeal, WERO, Bizum or BLIK.
Example: WERO - name: paymentTimestamp in: query type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByBankTransfer/sepa?bic=CHASGB2LXXX&iban=GB85CHAS60924241314994&paymentType=I&name=NETFLIX%20INTERNATIONAL%20B.V.&country=GB"' /v6/shops/findByBankTransferBatch/sepa: post: tags: - Shops summary: Find shops by raw data of SEPA bank transfer batch description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned for every request. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.

**Caching**: Possible and recommended (see the non-batch version of the endpoint for more details). operationId: findByBankTransferSepaBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw SEPA bank transfer data.
schema: $ref: '#/definitions/RequestSepaTransferBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"bic": "CHASGB2LXXX","iban": "GB85CHAS60924241314994","paymentType": "I","name": "NETFLIX INTERNATIONAL B.V.","country": "GB","customId": "Z33HhVt6oc"}]}'' "${TapixURL}/v6/shops/findByBankTransferBatch/sepa"' /v6/shops/complete/findByBankTransfer/sepa: get: tags: - Shops summary: Find shop by raw data of SEPA bank transfer - complete response description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
**Caching**: Never. operationId: findByBankTransferSepaComplete produces: - application/json parameters: - name: iban in: query description: | necessary

ISO 13616 - The International Bank Account Number of the counterpart.
Example: BG18RZBB91550123456789 type: string - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: bic in: query description: | important

ISO 9362 - Counterpart's bank code in international format.
Example: AIRACZPP type: string - name: name in: query description: | important

The raw name/description of the recipient counterpart.
Example: 15. přední hlídka Royal Rangers Mariánské Lázně type: string - name: remittanceInfo in: query description: | important

ISO 20022 – Remittance Information. Free-text payment reference provided by the originator to the beneficiary.
Example: Invoice 2023/09 #4581 type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: city in: query description: | optional

The city of the counterpart.
Example: PRAHA type: string - name: zip in: query description: | optional

The postal (ZIP) code of the counterpart.
Example: 36001 type: string - name: postalAddress in: query description: | optional

The specific postal address of the counterpart.
Example: CZ, JUNGMANNOVA 1, PRAHA 1, 110 00 type: string - name: country in: query description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: CZ type: string - name: rawParams in: query description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it.
type: string - name: aggCount in: query description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 type: integer - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS - name: nextPaymentDate in: query type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 - name: recurrenceType in: query type: string description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] - name: paymentScheme in: query type: string description: | important

The specific payment method or local overlay used within the SEPA network. This differentiates between standard credit transfers and regional sub-variants or specialized European payment brands such as iDeal, WERO, Bizum or BLIK.
Example: WERO - name: paymentTimestamp in: query type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscriptionComplete' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/complete/findByBankTransfer/sepa?bic=CHASGB2LXXX&iban=GB85CHAS60924241314994&paymentType=I&name=NETFLIX%20INTERNATIONAL%20B.V.&country=GB"' /v6/shops/complete/findByBankTransferBatch/sepa: post: tags: - Shops summary: Find shops by raw data of SEPA bank transfer batch - complete response description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
If the shop is found, all available information about it is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 250 entries per request.
**Caching**: Never. operationId: findByBankTransferSepaBatchComplete consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw SEPA bank transfer data.
schema: $ref: '#/definitions/RequestSepaTransferBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2FootprintAndSubscriptionComplete' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"bic": "CHASGB2LXXX","iban": "GB85CHAS60924241314994","paymentType": "I","name": "NETFLIX INTERNATIONAL B.V.","country": "GB","customId": "Z33HhVt6oc"}]}'' "${TapixURL}/v6/shops/complete/findByBankTransferBatch/sepa"' /v6/shops/findByBankTransfer/uk: get: tags: - Shops summary: Find shop by raw data of BACS / Faster Payments bank transfer description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.

**Caching**: Possible and recommended. * Cache key: All request parameters except these: `refresh`, `aggCount`. * Cache value: Complete Tapix response and processed transfers counter. * Cache invalidation: Based on `GET /invalidations` - all cache records containing invalidated handle (in the cache value) must be discarded. * Cache statistics delivery: In order to keep Tapix fresh and smart, it needs to know how the real-world data looks. So, Tapix must be periodically (every 1-7 days) informed about how many real bank transfers has been processed by every item of the cache. It shall be done by calling Tapix with the parameters filled according to the cache key plus additional `aggCount` parameter containing the number of processed transfers since the last call. The same must be done for every cache record upon its removal from the cache (e.g. when invalidation occurs). operationId: findByBankTransferUK produces: - application/json parameters: - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: sortCode in: query description: | necessary

A 6 numeric digit number without hyphens that identifies the UK institution and branch. Must be valid UK sorting code.
Example: 400515 type: string - name: accountNumber in: query description: | necessary

An 8 numeric digit number that identifies the individual customer’s clearing account at the UK institution/branch. Must be valid UK account number.
Example: 01234567 type: string - name: bankCode in: query description: | necessary

Identical to the first four characters of the counterpart bank's BIC/SWIFT code. For more info see ISO 9362. Length - 4 characters.
Example: HBUK type: string - name: paymentMethod in: query description: | important

Automated payment method. "BACS_DD" - BACS Direct Debit, "BACS_DC" - BACS Direct Credit, "FP" - Faster Payments.
Example: BACS_DD type: string enum: [BACS_DD, BACS_DC, FP] - name: name in: query description: | important

The raw name/description of the recipient counterpart. Maximum length - 18 characters.
Example: GOOGLE IRELAND type: string - name: bankName in: query description: | important

The name of the counterpart's bank. Maximum length - 35 characters.
Example: Barclays type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: GBP type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: paymentDate in: query description: | good to have

Payment date. Date, local payment. ISO . Format: YYYY-MM-DD.
Example: 2020-11-30 type: string format: date - name: paymentReference in: query description: | good to have

Details of the payment. Maximum length: 18 characters.
Example: AS4F54S564F56S4 type: string - name: city in: query description: | optional

The city of the counterpart.
Example: REDLYNCH type: string - name: zip in: query description: | optional

The postal (ZIP) code of the counterpart.
Example: BA10 1WN type: string - name: address in: query description: | optional

The specific address of the counterpart.
Example: 97 BOAT LANE type: string - name: country in: query description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: GB type: string - name: aggCount in: query description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 type: integer - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS - name: nextPaymentDate in: query type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 - name: recurrenceType in: query type: string description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] - name: paymentTimestamp in: query type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByBankTransfer/uk?paymentMethod=FP&paymentType=I&sortCode=202646&accountNumber=33443450&name=LONDON%20PAY%20LTD&paymentReference=LONDON%20PAY&country=GB"' /v6/shops/findByBankTransferBatch/uk: post: tags: - Shops summary: Find shops by raw data of BACS / Faster Payments bank transfer batch description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned for every request. It either identifies a known shop or an unsolved / unknown shop which may be updated some time later (using `/invalidations`). If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.

**Caching**: Possible and recommended (see the non-batch version of the endpoint for more details). operationId: findByBankTransferUKBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw BACS / Faster Payments bank transfer data.
schema: $ref: '#/definitions/RequestUKTransferBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndBankAndCO2FootprintAndSubscription' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"paymentMethod": "FP","paymentType": "I","sortCode": "202646","accountNumber": "33443450","name": "LONDON PAY LTD","paymentReference": "LONDON PAY","country": "GB","bankCode": "HBUK","customId": "T12FbTr3mv"}]}'' "${TapixURL}/v6/shops/findByBankTransferBatch/uk"' /v6/shops/findByBankTransfer/jopacc: get: tags: - Shops summary: Find shop by raw data of JoPACC bank transfer description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop. If the shop is found, then its uid is also returned.

**Caching**: Never. operationId: findByBankTransferJoPACC produces: - application/json parameters: - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: type in: query description: | necessary

Subcategory of the payment method.
Example: BILLS type: string - name: accountName in: query description: | important

The name of the counterpart.
Example: Cristiano Ronaldo type: string - name: billerCode in: query description: | important

Code of the biller, relevant for payments of type "BILLS".
Example: 39 type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: JOD type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: description in: query description: | good to have

Additional information or payment description.
Example: Physical card delivery fee type: string - name: purposeCode in: query description: | good to have

Purpose code of the payment.
Example: 104 type: string - name: country in: query description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: JO type: string - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS - name: nextPaymentDate in: query type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 - name: recurrenceType in: query type: string description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByBankTransfer/jopacc?accountName=Cristiano%20Ronaldo&paymentType=I&country=JO&type=BILLS&billerCode=39&description=Physical%20card%20delivery%20fee&purposeCode=104"' /v6/shops/findByBankTransfer/p2p: get: tags: - Shops summary: Find shop by raw data of person-to-person bank transfer description: | Start with our guide on how to enrich bank transfer data. Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop. If the shop is found, then its uid is also returned.

**Caching**: Never. operationId: findByBankTransferP2P produces: - application/json parameters: - name: message in: query description: | necessary

Additional information or message for counterpart.
Example: Dinner type: string - name: paymentType in: query description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I type: string enum: [I, O] - name: accountName in: query description: | important

The name of the counterpart.
Example: Cristiano Ronaldo type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: JOD type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: type in: query description: | good to have

Subcategory of the payment method.
Example: DEBIT type: string - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithBankAndCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByBankTransfer/p2p?accountName=Cristiano%20Ronaldo&message=Dinner&type=DEBIT&paymentType=I"' /v6/shops/findByQRPayment: get: tags: - Shops summary: Find shop by raw QR payment data description: | Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop. If the shop is found, then its uid is also returned.

**Caching**: Never. operationId: findByQRPayment produces: - application/json parameters: - name: merchantName in: query description: | necessary

Trade merchant name of the payee. Case-insensitive.
Example: Burger King type: string - name: storeName in: query description: | necessary

Name of the merchant's store. Case-insensitive.
Example: BK Trafalgar Square type: string - name: merchantId in: query description: | important

Merchant ID of the payee. Case-insensitive.
Example: MPL353236E21 type: string - name: storeId in: query description: | important

Store ID of the payee. Case-insensitive.
Example: MPL353566E24 type: string - name: terminalId in: query description: | important

Terminal ID of the payee. Case-insensitive.
Example: ZER387566D28 type: string - name: iban in: query description: | important

ISO 13616 - The International Bank Account Number of the payee. Case-insensitive.
Example: BG18RZBB91550123456789 type: string - name: country in: query description: | important

Merchant country. Format is defined in ISO 3166-1 alpha-2. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable. Case-insensitive.
Please make sure NOT to just trim the ISO 3166-1 alpha-3 country code to 2 letters!
Example: US type: string - name: city in: query description: | important

Merchant city - city where the QR code is located. Case-insensitive.
Example: London type: string - name: mcc in: query description: | important

Merchant category code.
Note: any non-numeric value will be ignored.
Example: 5411 type: string - name: transactionTimestamp in: query description: | important

Transaction timestamp. Date and time, local transaction. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. If you want to provide information about the date only, without the precise time, use field ignoreTime = true.
Example: 2018-09-19T11:16:36+00:00 type: string format: date-time - name: ignoreTime in: query description: | important

Set to true, if time from transactionTimestamp should be ignored (however, date will be used).
Example: true type: boolean - name: deviceId in: query description: | important

Stable identifier linking transactions from the device within few hours or a day (id can be newly generated after few hours). Case-insensitive.
Example: B7T1533692247A type: string - name: currency in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR type: string - name: amount in: query description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 type: number - name: refresh in: query description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true type: boolean - name: address in: query description: | good to have

Address of the place. Provided when some information is available. Case-insensitive.
Example: 87-135 Brompton Rd, London type: string - name: customId in: query type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. - name: clientId in: query type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/FindResultWithCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/findByQRPayment?merchantId=MPL353236E21&merchantName=Burger%20King&storeId=MPL353566E24&storeName=BK%20Trafalgar%20Square&terminalId=ZER387566D28&iban=BG18RZBB91550123456789&country=US&city=London&mcc=5411&address=87-135%20Brompton%20Rd%2C%20London&transactionTimestamp=2018-09-19T11%3A16%3A36%2B00%3A00&ignoreTime=true&deviceId=B7T1533692247A"' /v6/shops/findByQRPaymentBatch: post: tags: - Shops summary: Find shops by raw QR payment data batch description: | Notify us about missing parameters (if any) in order to make sure the quality of the service is not harmed.
If any parameter has an empty value (null or empty string) still send it as a parameter with an empty value. On the contrary, if the parameter is not available at all (e.g. the column is not present in your database table) then do not put it in the request.
Shop handle is always returned. It either identifies a known shop or an unsolved / unknown shop. If the shop is found, then its uid is also returned.
Found results in the response will have the same ordering as the individual requests in batch request.
Maximum batch size is 500 entries per request.
**Caching**: Never. operationId: findByQRPaymentBatch consumes: - application/json produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of raw QR payment data.
schema: $ref: '#/definitions/RequestQRBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: type: array items: $ref: '#/definitions/FindResultWithCustomIdAndCO2Footprint' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"requests": [{"merchantId": "MPL353236E21","merchantName": "Burger King","storeId": "MPL353566E24","storeName": "BK Trafalgar Square","terminalId": "ZER387566D28","iban": "BG18RZBB91550123456789","country": "US","city": "London","mcc": "5411","address": "87-135 Brompton Rd, London","transactionTimestamp": "2018-09-19T11:16:36+00:00","ignoreTime": true,"deviceId": "B7T1533692247A","customId": "X11FfTr4ma"}]}'' "${TapixURL}/v6/shops/findByQRPaymentBatch"' /v6/shops/{id}: get: tags: - Shops summary: Find shop by ID description: | Start with our guide on getting shop and merchant information. All available information about the shop is returned. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Shop uid should be used as input ID value.
**Caching**: May be cached and it is recommended to do so. Use the value of the `uid` field from the response as an identifier of the shop. Cache invalidation is required to keep the data fresh - there are two options:
- call `/invalidations` to get invalidated shops on the regular basis - let the records in your cache expire to allow natural refreshment. operationId: getShopById produces: - application/json parameters: - name: id in: path description: | necessary

ID (`uid`) of shop to return. Case-insensitive.
Example: MmPdedgnvjXiRZnBJzJQKb required: true type: string responses: '200': description: 'Search finished returning one shop' schema: $ref: '#/definitions/Shop' '404': description: 'No shop exists with the provided ID or it has been removed' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/shops/bed0443280d34179bf0050"' /v6/shops: post: tags: - Shops summary: Find shop by IDs Batch description: | Start with our guide on getting shop and merchant information. All available information about the shop is returned for every shop uid. If any information is missing (e.g. coordinates or postal address) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Shop uid should be used as an input ID value.
Maximum batch size is 1000 entries per request. **Caching**: May be cached and it is recommended to do so. Use the value of the `uid` field from the response as an identifier of the shop. Cache invalidation is required to keep the data fresh - there are two options:
- call `/invalidations` to get invalidated shops on the regular basis - let the records in your cache expire to allow natural refreshment. operationId: getShopsByPublicIdBatch produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of IDs (`uid`) of shops to return.
schema: $ref: '#/definitions/RequestGetShopBatch' responses: '200': description: 'Search finished returning one shop for every request' schema: $ref: '#/definitions/ShopOutputBatch' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"shops": [{"id":"MmPdedgnvjXiRZnBJzJQKb"}]}'' "${TapixURL}/v6/shops"' /v6/atms/complete/findNearby: get: tags: - ATMs summary: Find ATMs by GPS coordinates - complete response description: | Find ATMs within a specified area.
**Caching**: Never. operationId: atmsFindNearbyComplete produces: - application/json parameters: - name: lat in: query description: | necessary

Latitude of the point around which ATMs are searched.
Example: 50.049689 type: number format: double required: true - name: long in: query description: | necessary

Longitude of the point around which ATMs are searched.
Example: 14.294543 type: number format: double required: true - name: radius in: query description: | necessary

The distance in metres within which ATMs are searched. Maximum value is 100000.
Example: 5000 type: integer required: true - name: allianceOnly in: query description: | optional

If set to true, the response will only include ATMs operated by the client and their defined partners. Defaults to false (returns all ATMs).
Example: true type: boolean required: false - name: countLimit in: query description: | optional

Maximum number of ATMs that are returned. Default value is 50. Maximum value is 200.
Example: 10 type: integer required: false - name: voiceAssistant in: query description: | optional

Filters for ATMs based on the `voiceAssistant` feature. When a value is provided (`true` or `false`), the response includes ATMs that match the value, as well as ATMs where this information is unknown. type: boolean required: false - name: wheelchairAccess in: query description: | optional

Filters for ATMs based on the `wheelchairAccess` feature. When a value is provided (`true` or `false`), the response includes ATMs that match the value, as well as ATMs where this information is unknown. type: boolean required: false - name: contactless in: query description: | optional

Filters for ATMs based on the `contactless` feature. When a value is provided (`true` or `false`), the response includes ATMs that match the value, as well as ATMs where this information is unknown. type: boolean required: false - name: depositAtm in: query description: | optional

Filters for ATMs based on the `depositAtm` feature. When a value is provided (`true` or `false`), the response includes ATMs that match the value, as well as ATMs where this information is unknown. type: boolean required: false - name: openNonStop in: query description: | optional

Filters for ATMs based on the `openNonStop` feature. When a value is provided (`true` or `false`), the response includes ATMs that match the value, as well as ATMs where this information is unknown. type: boolean required: false - name: openNow in: query description: | optional

Filters for ATMs that are currently open. This feature must be enabled for your account.
When a value of `true` is provided, the response includes ATMs that are currently open, as well as ATMs where the opening hours are unknown. A value of `false` is ignored. type: boolean required: false - name: isFree in: query description: | optional

Filters for ATMs based on whether they charge a withdrawal fee. This feature must be enabled for your account. When a value is provided (`true` for free, `false` for not free), the response includes ATMs that match the status, as well as ATMs where fee information is unknown. type: boolean required: false responses: '200': description: 'Search finished returning found ATMs sorted by distance' schema: $ref: '#/definitions/FindNearbyResultsComplete' '400': description: 'Invalid input or empty request' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/atms/complete/findNearby?lat=50.049689&long=14.294543&radius=5000&countLimit=10"' /v6/merchants/{id}: get: tags: - Merchants summary: Find merchant by ID description: | All available information about the merchant is returned. If any information is missing (e.g. logo) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Merchant uid should be used as an input ID value.
**Caching**: May be cached and it is recommended to do so. Use the value of the `uid` field from the response as an identifier of the merchant. Cache invalidation is required to keep the data fresh - there are two options:
- call `/invalidations` to get invalidated merchants on the regular basis - let the records in your cache expire to allow natural refreshment. operationId: getMerchantById produces: - application/json parameters: - name: id in: path description: | necessary

ID (`uid`) of merchant to return. Case-insensitive.
Example: frephafR7zekayUzu5uxu8 required: true type: string responses: '200': description: 'Search finished returning one merchant' schema: $ref: '#/definitions/Merchant' '404': description: 'No merchant exists with the provided ID or it has been removed' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/merchants/frephafR7zekayUzu5uxu8"' /v6/merchants: post: tags: - Merchants summary: Find merchant by IDs batch description: | All available information about the merchant is returned for every merchant uid. If any information is missing (e.g. logo) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Merchant uid should be used as an input ID value.
Maximum batch size is 1000 entries per request. **Caching**: May be cached and it is recommended to do so. Use the value of the `uid` field from the response as an identifier of the merchant. Cache invalidation is required to keep the data fresh - there are two options:
- call `/invalidations` to get invalidated merchants on the regular basis - let the records in your cache expire to allow natural refreshment. operationId: getMerchantsByIdBatch produces: - application/json parameters: - name: body in: body description: | Request object containing a batch of IDs (`uid`) of merchants to return.
schema: $ref: '#/definitions/RequestGetMerchantBatch' responses: '200': description: 'Search finished returning one merchant for every request' schema: $ref: '#/definitions/MerchantOutputBatch' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"merchants": [{"id":"frephafR7zekayUzu5uxu8"}]}'' "${TapixURL}/v6/merchants"' /v6/paymentGateways/{id}: get: tags: - Payment Gateways summary: Find payment gateway by ID description: | All available information about the payment gateway is returned. If any information is missing (e.g. logo) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Payment gateway uid should be used as an input ID value.
operationId: getPaymentGatewayById produces: - application/json parameters: - name: id in: path description: | necessary

ID (`uid`) of payment gateway to return. Case-insensitive.
Example: 7nZcLG3d5HCAkmCRCT0KAm required: true type: string responses: '200': description: 'Search finished returning one payment gateway' schema: $ref: '#/definitions/PaymentGateway' '404': description: 'No payment gateway exists with the provided ID or it has been removed' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/paymentGateways/107dbd71e71a9826ccb1db"' /v6/banks/{id}: get: tags: - Banks summary: Find bank by ID description: | All available information about the bank is returned. If any information is missing (e.g. logo) the respective attributes are not included into the response. Therefore only non-empty fields are returned.
Bank uid should be used as an input ID value.
operationId: getBankById produces: - application/json parameters: - name: id in: path description: | necessary

ID (`uid`) of bank to return. Case-insensitive.
Example: 107dbd71e71a9826ccb1db required: true type: string responses: '200': description: 'Search finished returning one bank' schema: $ref: '#/definitions/Bank' '404': description: 'No bank exists with the provided ID or it has been removed' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/banks/107dbd71e71a9826ccb1db"' /v6/invalidations/item/range: get: tags: - Invalidations summary: Get a numeric ID range of the all items invalidated between given timestamps description: | Returns a numeric ID range of all items invalidated since the instant provided in `from` parameter and before the instant provided in `to` parameter.
The result contains the numeric ID of the first and the last invalidated item within the requested period of time. These values are expected to be used as the parameters in `/invalidations` service to get a list of all invalidated items within the given numeric ID range.
Please note that this endpoint `/invalidations/item/range` is not intended to be used on a regular basis, but rather to start a continuous invalidation process by getting the initial numeric id values. Further invalidations should continue in `/invalidations`.
**Caching**: Never. operationId: getInvalidationRange produces: - application/json parameters: - name: from in: query description: | necessary

Only items invalidated after this timestamp will get to the result range.
Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Examples: '2017-10-20T13:15:08Z, 2017-10-20T13:15:08+02:00' required: true type: string format: date-time - name: to in: query description: | optional

Only items invalidated before this timestamp will get to the result range.
Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Examples: '2017-11-20T13:15:08Z, 2017-11-20T13:15:08+02:00' required: false type: string format: date-time responses: '200': description: 'Result contains a numeric ID range of all invalidated items between given timestamps' schema: $ref: '#/definitions/InvalidationRange' '400': description: 'Invalid date format' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/invalidations/item/range?from=2018-06-08T10:15:08Z&to=2018-06-10T10:15:08Z"' /v6/invalidations: get: tags: - Invalidations summary: Get paginated list of all invalidated items within the given numeric ID range description: | Returns a list of all invalidated items within the given numeric ID range with limited size.
Any merchant or shop may be invalidated at any time so you need to call this service on a regular basis and process the invalidations as soon as possible (once a day is enough).

The response contains a list of invalidated items and the information about the last item ID in the current page, which should be used as a value of `fromId` parameter in the following request.
If any item (e.g. shop or merchant) is completely removed from our database, its `uid` will appear in the list of invalidated items.

The invalidation described step-by-step: * Let's suppose you have `lastItemId` from the previous invalidation. If you don't have it, use `GET /invalidations/item/range` to obtain it. * Call `GET /invalidations?fromId={{myLastItemId}}&pageSize={{myPageSize}}` * We don't need to set the `toId` parameter - usually you just need everything up to now. * The response contains at most `myPageSize` items and we process them all. * We remember the new value of `lastItemId` received in the response as `paging.lastItemId`. * If there are more than `myPageSize` items available, we'll see `paging.lastPage` set to `false` in the response. In that case, we just make another call to `GET /invalidations` with a new value of `lastItemId` It is worth emphasizing that the value of `lastItemId` field is the most significant and necessary for further calls. The list of invalidated items in the response may contain the following combinations of invalidation types and levels: ### Related to `/shops/{id}` #### type: shop + level: shallow Some of the shop's attributes have been changed (e.g. address, coordinates). Card transactions associated with the invalidated shops are still valid and its associations to the shop stay in place.
The result list (`data.batches.ids` field) contains uids of invalidated shops, including those that have been completely removed from our database. Calling the original endpoint for such removed shops will result in a `404` response or `notFound` status, which means you should remove the record from your system.
### Related to `/shops/findBy*Transaction*` #### type: shop + level: deep Deeply invalidated shop means you must throw away all previous results pointing to the shops in the response. All card transactions associated with the invalidated shops must be processed again.
The result list (`data.batches.ids` field) contains handles of the invalidated shops.
#### type: shop + level: solved Solved shop means you must throw away all previous results pointing to the `unsolved` shops in the response. All card transactions associated with the invalidated `unsolved` shops must be processed again.
The result list (`data.batches.ids` field) contains handles of the invalidated shops.
### Related to `/shops/findByBankTransfer/*` #### type: shop + level: transfer-deep Transfer-deeply invalidated shop means you must throw away all previous results pointing to the shops in the response. All bank transfers associated with the invalidated shops must be processed again.
The result list (`data.batches.ids` field) contains handles of the invalidated shops.

#### type: shop + level: transfer-solved Transfer-solved shop means you must throw away all previous results pointing to the `unsolved` shops in the response. All bank transfers associated with the invalidated `unsolved` shops must be processed again.
The result list (`data.batches.ids` field) contains handles of the invalidated shops.
### Related to `/merchants/{id}` #### type: merchant + level: shallow Some of the merchant's attributes have been changed (e.g. name or logo). Card transactions associated with the invalidated merchants are still valid and its associations to merchant's shops stay in place.
The result list (`data.batches.ids` field) contains uids of invalidated merchants, including those that have been completely removed from our database. Calling the original endpoint for such removed merchants will result in a `404` response or `notFound` status, which means you should remove the record from your system.
operationId: getInvalidationResult produces: - application/json parameters: - name: fromId in: query description: | necessary

The start ID (exclusive) of the range. Invalidated items with ID greater than this value will get to the result. required: true type: integer format: int64 - name: toId in: query description: | optional

The end ID (inclusive) of the range. Invalidated items with ID less or equal to this value will get to the result. required: false type: integer format: int64 - name: level in: query description: | optional

The result will only contain invalidated items with specified levels. If the value is empty or missing, no filter will be applied. required: false type: array items: type: string enum: - shallow - deep - transfer-deep - solved - transfer-solved - name: pageSize in: query description: | necessary

Specifies a limited number of items in the result set to be returned based on this value. Recommended value is between 100000 and 300000. Maximum value is 500000. required: true type: integer format: int64 responses: '200': description: 'Result contains one page of a list of invalidation batches and information about next page' schema: $ref: '#/definitions/InvalidationResult' '400': description: 'Invalid input' x-codeSamples: - lang: 'cURL' source: 'curl -X GET -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" "${TapixURL}/v6/invalidations?fromId=78757&level=shallow&pageSize=10"' /v6/feedback: post: tags: - Feedback summary: Report improvements or corrections. description: | Report improvements or corrections to the data provided by any of our services.

The `current` section carries the currently displayed merchant, category and location data, and `suggestion` is a free-form map describing what needs to be fixed.

Try to provide us with the maximum information possible. Ask us if you are unsure. operationId: suggest consumes: - application/json produces: - application/json parameters: - name: body in: body schema: $ref: '#/definitions/Feedback' responses: '200': description: 'Feedback was accepted' '400': description: 'Invalid input (missing/empty `suggestion` map or `source`, or unparseable `requestTimestamp`/`source`)' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"original":{"request":{"merchantId":"84591982","posId":"TES44278","description":"TESCO STORES 2789","zip":"N1 9DX","city":"LONDON","country":"GB","mcc":"5411"},"url":"/v6/shops/findByCardTransactionBatch","response":{"result":"found","handle":"0erPBQ5neagUElWYBK9ozG","shop":{"uid":"0erPBQ5neagUElWYBK9ozG"}},"requestTimestamp":"2020-09-19T11:16:36+00:00"},"current":{"shopUid":"0erPBQ5neagUElWYBK9ozG","merchantUid":"538VqZ4gn33tVJJWEYa8d3@gb","merchantName":"Tesco","location":{"address":{"street":"Skandinávská 144/25","city":"Praha 5 - Třebonice","zip":"15500","country":"CZ"},"coordinates":{"lat":50.049689,"long":14.294543}}},"suggestion":{"incorrectLocation":true,"text":"Wrong shop, should be Tesco store on 2 Monck St, London."},"source":"user"}'' "${TapixURL}/v6/feedback"' /v6/suggestions: post: tags: - Suggestions summary: Report improvements or corrections. deprecated: true description: |

Deprecated. This endpoint has been replaced by POST /v6/feedback. Please migrate to the Feedback endpoint.

Report improvements or corrections to the data provided by any of our services.
Every field except `suggestion` and `source` is optional and may be omitted if its value is not available. Try to provide us with the maximum information possible. Ask if you unsure. operationId: suggestDeprecated consumes: - application/json produces: - application/json parameters: - name: body in: body schema: $ref: '#/definitions/Suggestion' responses: '200': description: 'Suggestion was accepted' '400': description: 'Invalid input' x-codeSamples: - lang: 'cURL' source: 'curl -X POST -H ''Content-Type: application/json'' -H "Authorization: Bearer ${TOKEN}" -d ''{"original":{"url":"/v6/shops/findByBankTransfer/sepa?iban=BG18RZBB91550123456789","request":{"iban":"BG18RZBB91550123456789"},"response":{"result":"found","handle":"MmPdedgnvjXiRZnBJzJQKb","shop":{"uid":"MmPdedgnvjXiRZnBJzJQKb"}},"timestamp":"2018-09-20T11:16:36+00:00"},"current":{"shopUid":"MmPdedgnvjXiRZnBJzJQKb","transaction":{"iban":"BG18RZBB91550123456789"}},"suggestion":"Wrong shop, should be Nespresso shop in Amstelveen, Netherlands.","source":"partner"}'' "${TapixURL}/v6/suggestions"' /health: get: produces: - application/json summary: Application status check description: Returns the health status of the application. Always returns `UP` if the service is healthy. tags: - Health responses: '200': description: Application is running schema: $ref: '#/definitions/HealthResponse' definitions: HealthResponse: type: object properties: status: type: string example: 'UP' description: Current status of the application. FindNearbyResultsComplete: type: object properties: results: type: array items: $ref: '#/definitions/FindNearbyResultComplete' count: type: integer description: Number of ATMs returned. example: 1 countLimit: type: integer description: Value used to limit number of ATMs in result. example: 10 totalCount: type: integer description: Total number of ATMs found within the searched area. example: 1 FindNearbyResultComplete: type: object properties: atm: $ref: '#/definitions/AtmComplete' distance: type: integer description: Distance in meters from the specified location. example: 120 Areas: type: object description: Information about areas in which the shop or ATM is located (e.g. region, district, state, etc.). Represented as an associative array where each key represents the area level (in inclusion order) and its corresponding value represents the area name. E.g. for CZ/SK, area level 10 corresponds to an "okres" and level 20 to a "kraj". For the US, level 21 corresponds to state codes based on ISO 3166-2. additionalProperties: type: string example: 20: Hlavní město Praha 10: Hlavní město Praha Address: type: object properties: street: type: string maxLength: 255 example: 'Skandinávská 144/25' city: type: string maxLength: 255 example: 'Praha 5 - Třebonice' zip: type: string maxLength: 16 example: '15500' country: type: string description: Two letter country code as defined in ISO 3166-1 alpha-2 or three letter country code as defined in ISO 3166-1 alpha-3. example: 'CZ' areas: $ref: '#/definitions/Areas' unid: type: string maxLength: 255 description: Unique national postal address identifier (e.g. RUIAN ID in Czechia). example: '24987531' Coordinates: type: object description: Exact GPS coordinates of the place. properties: type: type: string enum: - rooftop - approximate description: | Coordinates type in sense of accuracy: * rooftop - pinpoint precision of the location * approximate - center of a broader area lat: type: number format: double example: 50.049689 long: type: number format: double example: 14.294543 zoom: type: number format: integer description: Zoom level for displaying provided coordinates on a map using Mercator projection. example: 16 Location: type: object properties: address: $ref: '#/definitions/Address' coordinates: $ref: '#/definitions/Coordinates' OtherCategoryOutput: type: 'object' properties: name: type: 'string' maxLength: 255 example: 'Employee Costs' description: Name of the category. logo: type: 'string' example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/category/Pt3GG2VcxfQZ1m6Nl9Kb0/l' description: Logo of the category. The logos are in a square format of 512 * 512 px but optimised for a circular cut with a diameter of 512 px, in case you need them round. The background colour is either white, black or other, depending on the design of the logo. The file format is always PNG. All logos are manually optimised and reviewed. The logo should be downloaded by the client using the URL returned in the response or stored in the database. CategoryOutput: type: 'object' properties: name: type: 'string' maxLength: 255 enum: - Atm - Beauty - Bills And Household - Car - Children - Consumer Goods - Culture - Digital Services - Drugstore - Electronics - Fashion - Financial Services - Food And Drink - Freetime - Groceries - Health - House And Garden - Pets - Professional Services - Shopping Online - Sport - Travel - Income - Investments - Business Expenses example: 'Fashion' description: Understand better Tapix’s categorisation and tags. logo: type: 'string' example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/category/Rw7HH6FpbvYJ1k2X9gDq5/l' description: Logo of the category. The logos are in a square format of 512 * 512 px but optimised for a circular cut with a diameter of 512 px, in case you need them round. The background colour is either white, black or other, depending on the design of the logo. The file format is always PNG. All logos are manually optimised and reviewed. The logo should be downloaded by the client using the URL returned in the response or stored in the database. MerchantWithoutID: type: object properties: name: type: string maxLength: 255 example: 'Marks and Spencer' description: Name of the merchant. logo: type: string maxLength: 1023 example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/m/Xm7GG0ErnrAT3z2N2pXVDv/l#f1804827d24250488b56d7e198abe57883dfaf9f' description: The logos are in a square format of 512 * 512 px but optimised for a circular cut with a diameter of 512 px, in case you need them round. The background colour is either white, black or other, depending on the design of the logo. The file format is always PNG. All logos are manually optimised and reviewed. The logo should be downloaded by the client using the URL returned in the response or stored in the database. The returned URL includes an appended etag after a '#' symbol, which serves as a unique identifier for the stored logo. localizedNames: type: object description: List of all localized names available for the returned merchant. additionalProperties: type: string example: latin: 'Marks and Spencer' 'greek': 'Μαρκς και Σπένσερ' 'arabic': 'ماركس وسبنسر' Merchant: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the merchant. example: 'frephafR7zekayUzu5uxu8' - $ref: '#/definitions/MerchantWithoutID' MerchantOutputBatch: type: object properties: merchants: type: array items: $ref: '#/definitions/MerchantWithStatus' MerchantWithStatus: type: object allOf: - $ref: '#/definitions/Merchant' - type: object properties: status: type: string description: | Status of the search result: * found - merchant found * notFound - no merchant exists with the provided ID or it has been removed
enum: - 'found' - 'notFound' MerchantComplete: type: object allOf: - $ref: '#/definitions/Merchant' MerchantAtmComplete: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the merchant. example: 'hlubnfR7rqndtNzu1thmQ' - $ref: '#/definitions/MerchantWithoutID' example: uid: 'hlubnfR7rqndtNzu1thmQ' name: 'ATM Geldmaat' logo: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/m/QyjWVeGa11ksnNMZZLr1Ro/l' AddressAtm: type: object properties: street: type: string maxLength: 255 example: 'Utrechtsestraat 13' city: type: string maxLength: 255 example: 'Amsterdam' zip: type: string maxLength: 16 example: '1017 VN' country: type: string description: Two letter country code as defined in ISO 3166-1 alpha-2 or three letter country code as defined in ISO 3166-1 alpha-3. example: 'NL' CoordinatesAtm: type: object description: Exact GPS coordinates of the place. properties: lat: type: number format: double example: 52.36567 long: type: number format: double example: 4.897928 LocationAtm: type: object properties: address: $ref: '#/definitions/AddressAtm' coordinates: $ref: '#/definitions/CoordinatesAtm' AtmWithoutIDAndMerchant: type: object properties: location: $ref: '#/definitions/LocationAtm' voiceAssistant: type: boolean description: Indicates whether voice assistance is available from the ATM. example: false wheelchairAccess: type: boolean description: Indicates whether the ATM has features for wheelchair accessibility. example: true contactless: type: boolean description: Indicates whether the the ATM is contactless. example: true depositAtm: type: boolean description: Indicates whether the ATM supports deposits. This information (`true`) is only available for ATMs that are part of the user's alliance. For all other ATMs, this field will be `false`. example: true inAlliance: type: boolean description: Indicates whether the ATM is part of the user's alliance. `true` for ATMs belonging to the user's alliance, `false` otherwise. For users without an alliance, this field is always `false`. example: true openNonStop: type: boolean description: Indicates whether the ATM is available 24/7. If false, check `openingHours`. example: false openStatus: $ref: '#/definitions/OpenStatus' description: Information about the current opening status of the ATM. openingHours: type: string description: | Opening hours of the ATM. Uses OpenStreetMap opening_hours format. example: 'Mo-Fr 08:00-20:00; Sa 09:00-12:00' fee: type: object description: Information about the fee charged by the ATM. This is an extra feature that will not be active by default. It can be activated upon request. properties: currency: type: string description: Fixed fee currency represented by a three-letter alphabetic code. ISO 4217. amount: type: number description: Fixed fee amount. percentage: type: number minimum: 0.0 maximum: 1.0 description: Percentage fee on withdrawal. example: currency: 'EUR' percentage: 0.15 partnerData: $ref: '#/definitions/PartnerData' description: | Contains additional, partner-specific data for an ATM. This field is only returned when a partner has provided supplementary information for this specific ATM. The structure of this object is defined by the partner. OpenStatus: type: object description: Information about the current opening status of the ATM. properties: isOpen: type: boolean description: Indicates if the ATM is currently open based on its opening hours. example: true minutesToOpen: type: integer description: Number of minutes until the ATM opens. Only present if `isOpen` is false and the next opening time is known. minutesToClose: type: integer description: Number of minutes until the ATM closes. Only present if `isOpen` is true and the closing time is known. example: 120 example: isOpen: true minutesToClose: 120 PartnerData: type: object description: | Contains additional, partner-specific data for an ATM. This field is only returned when a partner has provided supplementary information for this specific ATM. The structure of this object is defined by the partner. example: isPremiumLocation: true supportedServices: - 'Coin Deposit' - 'Statement Printing' lastMaintenanceDate: '2025-01-30' ShopWithoutIDAndMerchant: type: object properties: type: type: string maxLength: 20 enum: - bricks - online - atm - account description: | Shop type in sense how it operates: * bricks - bricks and mortar (real shop in a real world) * online - eshop or any other online purchase * atm - ATM, cash-machine, bancomat * account - specific bank account of the merchant category: $ref: '#/definitions/CategoryOutput' tags: type: array items: type: string maxLength: 255 example: ['Bookstore', 'Shopping Online'] description: Tags describing goods / services available in the shop (related to category). The tags are sorted by relevance, the most relevant comes first. Tag values are not immutable and may change over time.
Understand better Tapix’s categorisation and tags. otherCategories: type: object additionalProperties: $ref: '#/definitions/OtherCategoryOutput' example: business: { name: 'Employee Costs', logo: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/category/Fo2UU9LkxdZA1w7V3qBTh4/l', } custom: { name: 'Entertainment', logo: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/category/Kb6RR1QjzvXZ2g8H6cNPy5/l', } description: Other types of categories not directly related to merchant's field of business rather to a type of transaction, e.g. Everyday Business Expenses, Staff payment, etc.
Understand better Tapix’s categorisation and tags. This feature is not enabled by default and can be activated upon request. otherTags: type: object additionalProperties: type: array items: type: string maxLength: 255 example: business: ['Advertising', 'Printing / Copying'] description: Tags describing goods / services available in the shop (related to otherCategories). The tags are sorted by relevance, the most relevant comes first. Tag values are not immutable and may change over time.
Understand better Tapix’s categorisation and tags. This feature is not enabled by default and can be activated upon request. location: $ref: '#/definitions/Location' url: type: string description: Website URL of the shop. example: 'https://dateio.eu' googlePlaceId: type: string maxLength: 1024 description: Place IDs uniquely identify a place in the Google Places database and on Google Maps. example: 'ChIJrTLr-GyuEmsRBfy61i59si0' phoneNumber: type: string maxLength: 255 description: Phone number of the shop. example: '+420 123 456 789' Bank: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the bank. example: '107dbd71e71a9826ccb1db' - $ref: '#/definitions/BankWithoutID' BankWithoutID: type: object properties: name: type: string maxLength: 255 example: 'Barclays' logo: type: string maxLength: 1023 example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/b/107dbd71e71a9826ccb1db/l#09ad1dde68f89b0304e2e2a4c3529da37578a069' description: The logo of the bank. The logo should be downloaded by the client using the URL returned in the response or stored in the database. The returned URL includes an appended etag after a '#' symbol, which serves as a unique identifier for the stored logo. Shop: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the shop. example: 'MmPdedgnvjXiRZnBJzJQKb' merchantUid: type: string maxLength: 100 description: Unique identifier of the merchant. example: 'frephafR7zekayUzu5uxu8' - $ref: '#/definitions/ShopWithoutIDAndMerchant' ShopOutputBatch: type: object properties: shops: type: array items: $ref: '#/definitions/ShopWithStatus' ShopWithStatus: type: object allOf: - $ref: '#/definitions/Shop' - type: object properties: status: type: string description: | Status of the search result: * found - shop found * notFound - no shop exists with the provided ID or it has been removed enum: - 'found' - 'notFound' ShopComplete: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the found shop. example: 'MmPdedgnvjXiRZnBJzJQKb' merchant: $ref: '#/definitions/MerchantComplete' - $ref: '#/definitions/ShopWithoutIDAndMerchant' AtmComplete: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the atm. example: 'KrDfusnfsYoWBnBJzJQBk' merchant: $ref: '#/definitions/MerchantAtmComplete' - $ref: '#/definitions/AtmWithoutIDAndMerchant' BankComplete: type: object allOf: - $ref: '#/definitions/Bank' FindResult: type: object properties: result: $ref: '#/definitions/FindResultType' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/FindResultShop' debug: $ref: '#/definitions/DebugFindings' FindResultWithCO2Footprint: type: object properties: result: $ref: '#/definitions/FindResultType' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/FindResultShop' co2Footprint: $ref: '#/definitions/CO2Footprint' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'T13FbTr3mu' FindResultWithPaymentGatewayAndCO2Footprint: type: object properties: result: $ref: '#/definitions/FindResultType' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/FindResultShop' paymentGateway: $ref: '#/definitions/FindResultPaymentGateway' co2Footprint: $ref: '#/definitions/CO2Footprint' subscription: $ref: '#/definitions/FindResultSubscription' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'T13FbTr3mu' FindResultWithBankAndCO2Footprint: type: object properties: result: $ref: '#/definitions/FindResultType' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/FindResultShop' bank: $ref: '#/definitions/FindResultBank' co2Footprint: $ref: '#/definitions/CO2Footprint' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. It will be randomly generated if not specified. example: 'T13FbTr3mu' FindResultWithCustomIdAndBankAndCO2Footprint: type: object allOf: - $ref: '#/definitions/FindResultWithBankAndCO2Footprint' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'X11FfTr4ma' FindResultWithBankAndCO2FootprintAndSubscription: type: object properties: result: $ref: '#/definitions/FindResultType' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/FindResultShop' bank: $ref: '#/definitions/FindResultBank' co2Footprint: $ref: '#/definitions/CO2Footprint' subscription: $ref: '#/definitions/FindResultSubscription' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. It will be randomly generated if not specified. example: 'T13FbTr3mu' FindResultWithCustomIdAndBankAndCO2FootprintAndSubscription: type: object allOf: - $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscription' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'X11FfTr4ma' DebugFinding: type: object properties: comment: type: string description: Comment on the finding, may also include a suggestion for a fix. example: 'Request contains a date in an incorrect format' severity: type: string enum: - high - medium - low - info description: Severity of the finding. example: 'high' fields: type: array description: List of fields for which the finding was detected. items: type: string example: 'transactionTimestamp' InvalidationRange: type: object properties: fromId: type: integer format: int64 example: 120499 description: The start ID of the range. toId: type: integer format: int64 example: 152987 description: The end ID of the range. itemCount: type: integer format: int64 example: 27141 description: An approximate number of items in given range. InvalidationResult: type: object properties: data: type: object properties: currentTime: type: string format: date-time example: '2017-10-20T13:15:08Z' description: Exact time of the result generation. batches: type: array items: $ref: '#/definitions/InvalidationBatch' paging: type: object properties: lastItemId: type: integer format: int64 example: 134154 description: Numeric ID of the last item in the result. This value should be used as a start ID in the next page request. If the current result (current page) is empty, this field will not be presented. lastPage: type: boolean example: false description: Indicates whether this page is the last page of the complete result. pageSize: type: integer format: int64 example: 134154 description: Number of items in the current result (current page). InvalidationBatch: type: object properties: type: type: string maxLength: 20 enum: - merchant - shop example: 'shop' level: type: string maxLength: 20 enum: - shallow - deep - transfer-deep - solved - transfer-solved example: 'shallow' ids: type: array description: Contains list of IDs (`uid`) identifying all invalidated items of given type and invalidation level. items: type: string maxLength: 100 example: ['MmPdedgnvjXiRZnBJzJQKb', 'MmPdedgnvjXiRZnBJzJQKx'] RequestGetShop: type: 'object' properties: id: type: 'string' description: | necessary

ID (`uid`) of shop to return.
Example: MmPdedgnvjXiRZnBJzJQKb example: 'MmPdedgnvjXiRZnBJzJQKb' RequestGetShopBatch: type: 'object' properties: shops: type: 'array' description: | necessary

Contains list of IDs objects. items: $ref: '#/definitions/RequestGetShop' RequestGetMerchant: type: 'object' properties: id: type: 'string' description: | necessary

ID (`uid`) of merchant to return.
Example: frephafR7zekayUzu5uxu8 example: 'frephafR7zekayUzu5uxu8' RequestGetMerchantBatch: type: 'object' properties: merchants: type: 'array' description: | necessary

Contains list of IDs objects. items: $ref: '#/definitions/RequestGetMerchant' RequestCertisTransfer: type: object properties: accountNumber: type: string description: | necessary

The counterpart's (national) bank account number. Format specified in Annex 1 to the Rules of the CERTIS Payment System (10n, the leading zeros may be omitted).
Example: 4159 example: '4159' accountNumberPrefix: type: string description: | necessary

The prefix of the counterpart's (national) bank account number. Format specified in Annex 1 to the Rules of the CERTIS Payment System (6n, the leading zeros may be omitted).
Example: 178124 example: '178124' bankCode: type: string description: | necessary

Counterpart's national bank code assigned by a central bank, a bank supervisory body or a Bankers Association in a country to all its licensed member banks or financial institutions.
Example: 0710 example: '0710' paymentType: type: string enum: [I, O] description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I example: 'I' accountName: type: string description: | important

The name of the counterpart's account.
Example: Béďa Trávníček example: 'Béďa Trávníček' currency: type: string description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR example: EUR amount: type: number description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 example: 800.5 refresh: type: boolean description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true example: true variableSymbol: type: string description: | good to have

A variable symbol is used by beneficiary to make identifying a payment simpler especially when many payments are remitted to its account.
Example: 9 example: '9' specificSymbol: type: string description: | good to have

A specific symbol is used to identify a payment. Helps to classify a payment for your invoice, for instance.
Example: 100011 example: '100011' constantSymbol: type: string description: | good to have

A constant symbol is non-obligatory payment data solely used for classifying payments.
Example: 0558 example: '0558' message: type: string description: | optional

Additional information or message for counterpart.
Example: PREVOD PROSTREDKU example: 'PREVOD PROSTREDKU' note: type: string description: | optional

Additional information or note.
Example: WAGE 889Vd6 example: 'WAGE 889Vd6' aggCount: type: integer description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 example: 42 clientId: type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS example: 'C7T13423469224BFS' nextPaymentDate: type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 example: '2025-04-15' recurrenceType: type: string enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE example: 'SINGLE' paymentTimestamp: type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 example: '2025-04-15T11:16:36+00:00' RequestCertisTransferBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestCertisTransferWithCustomId' required: - requests RequestCertisTransferWithCustomId: type: object allOf: - $ref: '#/definitions/RequestCertisTransfer' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field will be returned unchanged in the response. It will be randomly generated if not specified.
Example: Y22GgUs5nb example: 'Y22GgUs5nb' RequestTX: type: object properties: description: type: string description: | necessary

ISO 8583 Field 43 - Card acceptor name / location (1-23 address). Case-insensitive.
Example: TESCO PRAHA ZLICIN example: 'TESCO PRAHA ZLICIN' merchantId: type: string description: | very important

ISO 8583 Field 42 - Card acceptor identification code. Case-insensitive.
Example: 820014 example: '820014' posId: type: string description: | very important

ISO 8583 Field 41 - Card acceptor terminal identification. Point-of-sale ID. Card acceptor (merchant) terminal identifier. Case-insensitive.
Example: 18052001 example: '18052001' city: type: string description: | very important

ISO 8583 Field 43 - Card acceptor name / location (24-36 city). Case-insensitive.
Example: PRAHA example: 'PRAHA' country: type: string description: | very important

ISO 8583 Field 43 - Card acceptor name / location (39-40 country). Format is defined in ISO 3166-1 alpha-2. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable. Case-insensitive.
Please make sure NOT to just trim the ISO 3166-1 alpha-3 country code to 2 letters!
Example: CZ example: 'CZ' mcc: type: string description: | very important

Merchant category code. ISO 8583 Field 18 - Merchant type.
Note: any non-numeric value will be ignored.
Example: 5411 example: '5411' transactionTimestamp: type: string format: date-time description: | important

Transaction timestamp. Date and time, local transaction. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. If you want to provide information about the date only, without the precise time, use field ignoreTime = true.
Example: 2018-09-19T11:16:36+00:00 example: '2018-09-19T11:16:36+00:00' sourceId: type: string maxLength: 255 example: 'B7T1533692247A' description: | important

Randomised number or hash used as a stable identifier linking transactions from the same card / mobile app.
Example: B7T1533692247A currency: type: string example: EUR description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR amount: type: number example: 800.5 description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 refresh: type: boolean example: true description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true ecommerceFlag: type: boolean description: | good to have

ISO 8583 Field 25 - Point of service condition code. True - E-Commerce, false - Physical Payment.
Example: true example: true channelCode: type: string description: | good to have

“ATM” - Cash Withdrawal (Bankomat), “POS” - Card Payment.
Example: POS example: 'POS' zip: type: string maxLength: 16 description: | good to have

ZIP code of location.
Example: 36001 example: '36001' state: type: string description: | good to have

ISO 8583 Field 43 - Card acceptor name / location (37-38 state).
Case-insensitive.
Example: CO example: 'CO' acquirerId: type: string description: | good to have

Acquiring institution identification code. ISO 8583 Field 32 Format N…11 (LLVAR).
Example: 1234567 example: '1234567' address: type: string maxLength: 255 example: 'Praha, Vinohradská 2842/104' description: | good to have

Address of the place. Provided when some information is available (e.g. from own acquiring).
Example: Praha, Vinohradská 2842/104 pairingId: type: string example: '4078296076' description: | good to have

Unique identifier which must be used to group all requests based on a single card transaction. Something like hashed transaction-id may be used. A typical use-case is calling Tapix in the payment authorization phase (in time of customer's payment at the point-of-sale) and afterwards in the settlement phase (minutes / hours / days later). Another use-case is calling Tapix after data invalidation when data of previously processed transactions is refreshed.
Example: 4078296076 acquirerCountryCode: type: string description: | good to have

Code of the country where the acquirer is located. ISO 8583 Field 19 Format specified by ISO 3166. posEntryMode: type: string description: | good to have

ISO 8583 Field 22 - Identifier of the method used to obtain the PAN.
Example: 10 example: '10' posTransactionStatusIndicator: type: string description: | good to have

ISO 8583 Field 60.6 - Identifier of the POS Transaction Status Indicator.
Example: R example: 'R' ecommerceIndicator: type: string description: | good to have

ISO 8583 Field 126 - Identifier of the Electronic Commerce/MOTO (Mail Order/Telephone Order) Indicator.
Example: 02 example: '02' associationName: type: string maxLength: 255 description: | optional

Name of card association.
Example: MASTERCARD example: 'MASTERCARD' ignoreTime: type: boolean description: | optional

Set to true, if time from transactionTimestamp should be ignored (however, date will be used).
Example: true example: true gpsLat: type: number format: double example: 50.049689 description: | optional

GPS coordinates of the place - latitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 50.049689 gpsLong: type: number format: double example: 14.294543 description: | optional

GPS coordinates of the place - longitude. Provided when some (also approximate) location of payment is known (e.g. based on mobile app location).
Example: 14.294543 rawParams: type: string maxLength: 255 description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it. clientId: type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS example: 'C7T13423469224BFS' RequestTXBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestTXWithCustomId' required: - requests RequestTXWithCustomId: type: object allOf: - $ref: '#/definitions/RequestTX' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field will be returned unchanged in the response. It will be randomly generated if not specified.
Example: X11FfTr4ma example: 'X11FfTr4ma' FindResultWithCustomIdAndCO2Footprint: type: object allOf: - $ref: '#/definitions/FindResultWithCO2Footprint' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'X11FfTr4ma' FindResultWithCustomIdAndPaymentGatewayAndCO2Footprint: type: object allOf: - $ref: '#/definitions/FindResultWithPaymentGatewayAndCO2Footprint' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'T13FbTr3mu' FindResultComplete: type: object properties: result: $ref: '#/definitions/FindResultTypeComplete' shop: $ref: '#/definitions/ShopComplete' debug: $ref: '#/definitions/DebugFindings' FindResultWithCO2FootprintComplete: type: object properties: result: $ref: '#/definitions/FindResultTypeComplete' handle: $ref: '#/definitions/FindResultHandle' shop: $ref: '#/definitions/ShopComplete' paymentGateway: $ref: '#/definitions/PaymentGateway' co2Footprint: $ref: '#/definitions/CO2Footprint' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'T13FbTr3mu' FindResultWithBankAndCO2FootprintComplete: type: object properties: result: $ref: '#/definitions/FindResultTypeComplete' shop: $ref: '#/definitions/ShopComplete' bank: $ref: '#/definitions/BankComplete' co2Footprint: $ref: '#/definitions/CO2Footprint' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. It will be randomly generated if not specified. example: 'T13FbTr3mu' FindResultTypeComplete: type: string maxLength: 20 enum: - found - unsolved example: 'found' description: > Result state based on the search result * found - Shop has been found and all available information about it is returned. * unsolved - Shop has not been found, but may be available in the future (we call this "unsolved shop"). FindResultType: type: string maxLength: 20 enum: - found - unsolved example: 'found' description: > Result state based on the search result * found - Shop has been found and its `handle` and `shop.uid` are returned. * unsolved - Shop has not been found, but may be available in the future (we call this "unsolved shop"). Only `handle` is returned which will be used in `/invalidations` after the shop becomes available and gets new `uid` (we say the shop is "solved"). FindResultHandle: type: string maxLength: 100 description: Represents an identifier of the reference between the transaction and the find result. The value of the `handle` is not unique for every transaction. Many different handles may refer to the same shop (`shop.uid`). If the find result gets changed some time in the future then the respective handle will appear in `GET /invalidations` response. That's why you need to keep the `handle` associated with the original transaction. example: '$91vbcF7535E43615lq7bqQ' FindResultShop: type: object description: Contains `uid` of the found shop and is included only if the `result` is 'found'. properties: uid: type: string maxLength: 100 description: Unique identifier of the found shop. example: 'MmPdedgnvjXiRZnBJzJQKb' FindResultBank: type: object description: Contains `uid` of the bank. properties: uid: type: string maxLength: 100 description: Unique identifier of the found bank. example: '107dbd71e71a9826ccb1db' DebugFindings: type: object description: | Contains debugging information on the request. It serves as a hint for correcting input values to help achieve better enrichment results.
This feature is enabled by default for all test accounts and disabled for production accounts. In the latter case, the debug result will not be included in the response. properties: findings: type: array description: Contains debugging information on the request. items: $ref: '#/definitions/DebugFinding' FindResultWithCustomIdAndCO2FootprintComplete: type: object allOf: - $ref: '#/definitions/FindResultWithCO2FootprintComplete' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'X11FfTr4ma' FindResultWithCustomIdAndBankAndCO2FootprintComplete: type: object allOf: - $ref: '#/definitions/FindResultWithBankAndCO2FootprintComplete' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. It will be randomly generated if not specified. example: 'X11FfTr4ma' FindResultWithBankAndCO2FootprintAndSubscriptionComplete: type: object properties: result: $ref: '#/definitions/FindResultTypeComplete' shop: $ref: '#/definitions/ShopComplete' bank: $ref: '#/definitions/BankComplete' co2Footprint: $ref: '#/definitions/CO2Footprint' subscription: $ref: '#/definitions/FindResultSubscription' debug: $ref: '#/definitions/DebugFindings' customId: type: string maxLength: 255 description: This field has the same value as in the request. It will be randomly generated if not specified. example: 'T13FbTr3mu' FindResultWithCustomIdAndBankAndCO2FootprintAndSubscriptionComplete: type: object allOf: - $ref: '#/definitions/FindResultWithBankAndCO2FootprintAndSubscriptionComplete' - type: object properties: customId: type: string maxLength: 255 description: This field has the same value as in the request. If none was provided, it will be randomly generated. example: 'X11FfTr4ma' RequestCTX: type: object properties: data: $ref: '#/definitions/RequestCTXData' bank: type: string description: | necessary

Identifier of bank of transaction origin.
Example: HSBC example: 'HSBC' source: type: string description: | necessary

Description of datasource.
Example: Saltedge example: 'Saltedge' refresh: type: boolean description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true example: true customId: type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated. required: - data - bank - source RequestCTXData: type: object description: | necessary

properties: description: type: string description: | necessary

Transaction description.
Example: STARBUCKS, LONDON 2022-02-02 10 GBP example: 'STARBUCKS, LONDON 2022-02-02 10 GBP' other: type: object description: | good to have

Other transactional data in JSON map. example: { 'note': 'caffe americano', 'city': 'London', 'country': 'GB', 'type': 'card payment', 'category': 'cafe', } required: - description RequestCTXBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestCTXWithCustomId' required: - requests RequestCTXWithCustomId: type: object allOf: - $ref: '#/definitions/RequestCTX' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field will be returned unchanged in the response. It will be randomly generated if not specified.
Example: X11FfTr4ma example: 'X11FfTr4ma' RequestQR: type: object properties: merchantName: type: string description: | necessary

Trade merchant name of the payee. Case-insensitive.
Example: Burger King example: 'Burger King' storeName: type: string description: | necessary

Name of the merchant's store. Case-insensitive.
Example: BK Trafalgar Square example: 'BK Trafalgar Square' merchantId: type: string description: | important

Merchant ID of the payee. Case-insensitive.
Example: MPL353236E21 example: 'MPL353236E21' storeId: type: string description: | important

Store ID of the payee. Case-insensitive.
Example: MPL353566E24 example: 'MPL353566E24' terminalId: type: string description: | important

Terminal ID of the payee. Case-insensitive.
Example: ZER387566D28 example: 'ZER387566D28' iban: type: string description: | important

The International Bank Account Number of the payee. Case-insensitive.
Example: BG18RZBB91550123456789 example: 'BG18RZBB91550123456789' country: type: string description: | important

Merchant country. Format is defined in ISO 3166-1 alpha-2. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable. Case-insensitive.
Please make sure NOT to just trim the ISO 3166-1 alpha-3 country code to 2 letters!
Example: US example: 'US' city: type: string description: | important

Merchant City - city where the QR code is located. Case-insensitive.
Example: London example: 'London' mcc: type: string description: | important

Merchant category code.
Note: any non-numeric value will be ignored.
Example: 5411 example: '5411' transactionTimestamp: type: string format: date-time description: | important

Transaction timestamp. Date and time, local transaction. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. If you want to provide information about the date only, without the precise time, use field ignoreTime = true.
Example: 2018-09-19T11:16:36+00:00 example: '2018-09-19T11:16:36+00:00' ignoreTime: type: boolean description: | important

Set to true, if time from transactionTimestamp should be ignored (however, date will be used).
Example: true example: true deviceId: type: string description: | important

Stable identifier linking transactions from the device within few hours or a day (id can be newly generated after few hours).
Example: B7T1533692247A example: 'B7T1533692247A' currency: type: string example: EUR description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR amount: type: number example: 800.5 description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 refresh: type: boolean description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true example: true address: type: string maxLength: 255 description: | good to have

Address of the place. Provided when some information is available. Case-insensitive.
Example: 87-135 Brompton Rd, London example: '87-135 Brompton Rd, London' clientId: type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS example: 'C7T13423469224BFS' RequestQRBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestQRWithCustomId' required: - requests RequestQRWithCustomId: type: object allOf: - $ref: '#/definitions/RequestQR' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field is used to identify requests. If it is provided, the same value will be returned in the response. Otherwise it will be randomly generated.
Example: X11FfTr4ma example: 'X11FfTr4ma' RequestSepaTransfer: type: object properties: iban: type: string description: | necessary

ISO 13616 - The International Bank Account Number of the counterpart.
Example: BG18RZBB91550123456789 example: 'BG18RZBB91550123456789' paymentType: type: string enum: [I, O] description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I example: 'I' bic: type: string description: | important

ISO 9362 - Counterpart's bank code in international format.
Example: AIRACZPP example: 'AIRACZPP' name: type: string description: | important

The raw name/description of the recipient counterpart.
Example: 15. přední hlídka Royal Rangers Mariánské Lázně example: '15. přední hlídka Royal Rangers Mariánské Lázně' remittanceInfo: type: string description: | important

ISO 20022 – Remittance Information. Free-text payment reference provided by the originator to the beneficiary.
Example: Invoice 2023/09 #4581 example: 'Invoice 2023/09 #4581' currency: type: string description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: EUR example: EUR amount: type: number description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 example: 800.5 refresh: type: boolean description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true example: true city: type: string description: | optional

The city of the counterpart.
Example: PRAHA example: 'PRAHA' zip: type: string description: | optional

The postal (ZIP) code of the counterpart.
Example: 36001 example: '36001' postalAddress: type: string description: | optional

The specific postal address of the counterpart.
Example: CZ, JUNGMANNOVA 1, PRAHA 1, 110 00 example: 'CZ, JUNGMANNOVA 1, PRAHA 1, 110 00' country: type: string description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: CZ example: 'CZ' rawParams: type: string description: | optional

Customer specific field. Content needs to be agreed upon, otherwise don’t use it. aggCount: type: integer description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 example: 42 clientId: type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS example: 'C7T13423469224BFS' nextPaymentDate: type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 example: '2025-04-15' recurrenceType: type: string enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE example: 'SINGLE' paymentScheme: type: string description: | important

The specific payment method or local overlay used within the SEPA network. This differentiates between standard credit transfers and regional sub-variants or specialized European payment brands such as iDeal, WERO, Bizum or BLIK.
Example: WERO example: 'WERO' paymentTimestamp: type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 example: '2025-04-15T11:16:36+00:00' RequestSepaTransferBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestSepaTransferWithCustomId' required: - requests RequestSepaTransferWithCustomId: type: object allOf: - $ref: '#/definitions/RequestSepaTransfer' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field will be returned unchanged in the response. It will be randomly generated if not specified.
Example: Z33HhVt6oc example: 'Z33HhVt6oc' RequestUKTransfer: type: object properties: paymentType: type: string enum: [I, O] description: | necessary

Type of the payment. "I" - Incoming (Credit), "O" - Outgoing (Debit).
Example: I example: 'I' sortCode: type: string description: | necessary

A 6 numeric digit number without hyphens that identifies the UK institution and branch. Must be valid UK sorting code.
Example: 400515 example: '400515' accountNumber: type: string description: | necessary

An 8 numeric digit number that identifies the individual customer’s clearing account at the UK institution/branch. Must be valid UK account number.
Example: 01234567 example: '01234567' bankCode: type: string description: | necessary

Identical to the first four characters of the counterpart bank's BIC/SWIFT code. For more info see ISO 9362. Length - 4 characters.
Example: HBUK example: 'HBUK' paymentMethod: type: string enum: [BACS_DD, BACS_DC, FP] description: | important

Automated payment method. "BACS_DD" - BACS Direct Debit, "BACS_DC" - BACS Direct Credit, "FP" - Faster Payments.
Example: BACS_DD example: 'BACS_DD' name: type: string description: | important

The raw name/description of the recipient counterpart. Maximum length - 18 characters.
Example: GOOGLE IRELAND example: 'GOOGLE IRELAND' bankName: type: string description: | important

The name of the counterpart's bank. Maximum length - 35 characters.
Example: Barclays example: 'Barclays' currency: type: string description: | conditional

Necessary parameter for CO2 footprint evaluation.
The currency in which the payment is made represented by an three-letter alphabetic code. ISO 4217.
Example: GBP example: 'GBP' amount: type: number description: | conditional

Necessary parameter for CO2 footprint evaluation.
The payment amount. A negative value usually means a refund for the purchase.
Example: 800.5 example: 800.5 refresh: type: boolean description: | conditional

Necessary parameter if invalidations are implemented.
False for all normal enrichment calls.
True for all enrichment calls which are part of the invalidations data update process.
Example: true example: true paymentDate: type: string format: date description: | good to have

Payment date. Date, local payment. ISO 8601. Format: YYYY-MM-DD.
Example: 2020-11-30 example: '2020-11-30' paymentReference: type: string description: | good to have

Details of the payment. Maximum length: 18 characters.
Example: AS4F54S564F56S4 example: 'AS4F54S564F56S4' city: type: string description: | optional

The city of the counterpart.
Example: REDLYNCH example: 'REDLYNCH' zip: type: string description: | optional

The postal (ZIP) code of the counterpart.
Example: BA10 1WN example: 'BA10 1WN' address: type: string description: | optional

The specific address of the counterpart.
Example: 97 BOAT LANE example: '97 BOAT LANE' country: type: string description: | optional

ISO 3166-1 alpha-2 - The country code of the counterpart. Three letter country code as defined in ISO 3166-1 alpha-3 is also acceptable.
Example: GB example: 'GB' aggCount: type: integer description: | optional

(Used only in combination with caching) Number of transfers processed using the cache. Every transfer processed shall be reported exactly once.
Example: 42 example: 42 clientId: type: string description: | important

Randomised number or hash used as a stable identifier linking transactions from the same client. Client_id must be identical across all endpoints.
Example: C7T13423469224BFS example: 'C7T13423469224BFS' nextPaymentDate: type: string format: date description: | important

The date of the next scheduled execution of the standing order. Must follow the ISO 8601 format (YYYY-MM-DD).
Example: 2025-04-15 example: '2025-04-15' recurrenceType: type: string enum: [SINGLE, STANDING_ORDER, DIRECT_DEBIT] description: | important

Defines the nature of the payment instruction. Possible values: SINGLE (one-off), STANDING_ORDER (recurring), or DIRECT_DEBIT.
Example: SINGLE example: 'SINGLE' paymentTimestamp: type: string format: date-time description: | important

The date and time when the payment was executed. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2025-04-15T11:16:36+00:00 example: '2025-04-15T11:16:36+00:00' RequestUKTransferBatch: type: object properties: requests: type: array description: | necessary

Contains list of request objects. items: $ref: '#/definitions/RequestUKTransferWithCustomId' required: - requests RequestUKTransferWithCustomId: type: object allOf: - $ref: '#/definitions/RequestUKTransfer' - type: object properties: customId: type: string maxLength: 255 description: | optional

This field will be returned unchanged in the response. It will be randomly generated if not specified.
Example: T12FbTr3mv example: 'T12FbTr3mv' Feedback: type: object properties: original: type: object description: | necessary

All available information about the original request to which the feedback relates. properties: request: type: object description: | necessary

Data from the original request (request body or query parameters). example: merchantId: '84591982' posId: 'TES44278' description: 'TESCO STORES 2789' zip: 'N1 9DX' city: 'LONDON' country: 'GB' mcc: '5411' transactionTimestamp: '2019-09-19T11:16:36+00:00' pairingId: '21a377333da2c86716b02d72396f57ad' customId: 'fDuVom31' url: type: string description: | necessary

URL of the used endpoint (including query parameters if available).
Example: /v6/shops/findByCardTransactionBatch example: '/v6/shops/findByCardTransactionBatch' response: type: object description: | optional

Data from the original response. example: result: 'found' handle: '0erPBQ5neagUElWYBK9ozG' shop: uid: '0erPBQ5neagUElWYBK9ozG' requestTimestamp: type: string format: date-time description: | optional

Timestamp of the original request. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`.
Example: 2020-09-19T11:16:36+00:00 example: '2020-09-19T11:16:36+00:00' required: - request - url current: type: object description: | necessary

All currently available data to which the feedback relates. properties: shopUid: type: string maxLength: 100 description: | important

uid of the shop to which the feedback relates.
Example: 0erPBQ5neagUElWYBK9ozG example: '0erPBQ5neagUElWYBK9ozG' merchantUid: type: string maxLength: 100 description: | important

uid of the merchant to which the feedback relates.
Example: 538VqZ4gn33tVJJWEYa8d3@gb example: '538VqZ4gn33tVJJWEYa8d3@gb' merchantName: type: string description: | important

Currently displayed merchant name. example: 'Tesco' merchantLogoUrl: type: string description: | important

Currently displayed merchant logo URL. example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/m/538VqZ4gn33tVJJWEYa8d3/l#893bdd4dc4db45a53e0582eb537bd5048e903144' shopCategory: description: | important

Currently assigned shop category. displayedCategory: description: | important

Currently displayed category. location: allOf: - description: | important

Currently displayed location (`address` + `coordinates`). - $ref: '#/definitions/Location' suggestion: type: object description: | necessary

Free-form map describing what is mismatched and its correct value. The example shows the recommended structure, but any fields are accepted. example: incorrectMerchant: false incorrectLogo: false incorrectLocation: true incorrectCategory: false text: 'Wrong shop, should be Tesco store on 2 Monck St, London.' source: type: string maxLength: 20 enum: - user - partner description: | necessary

Original author of the feedback: * user - end user (e.g. client of a bank) * partner - Tapix customer who is directly calling the API (e.g. a bank).
Example: user example: 'user' required: - suggestion - source Suggestion: type: object description: | Deprecated. Request body of the deprecated `POST /v6/suggestions` endpoint. Use the `Feedback` schema with `POST /v6/feedback` instead. properties: original: type: object description: | necessary

All available information about the original request to which the suggestion relates. Fill-in only if you have information about the original request. Otherwise, fill-in fields in `current` section. properties: request: type: object description: | necessary

Data from the original request. Usually fill-in the request body or query parameters in a map. example: merchantId: '84591982' posId: 'TES44278' description: 'TESCO STORES 2789' zip: 'N1 9DX' city: 'LONDON' country: 'GB' mcc: '5411' url: type: string description: | important

URL of the original request (including query parameters if available). example: '/v6/shops/findByCardTransaction?merchantId=84591982&posId=TES44278&zip=N1%209DX&description=TESCO%20STORES%202789&city=LONDON&country=GB&mcc=5411' response: type: object description: | optional

Data from the original response. example: result: 'found' handle: '0erPBQ5neagUElWYBK9ozG' shop: uid: '0erPBQ5neagUElWYBK9ozG' timestamp: type: string format: date-time description: | optional

Timestamp of the original request. Format RFC 3339, section 5.6: `YYYY-MM-DDThh:mm:ssZ` (UTC) or `YYYY-MM-DDThh:mm:ss±hh:mm`. example: '2020-09-19T11:16:36+00:00' current: type: object description: | necessary

All currently available data to which the suggestion relates. properties: shopUid: type: string maxLength: 100 description: | necessary

uid of the shop to which the suggestion relates. example: '0erPBQ5neagUElWYBK9ozG' merchantUid: type: string maxLength: 100 description: | necessary

uid of the merchant to which the suggestion relates. example: '538VqZ4gn33tVJJWEYa8d3@gb' transaction: type: object description: | important

The transaction (card transaction, bank transfer, etc.) to which the suggestion relates. example: merchantId: '84591982' posId: 'TES44278' description: 'TESCO STORES 2789' zip: 'N1 9DX' city: 'LONDON' country: 'GB' mcc: '5411' suggestion: type: string maxLength: 5000 description: | necessary

Text of the suggestion. It should clearly say what needs to be fixed.
Example: Wrong shop, should be Tesco store on 2 Monck St, London. example: 'Wrong shop, should be Tesco store on 2 Monck St, London.' source: type: string maxLength: 20 enum: - user - partner description: | necessary

Original author of the suggestion: * user - end user (e.g. client of a bank) * partner - Tapix customer who is directly calling the API (e.g. a bank). example: 'user' required: - suggestion - source CO2Footprint: type: object description: Contains the carbon footprint information.
This feature is not enabled by default and can be activated upon request. properties: unit: type: string enum: - 'kg' description: Unit of CO2 footprint. example: 'kg' value: type: number description: Value of CO2 footprint. example: 20.67 PaymentGateway: type: object allOf: - type: object properties: uid: type: string maxLength: 100 description: Unique identifier of the payment gateway. example: '111dasbd7sdf3225fsd22b' - $ref: '#/definitions/PaymentGatewayWithoutID' PaymentGatewayWithoutID: type: object properties: name: type: string maxLength: 255 example: 'PayPal' url: type: string description: Website URL of the payment gateway. example: 'https://paypal.com' logo: type: string maxLength: 1023 example: 'https://s3.eu-central-1.amazonaws.com/files.node-prod.dateio.cz/m/111dasbd7sdf3225fsd22b/l#163b947bad8801e8787bb0e2cfcbef1b92901049' description: The logo of the payment gateway. The logo should be downloaded by the client using the URL returned in the response or stored in the database. The returned URL includes an appended etag after a '#' symbol, which serves as a unique identifier for the stored logo. PaymentGatewayComplete: type: object allOf: - $ref: '#/definitions/PaymentGatewayWithoutID' FindResultPaymentGateway: type: object description: Contains `uid` of the payment gateway. properties: uid: type: string maxLength: 100 description: Unique identifier of the payment gateway. example: '111dasbd7sdf3225fsd22b' FindResultSubscription: type: object description: Indicates if a transaction is a recurring payment. Contains details about billing frequency and the next scheduled payment.
This feature is not enabled by default and can be activated upon request. properties: automaticCharging: type: boolean description: Indicates whether the payment is automatically charged or manually paid. example: true clientServiceUid: type: string maxLength: 100 description: | Stable identifier for one client and one service (service = merchant + frequency). It can be used to group transactions related to the same subscription service. The same service billed at a different frequency is reported under a different identifier.

Returned only when the request contains `clientId` (or `sourceId` when no `clientId` is sent). example: '4ec71da9f056f76b037213' frequency: type: string description: The billing frequency of the subscription. example: 'Monthly' nextAmountType: type: string description: | Indicates the expected nature of the next payment amount for the subscription: * Same - The next amount is expected to be the same as the current one. * Approximate - The next amount might vary slightly (e.g., due to usage-based billing, minor price adjustments). * Unknown - The next amount cannot be reliably predicted. enum: - Same - Approximate - Unknown example: Same nextBillingDate: type: string format: date description: The date of the next scheduled billing in `YYYY-MM-DD` format. example: '2024-10-01'