API guide
Hi 👋 Welcome to TransactionLink's API docs. Feel free to try out our API in sandbox mode if you
haven't done so yet.
We are building TransactionLink using an API-first approach - our starting point is always the connectivity we can offer, and then we stitch together the product to make it work. You can read more about this approach here.
In practice it means we will inform you in advance about the changes we introduce to our API to get your systems ready for it. We will also expose new endpoints to collect feedback from you before we release it to production.
We do our best to make the product as usable as possible. Feel free to send us feedback about this page, our API in general or if you just want to have a chat 🍺.
We can't wait to see what you'll build!
We are building TransactionLink using an API-first approach - our starting point is always the connectivity we can offer, and then we stitch together the product to make it work. You can read more about this approach here.
In practice it means we will inform you in advance about the changes we introduce to our API to get your systems ready for it. We will also expose new endpoints to collect feedback from you before we release it to production.
We do our best to make the product as usable as possible. Feel free to send us feedback about this page, our API in general or if you just want to have a chat 🍺.
We can't wait to see what you'll build!
Overview
TransactionLink API lets you import various types of information stored on individual and company
bank accounts through a single, reliable connection. The entire API is divided into products that
serve different types of data. The products currently available are:
Additionally, you can upgrade any product to Real time to
receive fresh data. In practice, we most commonly observe our customers to use the Real time upgrade
on the Transactions product, however you can use any of the other products with Real time
functionality too.
All TransactionLink products can be accessed via (public) APIs that is designed around REST. The API returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Our API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported. All requests must include a Content-Type of application/json and the body must be valid JSON.
All TransactionLink products can be accessed via (public) APIs that is designed around REST. The API returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Our API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported. All requests must include a Content-Type of application/json and the body must be valid JSON.
Python
Was this section helpful?
Authorization
To get access to our API you need to go through the registration process in our API
panel. To make a first API call, create an application in the panel and link products that you
want to use
.
After you register and successfully create an application, you can find your secret code in the Developers tab of the API panel. The generated secret code will work as the API KEY. The key must be placed in the header of every request as X-API-KEY.
Please note, you can only access endpoints associated with products that you linked with your application. For legal reasons, we need to verify your eligibility to access these endpoints and we do it by checking your API-KEY.
Keep your API KEY safe and don't share it with any unauthorized parties.
After you register and successfully create an application, you can find your secret code in the Developers tab of the API panel. The generated secret code will work as the API KEY. The key must be placed in the header of every request as X-API-KEY.
Please note, you can only access endpoints associated with products that you linked with your application. For legal reasons, we need to verify your eligibility to access these endpoints and we do it by checking your API-KEY.
Keep your API KEY safe and don't share it with any unauthorized parties.
Example headers
{
# Informs server about type of data to be parsed
"Content-Type": "application/json"
# Secret code generated for your application in API panel
"X-API-KEY": "dff08d9b-6604-1d63-b48c-d95028193d09"
}
Was this section helpful?
Request ID (optional)
Every API call we respond with has a unique request identifier associated with it. You can find it
in response header.
Additionally, we support your own request ID allocation if this accommodates your particular case better. You can include this parameter in header as X-Request-ID, so that we can track your issue in our API and provide you with support swiftly.
The request ID we send in response is of standard uuid version-1 format. You will also be required to submit your own request ID in this format for us to understand it.
Additionally, we support your own request ID allocation if this accommodates your particular case better. You can include this parameter in header as X-Request-ID, so that we can track your issue in our API and provide you with support swiftly.
The request ID we send in response is of standard uuid version-1 format. You will also be required to submit your own request ID in this format for us to understand it.
Request ID in header example
{
"X-Request-ID": "dff08d9b-6604-1d63-b48c-d95028193d09"
}
Was this section helpful?
Initialize access
As you connect with TransactionLink API, you will be using our web or mobile widget embedded on your
premises to onboard clients and pull their banking data. Regardless of products you decide to use
for your application, any user coming to you will need to follow the same first step - initialize
access to their bank account.
Before you make your first API call, you need to make sure that you provide us with a URL for initial data import. This is the address where we will be sending the data you request, right after the user authorizes access to their account, regardless of the product you chose for your application. You can specify the URL in your admin panel's Developer tab, under Notifications URL field.
After you specify the URL and have obtained your secret code from the panel, you can initialize access to client's bank account via the /client-management/authorize endpoint.
Please note that in order to send a correct request to that endpoint, you need to include the exact same request payload as seen on the example on the right (
After the request is accepted, our API will respond with a client reference number and an authorization url. You need to use the url to redirect client to the selected bank's page where they need to provide bank details to authorize access to their account.
After client successfully authorizes access to their account, he/she becomes active. To signify this, you will receive an event notification to the Notifications URL address you specified earlier.
Once the authorization process is complete, you can immediately start requesting user account data you require.
Before you make your first API call, you need to make sure that you provide us with a URL for initial data import. This is the address where we will be sending the data you request, right after the user authorizes access to their account, regardless of the product you chose for your application. You can specify the URL in your admin panel's Developer tab, under Notifications URL field.
After you specify the URL and have obtained your secret code from the panel, you can initialize access to client's bank account via the /client-management/authorize endpoint.
Please note that in order to send a correct request to that endpoint, you need to include the exact same request payload as seen on the example on the right (
--data-raw). This payload specifies features of client's bank
account data to be made available through the connection. We are working on making this much more
user-friendly, but for the time being this needs to be provided in the request for banks to accept
it.
Request payload schema
bankName string
Name of the bank the client is requesting to authorize with. By design, the names of the
banks are provided as their full name, with no capitals or special symbols. Please refer to
API housekeeping section to view the full list
of banks.
scopeTimeLimit string (timestamp)
The date to which client authorizes access to their bank account. Legally, you are obliged
to ask the client for strong re-authorization of access to bank account if you want to
monitor the account for more than 90 days. The format for this field follows the ISO 8601 is:
YYYY-MM-DDTHH:MM:SS.mmmZ.
maxAllowedHistoryLong int
Number of days into the past, from which you want to obtain data (applicable mostly to
transactions). Maximum number of days is 1460. The default number of days is 365.
usageLimit string
Specifies the type of access to data. It can be one of
single (for one-off permission to access data) or multiple (for a period of time specified by scopeTimeLimit).
After the request is accepted, our API will respond with a client reference number and an authorization url. You need to use the url to redirect client to the selected bank's page where they need to provide bank details to authorize access to their account.
Response schema
clientRef string
Unique client ID in uuid v4 format.
redirectUri string
URL provided by the bank where client can authorize their access to bank account.
After client successfully authorizes access to their account, he/she becomes active. To signify this, you will receive an event notification to the Notifications URL address you specified earlier.
Event notification schema
eventType string
Event type. Currently only
NEW_ACTIVE_CLIENT is supported.
clientRef string
Unique client ID in uuid v4 format.
timestamp string (timestamp)
Exact timestamp of the event.
error string
Error content, if one occurs.
Once the authorization process is complete, you can immediately start requesting user account data you require.
Initialize access request
curl --request POST -k "https://sandbox.transactionlink.io/client-management/authorize" \
--header "X-API-KEY: 75614757-ff53-1c52-abb5-4c668f2c6dc6" \
--header "X-Request-ID: " \
--header "Content-Type: application/json" \
--data-raw "{
"bankName": "alior",
"maxAllowedHistoryLong": 365,
"scopeTimeLimit": "2020-08-20T09:49:29.917Z",
"usageLimit": "multiple"
}"
Initialize access response
{
"clientRef": "ab2d237d-ece7-41d1-a0b1-d1fcf5a357f2",
"redirectUri": "https://oauthdemo.developer.aliorbank.pl/login?refConsentHash=6cd581a002177d08c8ade6b256bc90844bce9554e58c8e5826bedbc3740b63e5-9dc07b01e3254ab2a3f52229fb54770ad0d247b12c7b9089d0764a9368a8893d"
}
Event notification example
{
"eventType": "NEW_ACTIVE_CLIENT"
"clientRef": "ab2d237d-ece7-41d1-a0b1-d1fcf5a357f2"
"timestamp": "2020-05-20T09:49:29.917Z"
"error": ""
}
Was this section helpful?
Products
The entire TransactionLink API is divided into products, each serving a distinct business
purpose. The concept of products has been introduced in the design of our API in order to
structure the responses we can serve to you in a logical manner, rather than dumping all the
data available from a bank account in one lump file.
The products available on our API are: In order to start making requests under a product you need to enable that product for your application in the admin panel. Failure to do so will result in errors.
Please note that, by default, we exercise our duty of care towards all our customers. We feel that providing you with all the data available on bank accounts may not only confuse you but also can put your project at danger of becoming targetted by cyberattacks. If you are building a new loyalty app you probably don't need to verify an individual's address of residence or identity data - transaction history is probably where you want to focus most of your efforts. Equally, if you want to use our API as a KYC tool you probably don't want to be receiving megabytes of transaction data but only a simple confirmation of identity. This in another reason why we operate on the premise of products and provide you only the data you explicitly require.
Moreover, as a regulated entity we have a legal duty to allow you to import only the data your company or project is eligible for. For example, if you are a small, unregulated startup (i.e. one without a TPP license) we will not be able to provide you with full, unfiltered transaction history of an individual's bank account. You can learn more about the exact fields you can receive from us depending on your type of entity in the Legal tab in your admin panel.
In sandbox mode, you can access all the products available on our API without limitations. You can test your API calls and play around to test your code. However, once you are ready to move to production, we may need to perform a background check on your company depending on the products you will be using on our API (please refer to the Legal tab in your admin panel for more details).
The products available on our API are: In order to start making requests under a product you need to enable that product for your application in the admin panel. Failure to do so will result in errors.
Please note that, by default, we exercise our duty of care towards all our customers. We feel that providing you with all the data available on bank accounts may not only confuse you but also can put your project at danger of becoming targetted by cyberattacks. If you are building a new loyalty app you probably don't need to verify an individual's address of residence or identity data - transaction history is probably where you want to focus most of your efforts. Equally, if you want to use our API as a KYC tool you probably don't want to be receiving megabytes of transaction data but only a simple confirmation of identity. This in another reason why we operate on the premise of products and provide you only the data you explicitly require.
Moreover, as a regulated entity we have a legal duty to allow you to import only the data your company or project is eligible for. For example, if you are a small, unregulated startup (i.e. one without a TPP license) we will not be able to provide you with full, unfiltered transaction history of an individual's bank account. You can learn more about the exact fields you can receive from us depending on your type of entity in the Legal tab in your admin panel.
In sandbox mode, you can access all the products available on our API without limitations. You can test your API calls and play around to test your code. However, once you are ready to move to production, we may need to perform a background check on your company depending on the products you will be using on our API (please refer to the Legal tab in your admin panel for more details).
Transactions
After your client successfully authorizes access to account and becomes active, we hook up to their
bank account and let you pull their transaction history data. One of the best things about our API
is that you can request transaction data at any time, setting any boundaries, as frequently as you
need. You can think about it as if you were just querying your own SQL database.
The data received from banks is usually very messy so, before we send it to you, we perform a data clean to ensure every field contains correct data. The data fields we return through our API are standardized across all the financial institutions we support.
In order to retrieve client's transactions, use the GET /account-information-service/clients/{clientRef}/transactions endpoint. You will need to provide the
If you don't know the clients account ids, you can check them by using the GET /account-information-service/clients/{clientRef}/accounts endpoint.
We also provide endpoint, where you can check more details about client's account and some technical informations like the date of last refresh of transactions and balance data. Just make call to /account-information-service/clients/{client_id}/accounts/{account_id} with the account id which belongs to your client.
The data received from banks is usually very messy so, before we send it to you, we perform a data clean to ensure every field contains correct data. The data fields we return through our API are standardized across all the financial institutions we support.
In order to retrieve client's transactions, use the GET /account-information-service/clients/{clientRef}/transactions endpoint. You will need to provide the
clientRef parameter that
was assigned to client during access initialization
process. As a client might own multiple accounts with the same bank, you will need to specify the
account you want to retrieve data from. You need to put in the account number in the accountId field in the request.
If you don't know the clients account ids, you can check them by using the GET /account-information-service/clients/{clientRef}/accounts endpoint.
We also provide endpoint, where you can check more details about client's account and some technical informations like the date of last refresh of transactions and balance data. Just make call to /account-information-service/clients/{client_id}/accounts/{account_id} with the account id which belongs to your client.
Transactions query parameters
date_from string (optional)
The starting date from which you want to see transaction data. The field has the following
format: YYYY-MM-DD.
date_to string (optional)
The end date to which you want to see transaction data. The field has the following format:
YYYY-MM-DD.
account_id string (optional)
Account id in uuid v4 format. If you provide this parameter, you can select transactions
from specific account.
fields string (optional)
Lets you define the fields you want returned in your request. The default response provides
all fields. The fields can be listed as a comma-separated sequence. Fields sequence order
does not matter.
Transactions response schema
accountNumber string
Client's account number in IBAN format.
amount number
Value of the transaction. Always positive, regardless of transaction side (see
category below to resolve).
category string
Defines transaction side, i.e. who made the transaction to whom. It can be either
debit for transactions coming out of the client's account,
or credit for incoming transactions.
bookingDate string
The date of transaction occuring (not necessarily clearing). The field has the following
format: YYYY-MM-DD.
currency string
Transaction currency in the 3-letter format.
description string
Any additional information about the transaction, as seen on the bank statement.
sideAccount string
Debitor's or creditor's account number in IBAN format.
sideAddress string
Debitor's or creditor's address.
sideBankName string
Debitor's or creditor's bank with which he/she holds an account.
sideName number
Debitor's or creditor's full name as appears on the bank statement.
status string
Specifies current transaction status. It can be one of
done, pending or rejected.
tradeDate string
Transaction clearing date. This field's format is YYYY-MM-DD.
Retrieve client accounts example request
curl --request GET "https://sandbox.transactionlink.io/account-information-service/clients/47a51e96-fda8-4f1c-aa23-7272a0c62d95/accounts" \
--header "X-API-KEY: 9cc25a49-6c59-10d1-b62a-e84b85ccad49" \
--header "X-Request-ID: "
Retrieve client accounts example response
{
"number": "PL63249000050000400030900682",
"state": "active",
"accountId": "35216315-e913-46b5-81ad-5544fbcbd122"
},
{
"number": "PL50249000050000400076134538",
"state": "active",
"accountId": "0e559266-a659-4927-aaec-315119d51bf3"
}
Retrieve client's accounts details request
curl --request GET "https://sandbox.transactionlink.io/account-information-service/clients/47a51e96-fda8-4f1c-aa23-7272a0c62d95/accounts/60a51ee4-fda8-4f1c-aa23-8972a0cffd95" \
--header "X-API-KEY: 9cc25a49-6c59-10d1-b62a-e84b85ccad49" \
--header "X-Request-ID: "
Retrieve client's accounts details response
{
"availableBalance": -0.28,
"bookingBalance": 66370.14,
"currency": "PLN",
"description": "Rachunek oszczednosciowo - rozliczeniowy",
"holderType": "individual",
"lastBalanceRefresh": "2020-06-15T12:50:26.828099Z",
"lastTransactionsRefresh": "2020-06-15T12:50:30.340612Z",
"number": "PL63249000050000400030900682",
"state": "active",
"type": "Konto Osobiste"
}
Transactions example request
curl --request GET "https://sandbox.transactionlink.io/account-information-service/clients/47a51e96-fda8-4f1c-aa23-7272a0c62d95/transactions?date_from=2020-01-24&date_to=2020-05-26&fields=amount,category,currency" \
--header "X-API-KEY: 9cc25a49-6c59-10d1-b62a-e84b85ccad49" \
--header "X-Request-ID: "
Client transactions example response
{
"accountNumber": "PL50249000050000400076134538",
"amount": 25702.45,
"bookingDate": "2020-02-21",
"category": "DEBIT",
"currency": "EUR",
"description": "Automotive",
"sideAccount": "PL99857590822027445028075943",
"sideAddress": "8 Clemons Lane",
"sideBankName": "mBank",
"sideName": "Trump, Donald",
"status": "done",
"tradeDate": "2020-02-13"
}
Was this section helpful?
Balance
Balance product allow you to check current available balance and booking balance
on the client's account. If the client has more than one account in bank,
you'll be able to see the current balance on each of them.
To get current balance you need to make request as follow: GET /account-information-service/clients/{clientRef}/accounts/balances endpoint. Please note, that you need to specify the
To get current balance you need to make request as follow: GET /account-information-service/clients/{clientRef}/accounts/balances endpoint. Please note, that you need to specify the
clientRef field generated in access initialization process to access the data.
Balance response schema
accountNumber string
Client's account number(s) in IBAN format.
availableBalance number
Available funds on client's account. Funds can be withdrawn or transferred.
bookingBalance number
Booked balance for performing the transaction
currency string
3 letter ISO currency code in uppercase
Example balance request
curl --request GET "https://sandbox.transactionlink.io/account-information-service/clients/0563591d-9530-4ea1-953a-5991df986b99/accounts/balances" \
--header "X-API-KEY: 4f7a4cf2-0706-1e64-8854-e63b70daa6c2" \
--header "X-Request-ID: "
Example balance response
[
{
"accountNumber": "PL50249000050000400076134538",
"availableBalance": 87272.51,
"bookingBalance": 96015.39,
"currency": "EUR"
},
{
"accountNumber": "PL63249000050000400030900682",
"availableBalance": -0.28,
"bookingBalance": 66370.14,
"currency": "PLN"
}
]
Was this section helpful?
Identity
Identity product gives you access to client's identity data stored on their bank account. In order
to use this product, please make sure you have activated the product in your application in admin
panel.
To access identity data use the /account-information-service/clients/{clientRef}/identity endpoint. Please note, that you need to specify the
The response schema is self-explanatory from the example on the right.
To access identity data use the /account-information-service/clients/{clientRef}/identity endpoint. Please note, that you need to specify the
clientRef field generated in access initialization process to access the data.
The response schema is self-explanatory from the example on the right.
Example identity request
curl --request GET -k "https://sandbox.transactionlink.io/account-information-service/clients/53db0b3d-593c-49a2-b4c1-5edba84c3cd0/identity" \
--header "X-API-KEY: 75614757-ff53-1c52-abb5-4c668f2c6dc6"
Example identity response
{
"address": "464 Parkside Parkway",
"city": "Vancouver",
"country": "United States",
"firstName": "Satoshi",
"lastName": "Nakamoto",
"postalCode": "98664"
}
Was this section helpful?
Authentication
Authentication product allows you to verify client's authenticity by checking their bank account
number and full name associated with it.
To authenticate client use the GET account-information-service/clients/{clientRef}/authentication endpoint. Please note, that you need to specify the
To authenticate client use the GET account-information-service/clients/{clientRef}/authentication endpoint. Please note, that you need to specify the
clientRef field generated in access initialization process to access the data.
Authentication response schema
number string
Client's account number(s) in IBAN format.
currency string
3 letter ISO currency code in uppercase
description string
Short description about client's account
holderType string
Account holder type: individual person or corporation
type string
Account's type name
firstName string
Clients first name as appears on bank statement.
lastName string
Clients last name as appears on bank statement.
Example authentication request
curl --request GET -k "https://sandbox.transactionlink.io/account-information-service/clients/d9b73a16-0aac-42a7-9fb0-b81c7145de76/authentication" \
--header "X-API-KEY: 75614757-ff53-1c52-abb5-4c668f2c6dc6" \
--header "X-Request-ID: "
Example authentication response
# This particular client owns two accounts in the same bank
{
"accounts": [
{
"currency": "EUR",
"description": "Rachunek oszczednosciowo - rozliczeniowy",
"holderType": "individual",
"number": "PL50249000050000400076134538",
"type": "Konto Walutowe"
},
{
"currency": "PLN",
"description": "Rachunek oszczednosciowo - rozliczeniowy",
"holderType": "individual",
"number": "PL63249000050000400030900682",
"type": "Konto Osobiste"
}
],
"firstName": "Isaac",
"lastName": "Newton"
}
Was this section helpful?
Real time data
TransactionLink API lets you set up a webhook for real time notifications about changes on clients'
accounts. Once a new event occurs, we can send you a notification informing about it.
In order to use the real time functionality, you need to enable it in your admin panel, under the App details section. You can use the real time functionality for any product our API provides you, but it makes the most sense to use it with Transactions product.
To start receiving real time data you need to provide a URL to which we will be sending the fresh data, once we notice a change on client's account. You need to specify that URL address under the Real time data URL field in the Developers tab on your admin panel.
Please note that real time functionality on Identity and Authentication products follow the same logiacal pattern. We will notify you of changes on parameters associated with the products only once we observe a change. This means we will send you a notification about updated identity details only once the client introduces a change to them on their bank account.
The real time data incoming to the URL you specified with be of identical schema as regular products, with the only difference being an extra
With real time functionality enabled, we will be sending you all changes on client's bank account by default. You can modify what we will be notifying you about using our Filters feature.
In order to use the real time functionality, you need to enable it in your admin panel, under the App details section. You can use the real time functionality for any product our API provides you, but it makes the most sense to use it with Transactions product.
To start receiving real time data you need to provide a URL to which we will be sending the fresh data, once we notice a change on client's account. You need to specify that URL address under the Real time data URL field in the Developers tab on your admin panel.
Please note that real time functionality on Identity and Authentication products follow the same logiacal pattern. We will notify you of changes on parameters associated with the products only once we observe a change. This means we will send you a notification about updated identity details only once the client introduces a change to them on their bank account.
The real time data incoming to the URL you specified with be of identical schema as regular products, with the only difference being an extra
clientRef field
specifying the client, whose data you just received.
With real time functionality enabled, we will be sending you all changes on client's bank account by default. You can modify what we will be notifying you about using our Filters feature.
Real time incoming transaction example
{
# An additional clientRef field. The rest is identical with transaction request
"clientRef": "d9b73a16-0aac-42a7-9fb0-b81c7145de76",
"amount": 25.45,
"bookingDate": "2020-02-21",
"category": "DEBIT",
"currency": "EUR",
"description": "Grocery",
"sideAccount": "PL99857590822027445028075943",
"sideAddress": "8 Clemons Lane",
"sideBankName": "mBank",
"sideName": "Trump, Donald",
"status": "done",
"tradeDate": "2020-02-13"
}
Was this section helpful?
Filters
Filters let you set boundaries on the data that appears on clients' bank accounts and which data you
will receive to your URL address. Please note that filters only work for real time data
functionality enabled. If you want to impose certain boundary conditions on client's past
transactions, you should be using our Transactions product (inquirying our API about specific data
from the past is a built-in functionality).
In order to start using filters, you need to specify the conditions that are of interest to you in the admin panel, under the Filters tab. This is currently the only way to set up filters for your application.
For the time being, we only let you set a single filter for all clients in one application but we are working to extend that functionality. We also only let you use the AND operand and use the fields provided.
In order to start using filters, you need to specify the conditions that are of interest to you in the admin panel, under the Filters tab. This is currently the only way to set up filters for your application.
For the time being, we only let you set a single filter for all clients in one application but we are working to extend that functionality. We also only let you use the AND operand and use the fields provided.
Was this section helpful?
Testing real time data
Real time data functionality is notoriously hard to test - how can you know if your setup is correct
if there is no incoming transactions to test it on? For exactly this reason we prepared 2 ways for
you to check if your code runs correctly.
You will need to create at least one client with a client reference number in order to generate a test transaction for him if you want to create your custom transaction (see POST dummy transaction below).
Naturally, this functionality is only available in sandbox mode.
1. Add dummy client in panel
In your admin panel you can head to the Clients tab. In there you will find a list of clients using your application via TransactionLink API. In sandbox mode this table is empty by default but you can add dummy clients to test your code. We have created pre-made clients for you to test your functionality - simply add them to your client list to test your code on them. You will find their specific behaviour pattern in the client description.You will need to create at least one client with a client reference number in order to generate a test transaction for him if you want to create your custom transaction (see POST dummy transaction below).
2. POST dummy transaction
You can check your setup by directly posting a transaction with your own parameters to our API. The structure of the call is exactly the same as the structure of a transaction request, only swapping the GET method for POST. You will need to specify all the fields a transaction json normally returns. If everything is done correctly, you will receive a notification confirming transaction generation.Naturally, this functionality is only available in sandbox mode.
Example POST call to create a dummy transaction
curl --request POST -k "https://sandbox.transactionlink.io/account-information-service/clients/ea06d60e-cc50-41ff-9824-f51cc76d9546/accounts/255a8f8c-ef5f-4719-b62c-e112e4b6aac3/transactions" \
--header "X-API-KEY: 75614757-ff53-1c52-abb5-4c668f2c6dc6" \
--header "X-Request-ID: " \
--header "Content-Type: application/json" \
--data-raw "{
"amount": 72.45,
"bookingDate": "2020-02-21",
"category": "DEBIT",
"currency": "EUR",
"description": "Beauty",
"externalId": "7917",
"sideAccount": "PL99857590822027445028075943",
"sideAddress": "8 Clemons Lane",
"sideBankName": "mBank",
"sideName": "Corleone, Vito",
"status": "done",
"tradeDate": "2020-02-13"
}"
POST call response
{
"message": "Notification has been sent",
"code": 200
}
Was this section helpful?
Versioning
The current version of TransactionLink API is v1.1.0.
We are versioning our api in accordance with MAJOR.MINOR.PATH format which is taken from semantic versioning.
Version is being updated with following rules:
We are versioning our api in accordance with MAJOR.MINOR.PATH format which is taken from semantic versioning.
Version is being updated with following rules:
- MAJOR part when we make incompatible API changes
- MINOR part when we add functionality in a backwards compatible manner
- PATCH part when we make backwards compatible bug fixes.
Accept-Version header
Accept-Version string in format vMAJOR
MAJOR version incremented when we make backwards-incompatible API changes.
example: v1
example: v1
Version response schema
appId string (uuid)
Identifier of api definition
example: 46785659-c794-440c-93fb-477a7043cd24
example: 46785659-c794-440c-93fb-477a7043cd24
releaseDate string
Release date of api version. This field's format is YYYY-MM-DD.
example: 25.06.2020
example: 25.06.2020
version string
Returns the version of API you are currently working on in vMAJOR.MINOR.PATH format
example: v1.0.0
example: v1.0.0
Version request
curl --request
GET "https://sandbox.transactionlink.io/health" \
--header "Accept-Version: "
Version response
{
"apiId": "46785659-c794-440c-93fb-477a7043cd24",
"releaseDate": "25.06.2020",
"version": "v1.0.0"
}
Was this section helpful?
API Housekeeping
Here you can find all the requests regarding the general condition of the API.
/account-information-service/banks response schema
id int
Bank's unique identification number.
name string
Bank's name. This name can be used throughout the API interchangably with
id.
state string
Bank's connection availability. It can take the value of either
active
or inactive.
/health response schema
status string
Returns current API health status. It can take the value of either
pass or fail.
Retrive available banks
curl --request GET "https://sandbox.transactionlink.io/account-information-service/banks" \
--header "X-API-KEY: " \
--header "X-Request-ID: 9cc25a49-6c59-10d1-b62a-e84b85ccad49"
Available banks
[{
"id": 1,
"name": "alior",
"state": "active"
},
{
"id": 2,
"name": "idea",
"state": "active"
},
{
"id": 3,
"name": "mbank",
"state": "active"
},
{
"id": 4,
"name": "santander",
"state": "active"
},
{
"id": 5,
"name": "millennium",
"state": "active"
},
{
"id": 6,
"name": "bnpparibas",
"state": "active"
},
{
"id": 7,
"name": "bosbank",
"state": "active"
},
{
"id": 8,
"name": "getinnoble",
"state": "active"
},
{
"id": 9,
"name": "pekaobp",
"state": "active"
},
{
"id": 10,
"name": "pekaosa",
"state": "active"
},
{
"id": 11,
"name": "citihandlowy",
"state": "active"
}]
Example GET /health request
curl -X GET "https://sandbox.transactionlink.io/health"
-H "accept: */*"
-H "X-API-KEY: 9cc25a49-6c59-10d1-b62a-e84b85ccad49"
Example GET /health response
{
"status": "pass"
}
Was this section helpful?
Testing with Postman
For testing purpose, you can easily import our entire API definitions (We are using OpenAPI
Specification in v3.0 version) into Postman.
Currently you can find it on https://sandbox.transactionlink.io/openapi.json
in
JSON format and
on https://sandbox.transactionlink.io/openapi.yaml in YAML format.
Postman supports both YAML and JSON formats. In the Postman app, click 'Import' to bring up the following screen:
You can choose to upload a file, enter a URL, directly copy or drag and drop our api definition. When importing OpenAPI definitions, Postman follows the endpoint hierarchy defined in the specification to create a collection organized into folders.
After the specification have been successfully imported into the Postman application, you will see a collection of calls to our API. At this point, you only have to provide the api key to the header of each call. However, the most convenient solution is to save it in the collection's environment variables.
Postman supports both YAML and JSON formats. In the Postman app, click 'Import' to bring up the following screen:
You can choose to upload a file, enter a URL, directly copy or drag and drop our api definition. When importing OpenAPI definitions, Postman follows the endpoint hierarchy defined in the specification to create a collection organized into folders.
After the specification have been successfully imported into the Postman application, you will see a collection of calls to our API. At this point, you only have to provide the api key to the header of each call. However, the most convenient solution is to save it in the collection's environment variables.
Was this section helpful?
Error handling
Whenever a requested resource is not available or API call is incorrect you will get
HTTP response with status higher than or equal to 400 with a specific payload in JSON format.
Our error structure follow the rules described in RFC7807
which defines a Problem JSON object and the media type application/problem+json
There are two http error code ranges you can expect:
There are two http error code ranges you can expect:
- 4xx error status codes indicate error on the client side.
- 5xx error status codes indicate error on the TransactionLink side. We would be very grateful if you contact us immediately when you will get such an error.
Error response schema
type string (uri)
An absolute URI to the documentation section which is describing problem type.
default: https://doc.transactionlink.io
example: https://doc.transactionlink.io/#item-rtd
default: https://doc.transactionlink.io
example: https://doc.transactionlink.io/#item-rtd
title string
Summary of the problem type.
example: Service Unavailable
example: Service Unavailable
status int
The HTTP status code generated by the origin server for this occurrence
of the problem.
example: 404
example: 404
detail string
Contains more detailed information about occurence of the problem
example: Application is not authorized to the balance product. Enable access to this product in the panel.transactionlink.io
example: Application is not authorized to the balance product. Enable access to this product in the panel.transactionlink.io
instance string (uri)
A relative URI reference that identifies the specific occurrence of the problem.
example: /account-information-service/clients/2a002bd3-10f3-4a98-a5a8-a2e00200314e/accounts
example: /account-information-service/clients/2a002bd3-10f3-4a98-a5a8-a2e00200314e/accounts
external fields string
Problem type definitions may extend the problem details object with
additional fields and provide more informations about occurence of the problem.
HTTP Error codes
400 Bad Request
The server could not understand the request due to invalid syntax.
401 Unauthorized
Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated".
That is, the client must authenticate itself to get the requested response.
404 Not Found
The server can not find the requested resource. In the browser, this means the URL is not recognized.
In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client.
This response code is probably the most famous one due to its frequent occurrence on the web.
405 Method Not Allowed
The request method is known by the server but has been disabled and cannot be used.
For example, an API may forbid DELETE-ing a resource.
The two mandatory methods, GET and HEAD, must never be disabled and should not return this error code.
413 Payload Too Large
Request entity is larger than limits defined by server;
the server might close the connection or return an Retry-After header field.
415 Unsupported Media Type
The media format of the requested data is not supported by the server, so the server is rejecting the request.
429 Too Many Requests
The user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server Error
The server has encountered a situation it doesn't know how to handle.
501 Not Implemented
The request method is not supported by the server and cannot be handled.
The only methods that servers are required to support (and therefore that must not return this code) are GET and HEAD.
502 Bad Gateway
This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.
503 Service Unavailable
The server is not ready to handle the request.
Common causes are a server that is down for maintenance or that is overloaded.
Note that together with this response, a user-friendly page explaining the problem should be sent.
This responses should be used for temporary conditions and the Retry-After: HTTP header should, if possible,
contain the estimated time before the recovery of the service.
The webmaster must also take care about the caching-related headers that are sent along with this response,
as these temporary condition responses should usually not be cached.
Was this section helpful?