general
Overview
Account Information API is available for authorized Account Information Service Providers under PSD2 in the EU and Open Banking in the UK, and other regulated Third Party Providers and Service Providers in countries where there is no open banking regulation.
Account Information API aims to make requesting financial information from various providers as simple as a cURL. The API allows you to perform several important procedures, such as:
- Securely import bank data from multiple countries;
- Import data from online payment systems (PayPal, Yandex Money, etc.);
- Automatically synchronize accounts and transactions on a daily basis;
- Automatically categorize financial transactions;
- Keep a well-organized and up-to-date list of currency rates.
If you have any questions regarding the integration and use of Account Information API, feel free to contact us.
Integrations
The Salt Edge platform is incredibly easy to integrate with. We’ve built the Salt Edge Connect interface so your application could start importing your users’ financial data in a matter of minutes.
However, if you think your application could benefit more from the native look and feel, you can always contact us, and we can discuss what would be the best solution for your app.
Formats
We use JSON for all the requests and responses, including the errors.
Glossary
Most of the API revolves around several important concepts:
- Country - the country where a provider is located;
- Provider - a bank or an online payments system;
- Required Field - a mandatory field for authentication to a specific provider;
- Interactive Field - an interactive field for authentication to a specific provider;
- Client - an application consuming the Account Information API;
- Customer - an end-user of the client who is consuming the Account Information API;
- Connection - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
- Attempt - an attempt which is created when an end-user connects a financial institution;
- Consent - the permission from an end-user to fetch data;
- Holder Info - information about the account holder;
- Account - one of the accounts associated with a connection. It can be a credit card account, a savings account, one of the online accounts, etc;
- Merchant - a company that sells goods or provides services to the customer;
- Transaction - a single financial movement made within an account;
- Category - one of the personal or business categories that can be assigned to a transaction.
- Currency - string code that is used for an account.
Following the guides
You can start with Authentication and follow the links in the sidebar. If you have any questions, contact us anytime using our contact form.
Quick start
Here are some steps to get you started.
Create api keys
Any request to Account information API is authenticated, so before we are able to fetch any data, we need to create API keys. To do that, visit https://www.saltedge.com/clients/applications first and choose API Keys for the needed application.
Now a new Service
API key can be created. You can leave the “Public key” field blank.
Each request to API is authenticated with an App-id
, and a Secret
. Let’s store them
as environment variables so that all the later requests are authenticated.
$ export APP_ID=YOUR_APP_ID
$ export SECRET=YOUR_APP_SECRET
We can provide examples in various programming languages and SDKs for Android and iOS. Start testing different connection types by using fake data providers to make sure that the application can handle any scenario that might happen with a real data provider (e.g. bank).
Create customer
Before we can create any connections using Account Information API, we need to create a Customer. A Customer in Account Information API is the end-user of your application.
We need to save the Customer id
(in this case “222222222222222222”) because we will use it later to create connections.
$ export CUSTOMER_ID=222222222222222222
See customers reference for Customer related API endpoints.
URL
https://www.saltedge.com/api/v5/customers
https://www.saltedge.com/api/v5/customers
Method
POST
Sample Request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"test1\" \
} \
}" \
https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"test1\" \
} \
}" \
https://www.saltedge.com/api/v5/customers
Sample Response
{
"data": {
"id": "222222222222222222",
"identifier": "test1",
"secret": "SECRET"
}
}
Create connect session
Once we have the Customer id
(in this case id “222222222222222222”), we can create a connection.
There are 2 ways to create connections in Account Information API:
- implementing the UI for creating connections from scratch
- use Salt Edge Connect, which already implemented the interface in a fast and secure way
This is a quick start guide so we will use the second approach. To initiate a connection in Salt Edge Connect, we need to execute a request to create connect session endpoint.
We will receive in response a connect_url
. This is the URL we will visit
to create the connection.
See connect sessions reference for more information and API endpoints related to Salt Edge Connect.
Sample Request
URL
https://www.saltedge.com/api/v5/connect_sessions/create
https://www.saltedge.com/api/v5/connect_sessions/create
Method
POST
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2019-01-01\" \
}, \
\"attempt\": { \
\"return_to\": \"http://example.com/\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2019-01-01\" \
}, \
\"attempt\": { \
\"return_to\": \"http://example.com/\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/create
Sample Response
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Visit Connect Widget URL
Initially, all Account Information API registered clients only have access to fake providers.
Let’s connect one of them. Visit the connect_url
from the previous API response and
search for “Fake Bank Simple”.
Once selected, you will be presented with a form for user credential input, from this provider. Input “username” and “secret” as per the on-screen instructions and press “Proceed”.
After that, we will have to wait for the connection process to finish, and then we can proceed to retrieve all its data via the API.
Fetch connections
In Account Information API, a distinct bank connection is called Connection. Each Account Information API Customer can have multiple Connections. When we visited Salt Edge Connect and connected “Fake Bank Simple”, we effectively created a Connection for our Customer in the system. So to retrieve all data for this Connection, we first need to retrieve the Connection itself.
The response contains an array of entries, each representing a connection to a financial institution.
In our case we will have only one entry.
We need to save the id
(in our case “111111111111111111”) to retrieve its accounts.
$ export CONNECTION_ID=111111111111111111
See connections reference for more information on Connection endpoints.
Only clients who use service
keys can request a list of connections. For more information, please see the authentication guide.
Sample Request
URL
https://www.saltedge.com/api/v5/connections?customer_id={customer.id}
https://www.saltedge.com/api/v5/connections?customer_id={customer.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
Sample Response
{
"data": [
{
"id": "111111111111111111",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"customer_id": "222222222222222222",
...
}
]
}
Fetch accounts for connections
Having the Connection id
, we can retrieve all its accounts.
The response contains an array of entries, each representing an account from a financial institution.
We need to save the id
(in our case “333333333333333333”) to retrieve all transactions for this account.
$ export ACCOUNT_ID=333333333333333333
Sample Request
URL
https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}
https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/accounts?connection_id=$CONNECTION_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/accounts?connection_id=$CONNECTION_ID
Sample Response
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"connection_id": "111111111111111111",
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z",
"extra": {
"client_name": "Fake name"
},
...
}
]
}
Fetch transactions for an account
Having the Connection id
and the Account id
, we can retrieve its transactions.
The response contains an array of entries, each representing a transaction from a financial institution.
See transactions reference for more information on Transaction endpoints.
Sample Request
URL
https://www.saltedge.com/api/v5/transactions?connection_id={connection.id}&account_id={account.id}
https://www.saltedge.com/api/v5/transactions?connection_id={connection.id}&account_id={account.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID
Sample Response
{
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"account_id": "100",
"created_at": "2024-10-06T14:41:04Z",
"updated_at": "2024-10-07T14:41:04Z",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
...
}
]
}
Next steps
- Request Test status to connect real banking institutions.
- Switch to Live status to bring value to your customers globally.
- In this guide, we visited Connect manually. You might want to do that programmatically. For more information see about embedding Salt Edge Connect in your application.
- Since new Account Information API clients are in test mode and have access only to fake providers, the request signature is not required. However, you will need to implement request signing before you are going live. For more information see our signature guide.
- All responses with arrays (like accounts or transactions) are paginated by default, see how to implement it on our pagination guide.
- The recommended way of synchronizing data with Account Information API is via callbacks. That way you won’t have to poll the servers to see whether there is new data available. See our callbacks guide for more information.
Try in Postman
Step 1
Install Postman. You can get it on https://www.getpostman.com/apps.
Step 2
Import the postman collection, click the button below to do that.
Step 3
Account Information API requires APP_ID and SECRET headers in order to authenticate its clients. If you don’t have an API key created yet, you can use our quick start guide to help you create one. Once you have the API key created, you can add its secrets to postman.
Click on the eye on the top right corner and press on “Add” next to “Environments”.
Define variables APP_ID and SECRET with values from the key that you generated on https://www.saltedge.com/clients/profile/secrets, then add the environment.
Once added, you can select it in the top right corner, and all the requests to Account Information API will be authenticated using your API key.
Try in Swagger
Import Swagger JSON, click the button below to do that.
eIDAS Certificates
Open Banking Gateway supports only soft issued eIDAS certificates and Open Banking UK certificates.
For the purpose of identification, ASPSPs(Account Servicing Payment Service Providers) and TPPs(Third Party Providers) shall rely on using eIDAS (electronic Identification, Authentication and trust Services) Certificates for electronic seal and/or for website authentication. Identifying themselves is mandatory for all TPPs that wish to get access to ASPSP’s sandbox, live API, and/or to non-dedicated channel.
eIDAS Certificates are provided by Qualified Trust Service Providers (QTSPs) who are responsible for assuring the electronic identification of signatories and services by using strong mechanisms for authentication, digital certificates, and electronic signatures.
There are two types of eIDAS Certificates:
Qualified Website Authentication Certificates (QWAC)
- identification at the transport layer. QWAC is similar to SSL/TLS with Extended Validation used in Internet for the same purpose. It is used for website authentication, so that ASPSPs and Third Party Providers (TPPs) can be certain of each other’s identity, securing the transport layer. TPP should present its QWAC client certificate towards an ASPSP. The ASPSP can choose between using the ASPSP QWAC server certificate or just an existing SSL/TLS certificate to receive the TPP’s identification request.Qualified Certificate for Electronic Seals (QSEAL)
- identification at the application layer. It is used for identity verification, so that transaction information is protected from potential attacks during or after a communication. This means that the person receiving digitally signed data can be sure who signed the data and that it hasn’t been changed.
To create an eIDAS certificate in the Salt Edge system, you should accomplish the following steps:
a. Go to the Client Dashboard.
b. Go to Settings > eIDAS Certificates
c. Choose the certificate type you want to create (QWAC or QSEAL) and press Generate CSR.
d. Send the CSR to the QTSP (you can get test certificate, or buy production certificate)
e. Get a signed certificate from the QTSP
f. Go to Settings > eIDAS Certificates and press edit on previously created record.
g. Insert the received certificate in PEM format into the form and press update.
h. Choose a certificate that you want to use for identification, press edit and mark it as active.
Client Provider Keys
Open Banking Gateway now supports Account Information and Payment Initiation Services channels, which can be used with PSD2 and Open Banking compliant APIs. The connection to such a provider is possible only if you create a Provider Key (set of credentials) for it. In this case, the API keys for Providers are provided and controlled by you. The number of keys is restricted to 1 per provider. After you create the key, the provider will be accessible as an usual provider.
Salt Edge now supports eIDAS Certificates. Learn more.
Integration
To integrate your App’s individual keys with a Financial Provider (ASPSP in PSD2 terms), follow these steps:
a. Visit Provider Keys page of your Client Dashboard, select a provider you want add your client keys for, read the instructions and complete the form. You can see all the available providers by going to the New
tab on the same page;
b. Proceed by visiting the Connect page and search the provider you just created the key for. It will have a small subscript below the provider name stating that this provider is accessed via YOUR_CLIENT_NAME
;
c. The rest of the process is exactly the same as with usual providers.
Direct API - Salt Edge Connect
In case of using Direct API instead of Salt Edge Connect, it should be ensured that the code handles the new provider’s field nature - dynamic_select
, with its options dynamically generated and sent in an Interactive callback.
Testing
For the purpose of testing individual keys Salt Edge has developed the following list of Fake providers:
fake_client_xf
- requires a username and password (embedded);
Sample key:
client_id: "fake_client_id",
client_secret: "fake_client_secret"
fake_oauth_client_xf
- asks for authorization (OAuth redirect);
Sample key:
client_id: "fake_client_id",
client_secret: "fake_client_secret"
fake_interactive_client_xf
- asks to enter a fake captcha code in addition to a username and a password (embedded).
Sample key:
client_id: "fake_client_id",
client_secret: "fake_client_secret"
fake_interactive_decoupled_client_xf
- decoupled interactive flow (e.g. push notification), asks to wait 10 seconds in Connect widget and then click Proceed to continue in addition to a username and a password (embedded).
Sample key:
client_id: "fake_client_id",
client_secret: "fake_client_secret"
To see these providers in API or Salt Edge Connect, don’t forget to set include_fake_providers
parameter as true on connection create/reconnect or connect session create/reconnect.
All of the providers that are supported in this modes have _client_
in their provider code.
Dynamic Registration
Many banks provide the possibility to dynamically onboard in their API. In this context, Salt Edge has a self-service instrument called Dynamic Registration
that helps its clients to register quicker with the desired banks’ PSD2 and Open Banking channels.
This type of registration can eliminate manual processes including the need to manually create an account in the bank’s developer portal, fill in of data forms, and lengthy emails exchange with the bank.
To find out if a bank has a dynamic registration on Salt Edge’s side, please follow these steps:
a. Sign in to Client Dashboard.
b. Go to Settings > Dynamic registration.
c. Сlick on New registration
and input the desired bank/group name, then complete the form.
d. As a result, you will get a message with the status of Dynamic Registration.
e. On your Provider Keys page all the providers related to that Dynamic Registration will now appear. You will also notice that they’re categorized as Dynamic registration type.
Types of Dynamic registration
Salt Edge supports the following types of dynamic registration:
Dynamic registration that executes an API request
This is the base dynamic registration aimed at consuming the registration API implemented by the bank. Currently, this dynamic registration is separated into three subtypes:
- A registration endpoint that will create a new client and/or application on the bank’s side;
- An API endpoint that will update the eIDAS certificates associated with an already registered TPP;
- A validation endpoint that only verifies the validity of the eIDAS certificate.
Dynamic registration that doesn’t execute an API request
This type of dynamic registration does not contain any request to the bank, and its purpose is solely to help Salt Edge’s clients to add multiple client provider keys at once without the need to do it manually.
For example, the dynamic registration CBI Globe will add the client provider keys to 300+ providers, which means Salt Edge’s clients won’t need to do it manually for every provider separately.
Instruction
Every dynamic registration template contains an instruction which provides more details about its purpose and what additional steps must be done.
Dynamic registration result
Any dynamic registration attempt will result in one of the following:
Successful registration
A pop-up window with a confirmation message will be displayed. The client should save the displayed result for future reference and use.
The Client Provider Keys will be automatically added to all the associated providers.
Note: Sometimes the clients are required to perform additional steps after a successful registration. All additional information will be displayed in the pop-up window or in the initial instruction.
Failed registration
A pop-up window with the error’s details will be displayed.
If the error was raised by the bank and Salt Edge didn’t handle this error yet, the pop-up window will contain also the Date of the request and the response Salt Edge received from the bank.
Depending on the nature of the error, Salt Edge’s clients will have to:
- Adjust some of the information they input in the required dynamic registration fields;
- Address the issue with their Salt Edge representative;
- Contact the bank directly to report the problem.
Most common dynamic registration errors
Validation of the certificates failed
Possible error messages:
- Validation of QWAC failed
- Validation of QSealC failed
- Check on EBA register failed
The bank didn’t accept the TPP’s eIDAS certificates or EBA register check has failed. Hence, the TPP should contact and ask the bank to add their certificate in the bank’s trust store. If this is not the case, the bank will investigate additionally why the certificates were not accepted.
TPP already registered
Possible error messages:
- TPP Application was already registered
- Organization already exists
The TPP is already registered in the bank’s system, either using manual process or via Salt Edge. Hence, the TPP should contact the bank and clarify how to solve the encountered problem. The solution can differ depending on the bank.
Before going LIVE
In order to have your Client account transferred to LIVE mode, the following points should be handled:
- Please provide your Account Manager at Salt Edge with a test account in your app to verify Account Information API integration. If you have multiple apps (Android, iOS, web), a test account should be provided for each platform. In case the applications share the same backend, it’s enough to share an account for one platform.
- Be sure to provide signature in accordance with the instructions.
- If your application is running on mobile devices, desktops, tablets, which are under user’s control, please use app authentication.
- If you’re using Direct API integration (building your own UI for connection to the financial providers), your application should handle correctly all the fake banks.
- In case you are using the Salt Edge Connect widget, your application should handle correctly the following fake banks:
fakebank_simple_xf
,fakebank_interactive_xf
, andfake_oauth_client_xf
. - Your application should not create any duplicated customers and/or connections (i.e. connecting a provider with the same credentials for the same user using a different customer
id
). - The end-user should be able to create, reconnect, refresh and remove connections.
- After deleting a user from your system, you should send a remove request.
- Your application should handle correctly the refresh_timeout in provider entity.
- Your application should show to the end-users the instructions of how to connect providers.
- Your application should not allow usage of disabled providers.
- Your application should use the transactions-duplicate route for a better user experience.
- Your application should handle correctly the ConnectionDuplicated error.
- The Two-factor authentication has to be enabled for your account and all your teammates.
- In order to avoid legal issues with end-users and Data providers, the client should ensure that the end-users read and agree to End User License Terms.
- Be sure to indicate the
Incident reporting Email
in the dashboard settings on the Company page.
As soon as all of the verifications have been made by a Salt Edge representative, the account’s status will be upgraded to live.
Know Your Customer
Account holder info
This feature allows to fetch essential information about customers from their bank accounts
to be further used with the purpose of KYC verification.
Make sure to contact our Sales team to enable holder_info
scope for your client account.
Upon enabling the feature you will receive a holder_info
field inside the provider object.
This field will provide information on the account holder details that can be fetched from the queried provider.
Holder info route returns the information fetched from the customer’s account with the particular provider.
Depending on the provider, the following attributes might be returned in the holder_info
:
names
- returns the name(s) on the customer’s account with the provider, e.g.["John Doe"]
;emails
- returns email(s) registered within customer’s account with the provider, e.g.["john.doe@example.com", "johndoe@gmail.com"]
;phone_numbers
- returns the phone number(s) registered in the customer’s account with the provider, e.g.["+16135550175", "+40981233422"]
;addresses
- returns the address(es) on the customer’s account with the provider, e.g.
For some providers extra fields, e.g. Social Security Number or Cadastro de Pessoas Físicas, can also be returned.
Holder info can be fetched independently or along with other connection information, e.g. accounts and transactions.
In order to test the holder_info
attribute, you can connect the fakebank_simple_xf
provider.
Sample response (as provider attribute)
"holder_info": ["names", "emails"]
Sample response (as separate route)
{
"data": {
"names": ["John Doe"],
"emails": ["john.doe@example.com"]
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
}
}
Salt Edge Connect
You can easily test Connect
from your Dashboard
page by pressing the New Connection
button.
After your application has received a connect_session
for connecting or reconnecting a connection, you can redirect your user to the Salt Edge Connect URL.
There, they will see a screen that lets them pick a country and a provider.
Your user will also be asked to input the credentials and if needed, any of the interactive credentials.
For example, a user picked Italy as country and American Express as provider. This is what will be displayed:
To start the fetching process, the user will have to press “Proceed”. Afterwards, information on the connection’s progress will be displayed.
After the fetching is done, the user will be redirected back to your application.
After the connect
stage is changed to Updating Accounts(fetch_accounts), the user interaction will not be required, and the connect page can be hidden.
Salt Edge Connect (widget) supports only the 2 last versions of modern browsers.
Using connect in an iframe
Once you receive a connect_url
from Connect Sessions,
you can embed it in an iframe. However, there are several things you need
to take into account when doing that:
- to subscribe to callbacks, and close the iframe when the connection process finishes;
- connecting providers that authenticate via redirect may not work. That’s because most of the providers have HTTP headers (X-Frame-Options, Content-Security-Policy) that restrict the authentication page from being included in an iframe.
There are several ways in which you can mitigate the last point:
- Always open providers with redirect authentication in a new page.
These providers have the
mode
flag set tooauth
. - If the previous scenario is not an option, you can use
supported_iframe_embedding
flag to distinguish providers that restrict iframe usage.
Client side callbacks
When you request for a connect session, you can pass an optional argument javascript_callback_type
.
This argument enables one of the following notification methods:
- by inserting an iframe with a specific source URL into the connect page (used by Salt Edge Mobile SDKs);
- external object, calling window.external.SaltBridge (used by DotNet applications);
- external object, calling window.external.Notify (used by DotNet applications);
- postMessage,
calling window.addEventListener (used when Connect is in an iframe, popup, or new tab).
For React Native WebView it should be used WebView
onMessage
prop.
Salt Edge Connect will send any of these callbacks only in case when javascript_callback_type
was specified in the
connect session request.
Iframe injection
When not using the SDKs, your app is responsible for capturing the URLs, if you wish to be notified about the connect process.
The inserted URL has a custom scheme and host. The scheme of the URL is saltbridge
and the host is connect
. Here’s an example of such a URL:
saltbridge://connect/{"data":{"connection_id":"997674448","stage":"fetching","secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM", "custom_fields":{"key":"value"}, "api_stage":"start"}}
Once your app has captured the inserted URL, it has to serialize the JSON-encoded URL path following the scheme and the host. Here’s another example, this time of a duplicated connection callback:
saltbridge://connect/{"data":{"duplicated_connection_id":"994317674","stage":"error","custom_fields":{"key":"value"}, "api_stage":"finish"}}
Once your app has decoded the URL path, it can start performing several actions like accounts listing or error handling.
External object
If you access the Connect page from a .Net host, and you use WebBrowser.ObjectForScripting
, we will try to call the window.external.SaltBridge
function with the connection attributes serialized as JSON.
NOTE: In the example, SaltBridge
is a method defined on the object that was specified as an object for scripting: webBrowser1.ObjectForScripting = this
which initialized the WebView
.
External Notify Example
public void SaltBridge(String serializedLogin) {
// data
}
serializedConnection
{
"data": {
"connection_id":"111111111111111111",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields":{
"key":"value"
},
"api_stage": "start"
}
}
Post message
If you access the connect page wrapped in an iframe, you can use Window.postMessage (window.ReactNativeWebView.postMessage for React Native WebView
) which performs cross-origin communication.
Post Message Example
window.addEventListener("message", function(event) {
console.log(JSON.parse(event.data))
}
)
serializedConnection
{
"data": {
"connection_id":"111111111111111111",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key":"value"
},
"api_stage": "start"
}
}
External notify
On Windows Store app platform you can use event handler for ScriptNotify
event of WebView
. Your code should handle window.external.notify(args)
call, ScriptNotify
will fire, and you’ll get the args in Value
property of NotifyEventArgs
parameter.
Remember to add https://saltedge.com
and https://*.saltedge.com
to Content URIs in Package.appxmanifest
.
External Notify Example
protected override void OnNavigatedTo(NavigationEventArgs e) {
browser.ScriptNotify += browser_ScriptNotify;
}
private void browser_ScriptNotify(object sender, NotifyEventArgs e) {
var serializedConnection = e.Value;
}
serializedConnection
{
"data": {
"connection_id":"111111111111111111",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key":"value"
},
"api_stage": "start"
}
}
Connect callbacks
There are 2 callback types of Salt Edge Connect:
- Standard callback
- Duplicated connection callback.
Possible stage values for each callback type are fetching
, success
and error
.
Parameter api_stage
shows detailed information of the fetching process. Possible values are attempts stages.
Fetching
{
"data": {
"connection_id": "111111111111111111",
"stage": "fetching",
"secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key": "value"
},
"api_stage": "start"
}
}
and on duplicated connection:
{
"data": {
"duplicated_connection_id": "111111111111111112",
"stage": "fetching",
"custom_fields": {
"key": "value"
},
"api_stage": "start"
}
}
Success
For instance, when your user has created a connection using Salt Edge Connect, we will send the following success callback:
{
"data": {
"connection_id": "111111111111111111",
"stage": "success",
"secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key": "value"
},
"api_stage": "finish"
}
}
and on duplicated connection:
{
"data": {
"duplicated_connection_id": "111111111111111112",
"stage": "success",
"custom_fields": {
"key": "value"
},
"api_stage": "finish"
}
}
Error
Sometimes we fail to fetch the information from the provider’s page. It might happen because the interactive data was not sent by the user, the credentials are wrong, or we could not perform one of the steps of the fetching process. In this case, you will receive an error
callback, containing a JSON similar to the following:
{
"data": {
"connection_id": "111111111111111111",
"stage": "error",
"secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key": "value"
},
"api_stage": "finish"
}
}
and on duplicated connection:
{
"data": {
"duplicated_connection_id": "111111111111111112",
"stage": "error",
"custom_fields": {
"key": "value"
},
"api_stage": "finish"
}
}
Closing behaviour
After finishing the transaction fetching, the Connect Widget automatically redirects to the return_to
URL. This offers a seamless user experience by removing the widget from the screen once the transaction import process is complete.
Transaction Limit per Account:
PSU(user) will be redirected to the client’s application as soon as first transactions are fetched from the provider. When all other transactions are fetched, a success
callback is sent.
Import Process Duration:
The duration of the import process may vary depending on the number of accounts and transactions involved. Factors such as network speed, server response time, and the complexity of the transaction data can influence the time required for the import process. Users should be aware that larger datasets may require more time to complete the import process, while smaller datasets will generally import more quickly.
We recommend users to be patient and allow the Connect Widget sufficient time to import and process the transactions, particularly when dealing with a significant number of accounts and transactions. The background import process continues even after the widget has closed, thus users can continue with their tasks while the remaining transactions are imported.
Connect with Direct API
If you do not wish to create connections using Salt Edge Connect, you can perform all the connection actions using our API.
In order to create a new connection, you should use the connections create route. After creating the connection, your application will receive the corresponding callbacks so you can fetch your newly created connection.
If the connection you wish to connect is an interactive one, you will receive an interactive callback specified in your app’s profile, which means that you have to use the interactive route and follow the instructions specified in the API reference.
Direct API requires high-security standards for data handling on the client’s side. Having access to the Direct API routes gives you direct access to the end customer’s sensitive information, which is why we need to make sure that it is handled properly and securely. Therefore, this integration method is only available for the certified and/or selected partners.
In case your Client Account settings allow only Salt Edge Connect usage, though you try to send requests to Direct API endpoints, then you will encounter the ActionNotAllowedError
error.
For more information and assistance on the mentioned error you have received, please contact our Sales representatives via contact us.
Updating data
If a connection had an error while connecting, and it had an InvalidCredentials error during the fetching process, you should reconnect it and send the correct credentials in your request body.
When the connection is connected correctly, and you received all the accounts and transactions details, you can refresh the connection, and keep its data up-to-date.
Callbacks
The most important parts of Account Information API (e.g. Connection management) are asynchronous.
Every Web application has to provide a set of valid URLs which we will use to notify about the fetching progress. Other applications can poll Account Information API in order to retrieve the updated information.
There are several common points about the request we send to the callback URLs provided by the client:
- The
Content-Type
header isapplication/json
; - There is a
Signature
header that identifies the request was signed by Account Information API; - The request method is always
POST
; - The JSON object sent will always have a
data
field; - The
meta
field will display the version of the callbacks API.
You can set the callback URLs for your application by accessing your callbacks page.
Due to security reasons, the callbacks can be sent to ports 80/HTTP (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks do not follow redirects.
Request Identification
In order for the client to identify that the request is coming from Account Information API, there are two options, Signature and Mutual TLS:
Signature
Signature
- base64
encoded SHA256
signature of the string represented in the
form callback_url|post_body
- 2 parameters concatenated
with a vertical bar |
, signed with a Account Information API’s private key.
You can find the version of the signature key used to sign the callback in the Signature-key-version
header. The current version is 5.0
which corresponds to the following public key:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvL/Xxdmj7/cpZgvDMvxr
nTTU/vkHGM/qkJ0Q+rmfYLru0Z/rSWthPDEK3orY5BTa0sAe2wUV5Fes677X6+Ib
roCF8nODW5hSVTrqWcrQ55I7InpFkpTxyMkiFN8XPS7qmYXl/xofbYq0olcwE/aw
9lfHlZD7iwOpVJqTsYiXzSMRu92ZdECV895kYS/ggymSEtoMSW3405dQ6OfnK53x
7AJPdkAp0Wa2Lk4BNBMd24uu2tasO1bTYBsHpxonwbA+o8BXffdTEloloJgW7pV+
TWvxB/Uxil4yhZZJaFmvTCefxWFovyzLdjn2aSAEI7D1y4IYOdByMOPYQ6Mn7J9A
9wIDAQAB
-----END PUBLIC KEY-----
An example of the string that is to be used to generate the signature looks as follows:
https://www.client.com/api/callbacks/success|{"data":{"connection_id":"111111111111111111","customer_id":"222222222222222222","custom_fields":{}},"meta":{"version":"5","time":"2020-07-07T13:00:28Z"}}
The pseudocode that we use to generate the signature looks like this:
base64(sha256_signature(private_key, "callback_url|post_body"))
Mutual TLS
To verify that callback is coming from Account Information API, you can use Client Certificate Authentication.
a. Go to Account
-> Settings
-> Callbacks. There you will see on the right Mutual TLS.
b. Click on Generate CSR
.
c. Set Certificate attributes if needed and press Generate
.
d. Download CSR.
e. Use CA to generate client certificate from Downloaded CSR.
```
openssl x509 -req -days 365 -in salt_edge_callbacks.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
```
f. Upload generated certificate via the following form.
To see how it could be implemented on the server side check this example.
Requests cycle
To avoid unnecessary requests, performance issues and fetching all data, use the following diagram:
Success
We send a callback to your application’s success
URL whenever any operation has caused a change in the data we store for a particular connection.
For instance, after the user has been redirected to the Connect page, the provider has been selected, the credentials have been filled in and “Proceed” button has been pressed, Salt Edge will send you a success callback. This callback will contain the customer identifier and the id
of the newly created connection.
Afterwards, your application will be able to use the show connection route and query the information about this connection. You could also fetch the connection’s accounts and query the accounts (if any exist at the moment we sent the callback).
Whenever we have more information about the connection, we will send another success
callback.
A success callback marks a change in the data
, and you can generally expect from one to three success callbacks with the same payload within several minutes. We recommend that your application lists updated connection object, updates account balances, extra fields, and transactions using from_id
to fetch newly imported records at each callback, as some information might change during the fetching process.
For instance, when your user has created a connection using Salt Edge Connect, we will send the following success
callback:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "finish"
},
"meta": {
"version": "5",
"time": "2024-10-08T14:41:04.399Z"
}
}
You can now use the show connection route and obtain the provider, country and some other attributes of the new connection.
The possible stages sent in a success callback are as follows:
connect
- connecting to the data source;fetch_holder_info
- fetching the information about account holder;fetch_accounts
- fetching the accounts;fetch_recent
- fetching the transactions;finish
- wrapping up the fetching process.
Failure
Sometimes we fail to fetch the information from the provider’s page.
It might happen because the interactive data was not sent by the user, the credentials are wrong or we could not perform one of the steps of the fetching process.
In this case, you will receive a fail
callback, containing a JSON similar to the following:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"error_class": "InvalidCredentials",
"error_message": "Invalid credentials."
},
"meta": {
"version": "5",
"time": "2024-10-08T14:41:04.407Z"
}
}
After you get this callback, you need to request the connection to check for its updates. Please note that even if there’s an error, we still store the connection.
If you would like to delete the erroneous connection, you can use the remove connection route. In case of an InvalidCredentials error, we recommend you to use a Reconnect.
In order to avoid connection duplication errors on new connection creation, when you read the connection after a fail callback
,
we recommend you remove the connection in case of last_fail_error_class
is equal to InvalidCredentials, and the connection has zero linked accounts.
Additional callbacks
There are additional callbacks that your app needs to implement in order to use the API-only version of Account Information API.
Notify
Salt Edge can inform you about the progress the connection is going through using a Notify callback. Notify callback (if the appropriate Notify URL is set in your Client account), will be sent for create
, reconnect
and refresh
attempts.
Your app can expect the notify callback several times, depending on the type of the connection, but you can use this information to inform your users about what’s happening with their connection.
The possible stages sent in a notify callback are as follows:
start
- the fetching process has just begun;connect
- connecting to the data source;interactive
- waiting for the interactive credentials;fetch_holder_info
- fetching the information about account holder;fetch_accounts
- fetching the accounts;fetch_recent
- fetching the data for a recent period (several months);fetch_full
- fetching the data for a longer period;disconnect
- disconnecting from the data source;finish
- wrapping up the fetching process.
Here’s an example callback sent to the /notify
route of your app:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "start"
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
Interactive
Some of the providers require an additional step before signing in, asking users to input an SMS, Token, solve a CAPTCHA, etc.
Whenever we encounter that the connection requires an interactive step, we will send the interactive callback to the interactive route set in your app’s profile. Your app should prompt the users for the interactive credentials and send them to the interactive route.
We also send a snippet of HTML so that it would be easier for your app to display the CAPTCHA or image to the user.
If the provider requires filling a CAPTCHA, the img
tag in the HTML will contain the image URL.
During this process, the connection’s stage will be set to interactive
.
The interactive callback should contain the values of the interactive_credentials
field
from the corresponding provider.
Here’s an example callback sent to your app’s /interactive
route:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "interactive",
"html": "<div id='interactive'><img src='https://docs.saltedge.com/assets/images/saltedge_captcha.png' width='10' height='10' alt='some description' title='some description'></div>",
"session_expires_at": "2024-10-07T15:41:04Z",
"interactive_fields_names": ["image"]
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
In case of a dynamic_select
field, the callback will also include interactive_fields_options
, which you need to present to the user:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "interactive",
"html": "<p>Please select accounts from the list:</p>",
"session_expires_at": "2020-07-06T11:27:10Z",
"interactive_fields_names": ["accounts"],
"interactive_fields_options": {
"accounts": [
{
"name": "account1",
"english_name": "My checking account",
"localized_name": "My checking account",
"option_value": "service_acc_guid1",
"selected": false
},
{
"name": "account2",
"english_name": "My savings account",
"localized_name": "My savings account",
"option_value": "service_acc_guid2",
"selected": false
}
]
}
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
Note: Some interactive providers request to select only one option from dynamic_select
interactive field. In this case we mark such fields by adding multiple: false
flag to the extra key in provider’s interactive fields:
"interactive_fields": [
{
"name": "language",
"english_name": "Language",
"localized_name": "Language",
"nature": "dynamic_select",
"position": 3,
"optional": false,
"extra": {
"multiple": false
}
}
]
In such a case we expect to receive only 1 selected option value as a String
.
When the provider requires multiple options to be selected, we mark such fields by adding multiple: true
flag to the extra key in provider’s interactive fields:
"interactive_fields": [
{
"name": "accounts",
"english_name": "Accounts",
"localized_name": "Accounts",
"nature": "dynamic_select",
"position": 3,
"optional": false,
"extra": {
"multiple": true
}
}
]
In such a case we expect to receive an Array
of strings.
Interactive Redirect
There are some OAuth providers that require 2 redirects for authorization. In these cases, for the 2nd redirect Salt Edge will send an interactive callback with redirect_url
field:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"html": "",
"redirect_url": "https://bank.com/authorize"
"stage": "interactive",
"session_expires_at": "2024-10-07T15:41:04Z",
"interactive_fields_names": [],
"custom_fields": { "key": "value" }
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
Your application should redirect the user to redirect_url
field value of the interactive callback payload. Once the end-users will be authorized on the provider’s side, they will be redirected to the return_to
URL indicated in the create connection request.
To continue the process, you need to send a request containing the query string appended to your return_to
URL to the interactive route.
{
"data": {
"credentials": {
"query_string": "access_token=111111111111111111"
}
}
}
If there are no query parameters when the end-user is redirected to
the return_to
URL, please send an empty credentials
object.
{
"data": {
"credentials": {}
}
}
Authentication
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
} \
} \
}" \
https://www.saltedge.com/api/v5/connections/111111111111111111/interactive
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
} \
} \
}" \
https://www.saltedge.com/api/v5/connection/interactive
Destroy
Whenever a connection gets removed, we will send a callback to your application’s destroy URL, if such is set in your Client account.
Here’s an example callback sent to your app’s /destroy
route:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222"
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
Service
Whenever the connection had issues in the past and a change was made in connection’s provider codebase, your application will receive a callback telling that a refresh is needed in order to update connection’s data.
The possible reasons sent in a /service
callback are as follows:
fixed
- a fix was made;updated
- an update was made;
Here’s an example callback sent to the /service
route of your app:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"reason": "updated"
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:04Z"
}
}
Financial Insights
Whenever the Financial Insights Report is succesfully generated, your application will receive a callback.
The callback URL can be set by accessing Settings
-> Applications
-> Callbacks
-> Financial Insights
in the Dashboard.
Here’s an example callback sent to the Financial Insights route of your app:
{
"data": {
"report_id": "12345",
"status": "success",
"customer_id": "222222222222222222"
},
"meta": {
"version": "1",
"time": "2022-06-27T10:09:26.141Z"
}
}
Provider Changes
Whenever the Provider’s status changes, Salt Edge will send notifications to the Provider changes URL
callback route.
You can set the callback URLs for your application on the callbacks page.
Example Callback Payload:
{
"data": {
"provider_status": "inactive",
"provider_code": "fake_client_xf"
},
"meta": {
"version": 5,
"time": "2023-09-21T09:49:13.472Z"
}
}
Parameters sent to the callback URL
data
object
meta
object
data
object
meta
object
The possible statuses are:
active
- the provider is active and can be used for connections;inactive
- the provider is inactive and cannot be used for connections;
Errors
The Account Information API can return multiple errors for any operation, each having its meaning and usage.
Error attributes
class
string
The class of the error
message
string
A message describing the error
documentation_url
string
A link for error documentation
request_id
string
A unique identifier for this specific HTTP request. Can be sent to support for debugging
request
object
The body of the request that caused the error
class
string
The class of the error
message
string
A message describing the error
documentation_url
string
A link for error documentation
request_id
string
A unique identifier for this specific HTTP request. Can be sent to support for debugging
request
object
The body of the request that caused the error
Error codes
[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
[429] Too Many Requests
Sample response
{
"error": {
"class": "ConnectionNotFound",
"message": "Connection with id: '111111111111111111' was not found.",
"documentation_url": "https://docs.saltedge.com/account_information/v5/#errors-connection_not_found",
"request_id": "313b4518-10d4-4c15-a18e-34ddd583ebdf"
},
"request": {
"connection_id": "111111111111111111"
}
}
Bank integration layer
- Errors could take place either between Salt Edge and the bank, or on the bank’s end.
- Some of the errors are displayed to the end-users, while others are hidden.
- There are multiple reasons which cause the errors, for example, bank issues, incorrect user actions, invalid PSD2 access, etc.
ProviderError
,ExecutionTimeout
andProviderUnavailable
(unless the bank states it’s temporarily unavailable) should be reported to Salt Edge.ProviderAccessNotGranted
- the authorization on the bank’s end did not complete successfully. The reason can be identified only having the user’s comments and feedback. Such errors should be reported to Salt Edge so that we can contact the provider for assistance and clarifications.- The rest of the errors from the below table are caused by incorrect actions of the end-users.
Error class | HTTP code | Description |
---|---|---|
ExecutionTimeout | 406 | The whole fetching process took too long to execute |
FetchingTimeout | 406 | One of the steps of the fetching process took too long to execute |
InteractiveAdapterTimeout | 406 | The interactive step of the fetching process took too long to execute |
InvalidCredentials | 406 | The customer tried to connect/reconnect a connection with invalid credentials |
InvalidInteractiveCredentials | 406 | Interactive credentials that were sent are wrong |
ProviderAccessNotGranted | 406 | The authorization on the bank’s side did not complete successfully |
ProviderError | 406 | There’s an error on the provider’s side which obstructs us from obtaining the data for the connection |
ProviderUnavailable | 406 | The provider is temporarily unavailable |
AISP API Reference
- Errors can occur if the client configures API requests incorrectly.
- These errors are not displayed to end-users.
Error class | HTTP code | Description |
---|---|---|
AccountNotFound | 404 | An account with the sent |
AispConsentAlreadyRevoked | 406 | The consent has already been revoked |
AispConsentExpired | 406 | Refresh is not possible because the consent has expired |
AispConsentNotFound | 404 | A consent with such an |
AispConsentRevoked | 406 | Refresh is not possible because the consent has been revoked |
AispConsentScopesInvalid | 406 | The value of consent |
AispConsentScopesNotAllowed | 406 | The value of consent |
AllAccountsExcluded | 406 | You have excluded all the accounts from the connection fetching process |
AttemptNotFound | 404 | An attempt with such |
BackgroundFetchLimitExceeded | 406 | Background fetch limit (4 times in a 24 hour period) was exceeded (without the user’s presence). This restriction applies only to PSD2 providers. |
BatchSizeLimitExceeded | 406 | More than 100 objects were sent in the request (100 is the limit) |
CategorizationLimitReached | 406 | One client can categorize at most 1000 transactions per day. This error is applicable only to clients in |
ConnectionAlreadyAuthorized | 409 | The connection was already authorized |
ConnectionAlreadyProcessing | 409 | The connection is already being processed |
ConnectionCannotBeRefreshed | 406 | The next refresh attempt will be allowed according to |
ConnectionDisabled | 406 | The client tried to connect, reconnect or fetch a connection, but it appears to be disabled |
ConnectionDuplicated | 409 | The client tried to create a connection that already exists |
ConnectionFetchingStopped | 406 | Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process |
ConnectionLimitReached | 406 | The client tried to create more connections than possible for a client which is in |
ConnectionNotFound | 404 | We could not find a connection with the requested |
CountryNotFound | 404 | Sending a |
CredentialsNotMatch | 406 | New connection credentials do not match the old ones on reconnect. Please contact us in case you encountered this error. |
CustomFieldsFormatInvalid | 406 | The |
CustomFieldsSizeTooBig | 406 | The |
CustomerLocked | 406 | Customer is locked. May be unlocked |
CustomerNotFound | 404 | A customer with such |
DateFormatInvalid | 400 | We have received an invalid Date format |
DateOutOfAispConsentRange | 400 | The passed |
DateOutOfRange | 400 | Sending a date value that does not fit in admissible range |
DateTimeFormatInvalid | 400 | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 | Sending a datetime value that does not fit in admissible range |
DuplicatedCustomer | 409 | The customer you are trying to create already exists |
FetchScopesInvalid | 406 | The value of |
FetchScopesNotAllowed | 406 | The value of |
FileError | 406 | There were errors while uploading and processing files |
FileNotProvided | 400 | Provider with the |
FileNotSaved | 400 | File was not saved because of an error |
HolderInfoNotSupported | 406 | Fetching |
IdentifierInvalid | 406 | Invalid identifier sent for creatinng a customer |
InteractiveTimeout | 400 | It took too long to respond to the interactive question |
InvalidAispConsentFromDate | 406 | Invalid consent |
InvalidAispConsentPeriod | 406 | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 | Invalid |
InvalidToDate | 406 | Invalid |
JsonParseError | 400 | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 | The accessed provider has the |
ProviderInactive | 406 | The requested provider has the |
ProviderNotFound | 404 | Sending a |
ProviderNotInteractive | 406 | The connection’s provider has no interactive step |
RateLimitExceeded | 406 | Too many connections are being processed at the same time from one application |
ReportNotFound | 404 | The requested Financial Insights |
RequestExpired | 400 | The request has expired, took longer than mentioned in the |
ReturnURLInvalid | 406 | The |
ReturnURLTooLong | 406 | The |
RouteNotFound | 404 | The action and/or the endpoint you are trying to access does not exist |
TransactionNotFound | 404 | A transaction with the sent |
ValueOutOfRange | 400 | Sending a value (e.g. |
WrongProviderMode | 406 | We do not support the received |
WrongRequestFormat | 400 | The JSON request is incorrectly formed |
Client Configuration
Error class | HTTP code | Description |
---|---|---|
ActionNotAllowed | 400 | The client has no access to the required route or direct API access is not permitted. For more details, please check FAQ |
ApiKeyNotFound | 404 | The API key with the provided |
AppIdNotProvided | N/A | The |
ClientDisabled | 406 | The client has been disabled. You can find out more about the disabled status on Disabled guides page |
ClientNotFound | 404 | The API key used in the request does not belong to a client |
ClientPending | 406 | The client is pending approval. You can find out more about the pending status on Pending guides page |
ClientRestricted | 406 | The client is in |
ConnectionFailed | 406 | Some network errors appear while fetching data |
ConnectionLost | N/A | Internet connection was lost in the process |
ExpiresAtInvalid | 400 | The |
InternalServerError | 500 | An internal error has occurred |
InvalidEncoding | 400 | Invalid JSON encoded values |
MissingExpiresAt | 400 | The |
MissingSignature | 400 | The |
ProviderKeyNotFound | 404 | The chosen provider does not have provider keys |
PublicKeyNotProvided | 400 | The public key was not specified on Keys & secrets page |
SecretNotProvided | 400 | The |
SignatureNotMatch | 400 | The |
TooManyRequests | 400 | Too many requests have occurred for connecting/reconnecting a connection from one IP address in a short period of time |
WrongClientToken | 400 | We have received a wrong combination of |
WrongReportType | 400 | We have received a wrong report type |
api
Countries
The country is represented just as a string. We’re using ISO 3166-1 alpha-2 country codes. Thus, all the country codes will have exactly two uppercase letters. There are two special cases:
- “Other”, encoded as
XO
- “Fake”, encoded as
XF
Note that the Fake country is only available for clients in Test and Pending statuses.
List
Returns a list of countries supported by Account Information API.
Parameters
include_fake_providers
boolean, optional
Whether you wish to fetch the fake countries. Possible values: true
, false
. Defaults to false
.
include_fake_providers
boolean, optional
Whether you wish to fetch the fake countries. Possible values: true
, false
. Defaults to false
.
Response
name
string
Name of the country.
code
string
Country code as dated in ISO 3166-1 alpha-2
refresh_start_time
integer
Local country time when connections will be automatically refreshed. Possible values: 0
, 1
, 2
, 3
, 4
, 5
, 6
, 7
, 8
, 9
, 10
, 11
, 12
, 13
, 14
, 15
, 16
, 17
, 18
, 19
, 20
, 21
, 22
, 23
.
name
string
Name of the country.
code
string
Country code as dated in ISO 3166-1 alpha-2
refresh_start_time
integer
Local country time when connections will be automatically refreshed. Possible values: 0
, 1
, 2
, 3
, 4
, 5
, 6
, 7
, 8
, 9
, 10
, 11
, 12
, 13
, 14
, 15
, 16
, 17
, 18
, 19
, 20
, 21
, 22
, 23
.
Possible Errors
No specific errors
URL
https://www.saltedge.com/api/v5/countries
https://www.saltedge.com/api/v5/countries
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/countries
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/countries
Sample response
{
"data": [
{
"code": "CZ",
"name": "Czech Republic",
"refresh_start_time": 1
},
{
"code": "IL",
"name": "Israel",
"refresh_start_time": 7
},
{
"code": "MD",
"name": "Moldova",
"refresh_start_time": 0
},
{
"code": "RO",
"name": "Romania",
"refresh_start_time": 0
},
{
"code": "ES",
"name": "Spain",
"refresh_start_time": 1
},
{
"code": "GB",
"name": "United Kingdom",
"refresh_start_time": 23
},
{
"code": "XF",
"name": "Fake",
"refresh_start_time": 8
},
{
"code": "XO",
"name": "Other",
"refresh_start_time": 4
}
]
}
{
"data": [
{
"code": "CZ",
"name": "Czech Republic",
"refresh_start_time": 1
},
{
"code": "IL",
"name": "Israel",
"refresh_start_time": 7
},
{
"code": "MD",
"name": "Moldova",
"refresh_start_time": 0
},
{
"code": "RO",
"name": "Romania",
"refresh_start_time": 0
},
{
"code": "ES",
"name": "Spain",
"refresh_start_time": 1
},
{
"code": "GB",
"name": "United Kingdom",
"refresh_start_time": 23
},
{
"code": "XF",
"name": "Fake",
"refresh_start_time": 8
},
{
"code": "XO",
"name": "Other",
"refresh_start_time": 4
}
]
}
Providers
A provider is a source of financial data. We recommend you update all of the providers’ fields at least daily.
Attributes
id
string
The id
of the provider
code
string
Provider’s code
name
string
Provider’s name
mode
string
Possible values are:
oauth
– access through the bank’s dedicated API (regulated: true
). The user is redirected to the bank’s page for authorization. For more details, check OAuth providers.web
– access through the bank’s WEB interface using screen scraping technology. Therefore, the user undergoes the same authorization flow as in the bank’s web interface with an identical set of credentials.api
– access through a dedicated (regulated: true
) or non-dedicated (regulated: false
) bank’s API. Some required credentials fields might be present which the user should complete (IBAN, username, etc.). In case of a dedicated API, an interactive redirect might be present, but there are required credentials fields which the user should complete (IBAN, username, etc.). Using these credentials, we authorize the user on the bank’s side.file
– access through uploading a file of certain format (XLS, CSV, etc.), which is processed to extract information about accounts and transactions.
status
string
Possible values: active
, inactive
, disabled
- The providers with the
inactive
status are returned on the providers list endpoint, but are not visible on the Connect widget for the end-users. - The providers with
disabled
status are neither returned on the providers list endpoint, nor visible on the Connect widget for end-users.
automatic_fetch
boolean
Whether the provider’s connections can be automatically fetched. However, its performance also depends on optional_interactivity
flag
dynamic_registration_code
string, optional
The dynamic registration code assigned to the Provider
group_code
string, optional
The code of the group to which the Provider belongs
group_name
string, optional
It can be equal to provider_code
, but may also change independently, regardless of the provider_code
hub
string, optional
The hub that the Provider is affiliated with
customer_notified_on_sign_in
boolean
Whether the provider will notify the customer on log in attempt
interactive
boolean
Whether the provider requires interactive input
identification_mode
string
Whether the request to the provider is made with your authorization headers or with Salt Edge’s. Possible values: client
, saltedge
.
instruction
string
Guidance on how to connect the bank
home_url
string
The URL of the main page of the provider
login_url
string
Point of entrance to provider’s login web interface
logo_url
string
The URL for the provider logo, may have a placeholder for providers with missing logos
country_code
string
Code of the provider’s country
refresh_timeout
integer
Amount of time (in minutes) after which the provider’s connections are allowed to be refreshed
holder_info
array of strings
Contains information on the account holder details that can be fetched from this provider
max_consent_days
integer
Maximum allowed consent duration. If it is null
, then there are no limits
created_at
string (date-time)
Time and date when the provider was integrated
updated_at
string (date-time)
The last time when any of provider’s attributes were changed
timezone
string
Time zone data of capital/major city in a region corresponding to the provider
max_interactive_delay
integer
Delay in seconds before InteractiveAdapterTimeout
error will be raised
optional_interactivity
boolean
Provider which supports flipping of the interactive
and automatic_fetch
flags after connect
regulated
boolean
Whether the provider is integrated via a regulated channel under Open Banking/PSD2
max_fetch_interval
integer
Maximum period of days that a provider can return from its interface
custom_pendings
boolean, optional
Equals to true
if the provider supports a custom pending logic. For example, when the transactions for the last 7 days are marked as pending. Usually implemented to avoid the generation of duplicated transactions due to inconsistent transaction information returned by the bank.
custom_pendings_period
integer, optional
Populated when custom_pendings
is true
. Shows the number of days according to the custom pending period implemented in the provider.
supported_fetch_scopes
array of strings
Array of strings with supported fetch_scopes
supported_transaction_extra_fields
array of strings
Array of possible transaction extra fields to be fetched
supported_account_types
array of strings
Possible values inside array: personal
, business
.
identification_codes
array of strings
List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.
bic_codes
array of strings
List of BIC codes identifying supported branches of a specific provider.
supported_iframe_embedding
boolean
Possible values: true
, false
.
payment_templates
array of strings
Identifiers of the payment templates that are supported by this provider
supported_payment_fields
object, optional
If these fields are passed, they will be used by the provider. Otherwise, the payment will we processed even without them
required_payment_fields
object, optional
Mandatory payment attributes. If any of these fields are not passed, the payment will not be initiated successfully
id
string
The id
of the provider
code
string
Provider’s code
name
string
Provider’s name
mode
string
Possible values are:
oauth
– access through the bank’s dedicated API (regulated: true
). The user is redirected to the bank’s page for authorization. For more details, check OAuth providers.web
– access through the bank’s WEB interface using screen scraping technology. Therefore, the user undergoes the same authorization flow as in the bank’s web interface with an identical set of credentials.api
– access through a dedicated (regulated: true
) or non-dedicated (regulated: false
) bank’s API. Some required credentials fields might be present which the user should complete (IBAN, username, etc.). In case of a dedicated API, an interactive redirect might be present, but there are required credentials fields which the user should complete (IBAN, username, etc.). Using these credentials, we authorize the user on the bank’s side.file
– access through uploading a file of certain format (XLS, CSV, etc.), which is processed to extract information about accounts and transactions.
status
string
Possible values: active
, inactive
, disabled
- The providers with the
inactive
status are returned on the providers list endpoint, but are not visible on the Connect widget for the end-users. - The providers with
disabled
status are neither returned on the providers list endpoint, nor visible on the Connect widget for end-users.
automatic_fetch
boolean
Whether the provider’s connections can be automatically fetched. However, its performance also depends on optional_interactivity
flag
dynamic_registration_code
string, optional
The dynamic registration code assigned to the Provider
group_code
string, optional
The code of the group to which the Provider belongs
group_name
string, optional
It can be equal to provider_code
, but may also change independently, regardless of the provider_code
hub
string, optional
The hub that the Provider is affiliated with
customer_notified_on_sign_in
boolean
Whether the provider will notify the customer on log in attempt
interactive
boolean
Whether the provider requires interactive input
identification_mode
string
Whether the request to the provider is made with your authorization headers or with Salt Edge’s. Possible values: client
, saltedge
.
instruction
string
Guidance on how to connect the bank
home_url
string
The URL of the main page of the provider
login_url
string
Point of entrance to provider’s login web interface
logo_url
string
The URL for the provider logo, may have a placeholder for providers with missing logos
country_code
string
Code of the provider’s country
refresh_timeout
integer
Amount of time (in minutes) after which the provider’s connections are allowed to be refreshed
holder_info
array of strings
Contains information on the account holder details that can be fetched from this provider
max_consent_days
integer
Maximum allowed consent duration. If it is null
, then there are no limits
created_at
string (date-time)
Time and date when the provider was integrated
updated_at
string (date-time)
The last time when any of provider’s attributes were changed
timezone
string
Time zone data of capital/major city in a region corresponding to the provider
max_interactive_delay
integer
Delay in seconds before InteractiveAdapterTimeout
error will be raised
optional_interactivity
boolean
Provider which supports flipping of the interactive
and automatic_fetch
flags after connect
regulated
boolean
Whether the provider is integrated via a regulated channel under Open Banking/PSD2
max_fetch_interval
integer
Maximum period of days that a provider can return from its interface
custom_pendings
boolean, optional
Equals to true
if the provider supports a custom pending logic. For example, when the transactions for the last 7 days are marked as pending. Usually implemented to avoid the generation of duplicated transactions due to inconsistent transaction information returned by the bank.
custom_pendings_period
integer, optional
Populated when custom_pendings
is true
. Shows the number of days according to the custom pending period implemented in the provider.
supported_fetch_scopes
array of strings
Array of strings with supported fetch_scopes
supported_transaction_extra_fields
array of strings
Array of possible transaction extra fields to be fetched
supported_account_types
array of strings
Possible values inside array: personal
, business
.
identification_codes
array of strings
List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.
bic_codes
array of strings
List of BIC codes identifying supported branches of a specific provider.
supported_iframe_embedding
boolean
Possible values: true
, false
.
payment_templates
array of strings
Identifiers of the payment templates that are supported by this provider
supported_payment_fields
object, optional
If these fields are passed, they will be used by the provider. Otherwise, the payment will we processed even without them
required_payment_fields
object, optional
Mandatory payment attributes. If any of these fields are not passed, the payment will not be initiated successfully
Sample object
{
"id": "123",
"code": "fakebank_simple_xf",
"name": "Fake Bank",
"mode": "web",
"status": "active",
"automatic_fetch": true,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": false,
"interactive": false,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": [
"names",
"emails",
"phone_numbers"
],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:04Z",
"updated_at": "2024-10-03T14:41:04Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_extra_fields": [
],
"supported_transaction_extra_fields": [
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
}
}
{
"id": "123",
"code": "fakebank_simple_xf",
"name": "Fake Bank",
"mode": "web",
"status": "active",
"automatic_fetch": true,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": false,
"interactive": false,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": [
"names",
"emails",
"phone_numbers"
],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:04Z",
"updated_at": "2024-10-03T14:41:04Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_extra_fields": [
],
"supported_transaction_extra_fields": [
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
}
}
Show
Allows you to inspect a single provider in order to give
your users a proper interface to input their credentials.
The response will have an array of required_fields
and interactive_fields
,
which are explained in more detail in the create section of this reference.
Providers that require a client provider key will be included only if you have created provider keys for them and added to your client account.
Parameters
provider_code
string
Provider’s code
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
Defaults to false
.
provider_code
string
Provider’s code
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ProviderNotFound | 404 Not Found | Sending a |
URL
https://www.saltedge.com/api/v5/providers/{provider.code}
https://www.saltedge.com/api/v5/providers/{provider.code}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/providers/fakebank_interactive_xf
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/providers/fakebank_interactive_xf
Sample response
{
"data": {
"id": "67",
"code": "fakebank_interactive_xf",
"name": "Fake Bank with SMS",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"interactive": true,
"instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\",\nsms - \"123456\"\n",
"refresh_timeout": 5,
"customer_notified_on_sign_in": false,
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_interactive_xf",
"logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/xf/fakebank_interactive_xf.svg",
"country_code": "XF",
"created_at": "2014-03-19T17:55:44Z",
"updated_at": "2019-03-07T09:57:26Z",
"timezone": "UTC",
"holder_info": [
],
"max_consent_days": null,
"identification_mode": "saltedge",
"max_interactive_delay": 180,
"optional_interactivity": false,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"supported_account_extra_fields": [
"account_name",
"account_number",
"card_type",
"cards",
"client_name",
"iban",
"sort_code",
"status",
"swift"
],
"supported_transaction_extra_fields": [
"convert",
"original_amount",
"original_currency_code",
"payee",
"posting_date",
"transfer_account_name"
],
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_fields": [
{
"name": "login",
"english_name": "Login",
"localized_name": "Login",
"nature": "text",
"position": 1,
"optional": false,
"extra": {
}
},
{
"name": "password",
"english_name": "Password",
"localized_name": "Password",
"nature": "password",
"position": 2,
"optional": false,
"extra": {
}
}
],
"interactive_fields": [
{
"name": "sms",
"english_name": "SMS code",
"localized_name": "SMS code",
"nature": "number",
"position": 1,
"optional": false,
"extra": {
}
}
]
}
}
{
"data": {
"id": "67",
"code": "fakebank_interactive_xf",
"name": "Fake Bank with SMS",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"interactive": true,
"instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\",\nsms - \"123456\"\n",
"refresh_timeout": 5,
"customer_notified_on_sign_in": false,
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_interactive_xf",
"logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/xf/fakebank_interactive_xf.svg",
"country_code": "XF",
"created_at": "2014-03-19T17:55:44Z",
"updated_at": "2019-03-07T09:57:26Z",
"timezone": "UTC",
"holder_info": [
],
"max_consent_days": null,
"identification_mode": "saltedge",
"max_interactive_delay": 180,
"optional_interactivity": false,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"supported_account_extra_fields": [
"account_name",
"account_number",
"card_type",
"cards",
"client_name",
"iban",
"sort_code",
"status",
"swift"
],
"supported_transaction_extra_fields": [
"convert",
"original_amount",
"original_currency_code",
"payee",
"posting_date",
"transfer_account_name"
],
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_fields": [
{
"name": "login",
"english_name": "Login",
"localized_name": "Login",
"nature": "text",
"position": 1,
"optional": false,
"extra": {
}
},
{
"name": "password",
"english_name": "Password",
"localized_name": "Password",
"nature": "password",
"position": 2,
"optional": false,
"extra": {
}
}
],
"interactive_fields": [
{
"name": "sms",
"english_name": "SMS code",
"localized_name": "SMS code",
"nature": "number",
"position": 1,
"optional": false,
"extra": {
}
}
]
}
}
List
Returns all the providers we operate with.
If a provider becomes disabled
, it is not included in the list.
You can read more about the next_id
field in the pagination section of the reference.
Providers that require a client provider key will be included only if you have created provider keys for them and added to your client account.
Parameters
from_id
string, optional
The id
of the provider which the list starts with. Defaults to null
.
from_date
string (date), optional
Filtering providers by the updated_at
attribute, starting from this date. Defaults to null
.
country_code
string, optional
Filtering providers by country. Defaults to null
.
mode
string, optional
Filtering providers by mode. Possible values: oauth
, web
, api
, file
.
include_fake_providers
boolean, optional
Whether you wish to fetch the fake providers. Defaults to false
.
include_provider_fields
boolean, optional
Whether you wish to include all provider fields in the provider objects. Defaults to false
.
provider_key_owner
string, optional
Filtering providers by key owner. When value is set as client
, only providers with client-set keys will be returned. Please see Client Provider Keys. Possible values: client
, saltedge
.
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
Defaults to false
.
from_id
string, optional
The id
of the provider which the list starts with. Defaults to null
.
from_date
string (date), optional
Filtering providers by the updated_at
attribute, starting from this date. Defaults to null
.
country_code
string, optional
Filtering providers by country. Defaults to null
.
mode
string, optional
Filtering providers by mode. Possible values: oauth
, web
, api
, file
.
include_fake_providers
boolean, optional
Whether you wish to fetch the fake providers. Defaults to false
.
include_provider_fields
boolean, optional
Whether you wish to include all provider fields in the provider objects. Defaults to false
.
provider_key_owner
string, optional
Filtering providers by key owner. When value is set as client
, only providers with client-set keys will be returned. Please see Client Provider Keys. Possible values: client
, saltedge
.
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
DateOutOfRange | 400 Bad Request | Sending a date value that does not fit in admissible range |
ValueOutOfRange | 400 Bad Request | Sending a value (e.g. |
URL
https://www.saltedge.com/api/v5/providers
https://www.saltedge.com/api/v5/providers
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/providers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/providers
Sample Response
{
"data": [
{
"id": "123",
"code": "fakebank_image_xf",
"name": "Fake Bank with Image",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": true,
"interactive": true,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": [
"names",
"emails",
"phone_numbers"
],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:04Z",
"updated_at": "2024-10-03T14:41:04Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_extra_fields": [
],
"supported_transaction_extra_fields": [
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
}
}
],
"meta": {
"next_id": null,
"next_page": null
}
}
{
"data": [
{
"id": "123",
"code": "fakebank_image_xf",
"name": "Fake Bank with Image",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": true,
"interactive": true,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": [
"names",
"emails",
"phone_numbers"
],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:04Z",
"updated_at": "2024-10-03T14:41:04Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": [
"accounts",
"transactions"
],
"supported_account_extra_fields": [
],
"supported_transaction_extra_fields": [
],
"supported_account_natures": [
"account",
"card"
],
"supported_account_types": [
"personal"
],
"identification_codes": [
"123123"
],
"bic_codes": [
"ABCDEFGH"
],
"supported_iframe_embedding": true,
"payment_templates": [
"SEPA"
],
"supported_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
},
"required_payment_fields": {
"SEPA": [
"amount",
"creditor_iban",
"creditor_name",
"currency_code",
"customer_ip_address",
"description",
"end_to_end_id"
]
}
}
],
"meta": {
"next_id": null,
"next_page": null
}
}
Fields
There are several types of fields as marked by their nature
attribute.
nature
string
Possible values: text
, password
, select
, dynamic_select
, file
, number
.
name
string
The field’s name that should be used as a key in the credentials object
english_name
string
The field’s name in US English
localized_name
string
The name of the field in the provider’s main language
position
integer
The field’s position in the public user interface
optional
boolean
Whether the input for this field is required by the provider
field_options
object, optional
Only for the select
field type. Contains the options for the select
extra
object, optional
Extra information about the field
nature
string
Possible values: text
, password
, select
, dynamic_select
, file
, number
.
name
string
The field’s name that should be used as a key in the credentials object
english_name
string
The field’s name in US English
localized_name
string
The name of the field in the provider’s main language
position
integer
The field’s position in the public user interface
optional
boolean
Whether the input for this field is required by the provider
field_options
object, optional
Only for the select
field type. Contains the options for the select
extra
object, optional
Extra information about the field
Example object
{
"nature": "text",
"name": "login",
"english_name": "Username",
"localized_name": "Utilizator",
"optional": false,
"position": 1
}
{
"nature": "text",
"name": "login",
"english_name": "Username",
"localized_name": "Utilizator",
"optional": false,
"position": 1
}
Field options
Some providers ask their users to select a secret word or an answer to a question as a security measure. In this case, the provider will contain a field of select
type. The field will contain an array of field_options
objects, which describe the possible choices for the user.
name
string
The name of the field option
english_name
string
The option’s name in US English
localized_name
string
The name of the field in the provider’s main language
option_value
string
The value of the option that needs to be passed as credentials
selected
boolean
Whether the choice is selected by default
name
string
The name of the field option
english_name
string
The option’s name in US English
localized_name
string
The name of the field in the provider’s main language
option_value
string
The value of the option that needs to be passed as credentials
selected
boolean
Whether the choice is selected by default
The options for dynamic_select
are not stored in the Provider, they are generated dynamically and sent in an Interactive callback.
Example object
{
"name": "home",
"english_name": "Home",
"localized_name": "Casa",
"option_value": "home",
"selected": true
}
{
"name": "home",
"english_name": "Home",
"localized_name": "Casa",
"option_value": "home",
"selected": true
}
Fake
In order to help you with testing, we provide a fake country (having the country code XF
) and a set of fake providers.
If your application is in the Test or Pending status,
the Connect page will let you select the fake country and its providers.
Account Information API supplies a number of fake providers:
fakebank_simple_xf
- requires a username and a password;fakebank_select_xf
- has a dropdown list with some options for the user to choose from;fakebank_with_dynamic_select_xf
- allows to test thedynamic_select
credentials field;fakebank_image_xf
- the user needs to solve a CAPTCHA for authentication;fakebank_inactive_xf
- reproduces theProviderInactive
error;fakebank_interactive_xf
- asks for a fake SMS code;fake_delayed_oauth_client_xf
- will delay the payment initiation by a few seconds;fakebank_two_step_interactive_xf
- asks for interactive data twice during the fetching process;fakebank_semi_interactive_xf
- occasionally requires an SMS code;fake_oauth_interactive_client_xf
- has an interactive redirect during the attempt besides the first authorize redirect;fake_oauth_interactive_no_callback_client_xf
- allows testing scenario for additional redirect during the SCA process;fakebank_with_optional_fields_xf
- similar tofakebank_interactive_xf
, but with some of the interactive fields marked asoptional
;fakebank_api_with_fields_xf
- similar tofakebank_simple_xf
, used for ensuringapi
providers availability;fakebank_oauth_xf
- asks for authorization;fake_with_partial_data_xf
- has a dropdown list with some options for the user to choose from. Allows to test 3 different scenarios of partial data: incomplete accounts data, incomplete transactions data, and an error;fakebank_oauth_with_pending_xf
- similar tofakebank_oauth_xf
, returns pending transactions;fakebank_oauth_with_n_transactions_xf
- similar tofakebank_oauth_xf
, returns more than 1000 transactions;fakebank_with_updates_xf
- generates up to 4 transactions on everycreate
,refresh
,reconnect
with random amounts and modes;fake_demobank_xf
- generates multiple accounts with different currencies, and different account natures;fake_business_demobank_xf
- simulates the flow of a non-regulated API provider;fakebank_with_token_xf
- requires a username and a fake token;fake_with_dynamic_registration_oauth_client_xf
- linked to a fake dynamic registration. Once the dynamic registration is executed, the provider keys will be added automatically;fakebank_oauth_with_pending_and_available_balance_xf
- similar tofakebank_oauth_with_pending_xf
, having accounts, which have different values forbalance
andavailable_balance
;fakebank_with_possible_duplicates_xf
- each attempt generates transactions with the samemade_on
,amount
,currency_code
but differentdescription
. On the second attempt and later it marks those transaction withextra[:possible_duplicate]
flag set totrue
;fakebank_with_rememberable_credentials_xf
- remembers all the answers to secret questions and doesn’t ask them during the interactive stage if they were introduced correctly on previous attempts;fake_oauth_eidas_client_xf
- will raise an error if QWAC or QSeal certificates are not configured correctly in the client’s account;fakebank_with_crypto_assets_xf
- simulates the flow of a crypto provider;fakebank_with_natures_xf
- allows testing all the possiblesupported_account_natures
;fakebank_with_file_csv_xf
- extracts transactions from a csv file. You can download the sample here; Note: Testing this provider allows the client to try out categorization and merchant identification for a country. For that, it is required to configure theCountry
andAccount Currency
fields accordingly;fake_with_error_client_xf
- allows testing multiple errors;fakebank_with_error_xf
- allows testing multiple errors.
Fake Bank with Error (fake_with_error_client_xf
) allows selecting the error you would like to test. The choices are as follows:
Invalid SCA redirect URL
- no error. The user will be redirected to an invalid URL. As a result, the connection will fail withProviderAccessNotGranted
because the PSU (user) couldn’t complete the authorization step.Token Expired
- Error class: InvalidCredentials. Error message: Invalid token.Consent Invalid
- Error class: InvalidCredentials. Error message: Consent is not valid.Access declined
- Error class: InvalidCredentials. Error message: Access declined. Please contact your bank’s customer service.Too many requests
- Error class: ProviderUnavailable. Error message: Too many requests.ExecutionTimeout
- Error class: ExecutionTimeout. Error message: ExecutionTimeout error.InteractiveAdapterTimeout
- Error class: InteractiveAdapterTimeout. Error message: Interactive timeout.InvalidInteractiveCredentials
- Error class: InvalidInteractiveCredentials. Error message: Interactive action failed.AccountValidationError
- Error class: AccountValidationError. Error message: ‘Simple account 2’ already exists in account list.Payment failed with delay
- The payment will fail after 20 to 25 second from the moment of initialization. Error class: PaymentFailed. Error message: Payment failed.
Fake Bank with Error Web Banking (fakebank_with_error_xf
) allows selecting the error you would like to test. The choices are as follows:
No errors
- there will be no errors.No Errors, partial data
- Error class: AdapterError. Error message: Fake error. Note: accounts and transactions are imported successfully, butpartial
flag is set totrue
.ExecutionTimeout
- Error class: ExecutionTimeout. Error message: ExecutionTimeout error.FetchingTimeout
- Error class: FetchingTimeout. Error message: FetchingTimeout error.ProviderUnavailable
- Error class: ProviderUnavailable. Error message: ProviderUnavailable error.ActionRequested
- Error class: InvalidCredentials. Error message: Provider asked to perform an action. Please, log in your web client.AccountValidationError
- Error class: AccountValidationError. Error message: ‘Simple account 2’ already exists in account list.InvalidCredentials - consent expired
- Error class: InvalidCredentials. Error message: Consent has expired.ProviderError
- Error class: AdapterError. Error message: Provider error.InvalidInteractiveCredentials
- Error class: InvalidInteractiveCredentials. Error message: Interactive action failed.InteractiveAdapterTimeout
- Error class: InteractiveAdapterTimeout. Error message: Interactive timeout.No active accounts
- Error class: ProviderUnavailable. Error message: No active accounts were found. Please, contact your provider.
The ProviderNotFound
error may be reproduced by trying any inexistent and invalid provider_code
.
We also supply fake providers to test your Client Provider Keys with:
fake_client_xf
- requires a username and password (embedded);fake_oauth_client_xf
- asks for authorization (OAuth redirect);fake_interactive_client_xf
- asks to enter a fake captcha code in addition to a username and a password (embedded).fake_interactive_decoupled_client_xf
- decoupled interactive flow (e.g. push notification), asks to wait 10 seconds in Connect widget and then click Proceed to continue in addition to a username and a password (embedded).
Note: The appropriate credentials for a particular provider are mentioned under the Instructions
field on its Connect page.
Sandbox
Sandbox is a live-testing environment of a regulated provider that allows Partners and Clients to test providers under Salt Edge’s supervision.
In order to help with testing regulated providers, Salt Edge offers the sandbox environment of each PSD2 bank. A sandbox is identified by the word Sandbox in the provider_name
(eg. Lloyds Bank (Sandbox)) with a designated provider_code
containing XF
as country code (eg.lloyds_oauth_client_gb_xf
).
Just as with the fake providers, sandbox providers can be tested if your application is in Test or Pending status. In the Connect page, we will let you select the fake country (having the country code XF
), and its sandbox providers.
The authorization instructions are mentioned under the Instructions
field on its Connect page.
Note: Some Sandboxes may not be available for an indefinite period of time due to the limited support sources of a provider.
Customers
A Customer
represents a single end-user of the Account Information API. The customer uses the API to create Connections
, i.e. bank connections, that are further used to aggregate the customer’s financial data.
Here’s a diagram that illustrates the Customer
and its associated concepts:
Customer - a single end-user.
Connection - a single connection to a provider. A single customer can have multiple connections to multiple banks.
Account - an account returned by the provider. Corresponds to a customer’s bank account.
Transaction - a single movement made within an account. Can be a transfer transaction.
You need to store the id
returned from the response in your application, which is necessary when creating connections.
We give you the following customer API actions so that the customer will be successfully identified within Salt Edge.
Attributes
id
integer (int64)
Creates a customer, returning the customer object.
identifier
string
A unique identifier of the new customer.
secret
string
Customer secret.
blocked_at
string, optional
Customer block date. Customer was blocked by Salt Edge due to the usage of invalid credentials.
created_at
string (date-time)
When the customer was created
updated_at
string (date-time)
When the customer was updated
id
integer (int64)
Creates a customer, returning the customer object.
identifier
string
A unique identifier of the new customer.
secret
string
Customer secret.
blocked_at
string, optional
Customer block date. Customer was blocked by Salt Edge due to the usage of invalid credentials.
created_at
string (date-time)
When the customer was created
updated_at
string (date-time)
When the customer was updated
Sample object
{
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"blocked_at": "2021-03-15T09:43:01Z",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
{
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"blocked_at": "2021-03-15T09:43:01Z",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
Create
Creates a customer, returning the customer object.
Parameters
identifier
string
A unique id
of the new customer
identifier
string
A unique id
of the new customer
Possible Errors
Error class | HTTP code | Description |
---|---|---|
DuplicatedCustomer | 409 Duplicated | The customer you are trying to create already exists |
IdentifierInvalid | 406 Not Acceptable | Invalid identifier sent for creatinng a customer |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/customers
https://www.saltedge.com/api/v5/customers
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"12rv1212f1efxchsdhbgv\" \
} \
}" \
https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"12rv1212f1efxchsdhbgv\" \
} \
}" \
https://www.saltedge.com/api/v5/customers
Sample Response
{
"data": {
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
}
{
"data": {
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
}
Show
Returns the customer object.
Parameters
customer_id
integer
The id
of the customer
customer_id
integer
The id
of the customer
Possible Errors
Error class | HTTP code | Description |
---|---|---|
CustomerNotFound | 404 Not Found | A customer with such |
URL
https://www.saltedge.com/api/v5/customers/{customer.id}
https://www.saltedge.com/api/v5/customers/{customer.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/customers/222222222222222222
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/customers/222222222222222222
Sample Response
{
"data": {
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"blocked_at": "2021-03-15T09:43:01Z",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
}
{
"data": {
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"blocked_at": "2021-03-15T09:43:01Z",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
}
List
List all of your app’s customers. This route is available only for web applications, not mobile ones.
Parameters
identifier
string, optional
A unique id
of a customer
identifier
string, optional
A unique id
of a customer
Possible Errors
No specific errors
URL
https://www.saltedge.com/api/v5/customers
https://www.saltedge.com/api/v5/customers
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/customers
Sample Response
{
"data": [
{
"id": "222222222222222222",
"identifier": "unique_customer_identifier",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
},
{
"id": "222222222222222223",
"identifier": "unique_customer_identifier_2",
"secret": "UYhs6Q8vRyMrPjUVtW7J_O1n0hndQ25bvUJ8CIJT3",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
],
"meta": {
"next_id": "222222222222222224",
"next_page": "/api/v5/customers?from_id=222222222222222224"
}
}
{
"data": [
{
"id": "222222222222222222",
"identifier": "unique_customer_identifier",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
},
{
"id": "222222222222222223",
"identifier": "unique_customer_identifier_2",
"secret": "UYhs6Q8vRyMrPjUVtW7J_O1n0hndQ25bvUJ8CIJT3",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
],
"meta": {
"next_id": "222222222222222224",
"next_page": "/api/v5/customers?from_id=222222222222222224"
}
}
Remove
Deletes a customer, returning the customer object. Revokes all consents for this customer. This route is available only for web applications.
Parameters
customer_id
integer
The id
of the customer
customer_id
integer
The id
of the customer
Possible Errors
Error class | HTTP code | Description |
---|---|---|
CustomerNotFound | 404 Not Found | A customer with such |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/customers/{customer.id}
https://www.saltedge.com/api/v5/customers/{customer.id}
Method
DELETE
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/customers/222222222222222222
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/customers/222222222222222222
Sample Response
{
"data": {
"deleted": true,
"id": "222222222222222222"
}
}
{
"data": {
"deleted": true,
"id": "222222222222222222"
}
}
Lock
Locks a customer and its data, returning the customer object.
All customer related data including connections, accounts, transactions, attempts will not be available for reading, updating or deleting even by Salt Edge. This route is available only for web applications.
Parameters
customer_id
integer
The id
of the customer
customer_id
integer
The id
of the customer
Possible Errors
Error class | HTTP code | Description |
---|---|---|
CustomerNotFound | 404 Not Found | A customer with such |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/customers/{customer.id}/lock
https://www.saltedge.com/api/v5/customers/{customer.id}/lock
Method
PUT
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/customers/222222222222222222/lock
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/customers/222222222222222222/lock
Sample Response
{
"data": {
"locked": true,
"id": "222222222222222222"
}
}
{
"data": {
"locked": true,
"id": "222222222222222222"
}
}
Unlock
Unlocks a customer and its data, returning the customer object. This route is available only for web applications.
Parameters
customer_id
integer
The id
of the customer
customer_id
integer
The id
of the customer
Possible Errors
Error class | HTTP code | Description |
---|---|---|
CustomerNotFound | 404 Not Found | A customer with such |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/customers/{customer.id}/unlock
https://www.saltedge.com/api/v5/customers/{customer.id}/unlock
Method
PUT
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/customers/222222222222222222/unlock
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/customers/222222222222222222/unlock
Sample Response
{
"data": {
"unlocked": true,
"id": "222222222222222222"
}
}
{
"data": {
"unlocked": true,
"id": "222222222222222222"
}
}
Connect sessions
We use connect sessions to identify clients who use Salt Edge Connect.
With a connect session, you will be able to let your users connect, reconnect, or refresh a connection.
Note that the connect session will expire in 60 seconds
if you do not access Salt Edge Connect.
After the connect session has been used to redirect the user to Salt Edge Connect, the overall process of authentication and data fetch will take place 10 minutes. Afterwards, the end-user’s session will expire.
Note: There are exceptions when certain banks might take longer to fetch the data, which can extend the 10 minutes timeout.
Before acquiring a connect session, you should be sure that the user exists in the system, or create one.
If your client account’s status is Pending, you will receive a ClientPending error when connecting any connection not from the fake providers.
Create
Allows you to create a connect session, which will be used to access Salt Edge Connect for connection creation.
You will receive a connect_url
field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.
The consent confirmation, in this case, can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer should agree in the Salt Edge Connect interface should be sent).
Please see the sequence diagram for details on how Connect
integration works.
Parameters
customer_id
string
The id
of the customer received from customer create. This field is optional for ‘app’ authentication
allowed_countries
array of strings, optional
The list of countries that will be accessible in Salt Edge Connect, e.g.: ['US', 'DE']
. Defaults to null
.
country_code
string, optional
Returns the list of providers only from given country. Possible values: any country code from ISO 3166-1 alpha-2, e.g.: 'DE'
. Defaults to null
.
provider_code
string, optional
The code of the desired provider, defaults to null
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
disable_provider_search
boolean, optional
Whether the provider search will be disabled, works only if provider_code
parameter is sent. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restricts the list of the providers to only the ones that have the mode included in the array. Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}
. Defaults to false
.
show_consent_confirmation
boolean, optional
If consent confirmation is handled on the client’s side, this parameter should be sent as false
so, upon submitting the form, the user will not be asked to give the consent to Salt Edge Inc. Defaults to true
.
credentials_strategy
string, optional
The strategy of storing customer’s credentials.
Note: If the value is ask
, on the Connect page, the customer will be able to choose whether to save or not the credentials on Salt Edge side
Possible values: store
, do_not_store
, ask
. Defaults to store
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
allowed_countries
array of strings, optional
The list of countries that will be accessible in Salt Edge Connect, e.g.: ['US', 'DE']
. Defaults to null
.
country_code
string, optional
Returns the list of providers only from given country. Possible values: any country code from ISO 3166-1 alpha-2, e.g.: 'DE'
. Defaults to null
.
provider_code
string, optional
The code of the desired provider, defaults to null
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
disable_provider_search
boolean, optional
Whether the provider search will be disabled, works only if provider_code
parameter is sent. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restricts the list of the providers to only the ones that have the mode included in the array. Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}
. Defaults to false
.
show_consent_confirmation
boolean, optional
If consent confirmation is handled on the client’s side, this parameter should be sent as false
so, upon submitting the form, the user will not be asked to give the consent to Salt Edge Inc. Defaults to true
.
credentials_strategy
string, optional
The strategy of storing customer’s credentials.
Note: If the value is ask
, on the Connect page, the customer will be able to choose whether to save or not the credentials on Salt Edge side
Possible values: store
, do_not_store
, ask
. Defaults to store
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
ClientRestricted | 406 Not Acceptable | The client is in |
CountryNotFound | 404 Not Found | Sending a |
CustomerLocked | 406 Not Acceptable | Customer is locked. May be unlocked |
CustomerNotFound | 404 Not Found | A customer with such |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ProviderNotFound | 404 Not Found | Sending a |
ReturnURLInvalid | 406 Not Acceptable | The |
ReturnURLTooLong | 406 Not Acceptable | The |
WrongProviderMode | 406 Not Acceptable | We do not support the received |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connect_sessions/create
https://www.saltedge.com/api/v5/connect_sessions/create
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"consent\": { \
\"from_date\": \"2020-05-08\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-07-07\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"consent\": { \
\"from_date\": \"2020-05-08\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-07-07\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/create
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Reconnect
Allows you to create a connect session, which will be used to access Salt Edge Connect to reconnect a connection.
You will receive a connect_url
field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.
Reconnect requires new consent to be given. The consent confirmation, in this case, can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer should agree in the Salt Edge Connect interface should be sent).
Parameters
connection_id
string
The id
of the connection you wish to reconnect
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restricts the list of the providers to only the ones that have the mode included in the array. Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost' }}
. Defaults to false
.
show_consent_confirmation
boolean, optional
If consent confirmation is handled on the client’s side, this parameter should be sent as false
so, upon submitting the form, the user will not be asked to give the consent to Salt Edge Inc. Defaults to true
.
credentials_strategy
string, optional
The strategy of storing customer’s credentials.
Note: If the value is ask
, on the Connect page, the customer will be able to choose whether to save or not the credentials on Salt Edge side
Possible values: store
, do_not_store
, ask
. Defaults to store
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
override_credentials_strategy
string, optional
If sent as ask
, the user will be required to confirm the credentials override upon submitting the form, in the scenario where the new credentials are different from the ones in the previous attempt. If sent as override
, the new credentials will automatically override the old ones. Possible values: ask
, override
. Defaults to null
.
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restricts the list of the providers to only the ones that have the mode included in the array. Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost' }}
. Defaults to false
.
show_consent_confirmation
boolean, optional
If consent confirmation is handled on the client’s side, this parameter should be sent as false
so, upon submitting the form, the user will not be asked to give the consent to Salt Edge Inc. Defaults to true
.
credentials_strategy
string, optional
The strategy of storing customer’s credentials.
Note: If the value is ask
, on the Connect page, the customer will be able to choose whether to save or not the credentials on Salt Edge side
Possible values: store
, do_not_store
, ask
. Defaults to store
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
override_credentials_strategy
string, optional
If sent as ask
, the user will be required to confirm the credentials override upon submitting the form, in the scenario where the new credentials are different from the ones in the previous attempt. If sent as override
, the new credentials will automatically override the old ones. Possible values: ask
, override
. Defaults to null
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
AllAccountsExcluded | 406 Not Acceptable | You have excluded all the accounts from the connection fetching process |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
CountryNotFound | 404 Not Found | Sending a |
CustomerNotFound | 404 Not Found | A customer with such |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ProviderNotFound | 404 Not Found | Sending a |
ReturnURLInvalid | 406 Not Acceptable | The |
ReturnURLTooLong | 406 Not Acceptable | The |
WrongProviderMode | 406 Not Acceptable | We do not support the received |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connect_sessions/reconnect
https://www.saltedge.com/api/v5/connect_sessions/reconnect
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"connection_id\": \"111111111111111111\", \
\"consent\": { \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"consent\": { \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/reconnect
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Refresh
Allows you to create a connect session, which will be used to access Salt Edge Connect to refresh a connection.
You will receive a connect_url
field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.
Refresh does not require a new consent, it is based on the limitations of the current active consent. If the latest consent has been revoked, only a reconnect is possible.
Parameters
connection_id
string
The id
of the connection you wish to reconnect
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Shows whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restrict the list of the providers to only the ones that have the mode included in the array.
Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. If null
, it means that you will not receive any callbacks. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}
. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Shows whether to append connection_id
to return_to
URL. Defaults to false
.
provider_modes
array of strings, optional
Restrict the list of the providers to only the ones that have the mode included in the array.
Defaults to ["oauth", "web", "api", "file"]
. Possible values inside array: oauth
, web
, api
, file
.
javascript_callback_type
string, optional
Allows you to specify what kind of callback type you are expecting. If null
, it means that you will not receive any callbacks. Possible values: iframe
, external_saltbridge
, external_notify
, post_message
. Defaults to null
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
lost_connection_notify
boolean, optional
Being sent as true
, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type
you specified. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}
. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
.
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Possible values: default
, dark
. Defaults to default
.
connect_template
string, optional
Defaults to Salt Edge Connect
template unless a different template is passed and available for the current client
show_connect_overview
boolean, optional
Shows an overview of fetched accounts and balances after fetching was finished. Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentExpired | 406 Not Acceptable | Refresh is not possible because the consent has expired |
AispConsentRevoked | 406 Not Acceptable | Refresh is not possible because the consent has been revoked |
AllAccountsExcluded | 406 Not Acceptable | You have excluded all the accounts from the connection fetching process |
BackgroundFetchLimitExceeded | 406 Not Acceptable | Background fetch limit (4 times in a 24 hour period) was exceeded (without the user’s presence). This restriction applies only to PSD2 providers. |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ReturnURLInvalid | 406 Not Acceptable | The |
ReturnURLTooLong | 406 Not Acceptable | The |
WrongProviderMode | 406 Not Acceptable | We do not support the received |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connect_sessions/refresh
https://www.saltedge.com/api/v5/connect_sessions/refresh
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"connection_id\": \"111111111111111111\", \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connect_sessions/refresh
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
{
"data": {
"expires_at": "2024-10-08T15:41:04Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
OAuth Providers
Account Information API also allows your app to import data from OAuth providers we support. The OAuth workflow, in this case, is reduced to a couple of HTTP calls and redirects.
Connecting OAuth providers is done via the same mechanism as when connecting a usual connection - using connect sessions for creating, reconnecting, or refreshing.
The response will contain a redirect_url
, and your app has to redirect the user to that URL.
The redirect_url
points to a page where the users can provide Salt Edge access to their financial data, making it available for your app.
As soon as access is granted, the user will be redirected to the return_to
page.
Create
Used to create a connection for an OAuth provider.
After receiving the response, the customer will be redirected to return_to
URL.
Mobile clients receive a connection_secret
parameter in the return_to
URL if the connection was successfully connected and an error_message
parameter if the connection failed to connect for some reason.
Please note that return_to
is optional for clients only if they use shared (owned by Salt Edge) provider keys (defaults to client’s home_url
). If clients use their own provider keys, return_to
is required and should be a valid URL that was registered within the provider that is being connecting to.
Please see the sequence diagram on the flow described above.
Parameters
customer_id
string
The id
of the customer received from customer create. This field is optional for ‘app’ authentication
country_code
string
The code of the country
provider_code
string
The code of the provider
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers.
Defaults to false
.
country_code
string
The code of the country
provider_code
string
The code of the provider
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers.
Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
CountryNotFound | 404 Not Found | Sending a |
CustomerLocked | 406 Not Acceptable | Customer is locked. May be unlocked |
CustomerNotFound | 404 Not Found | A customer with such |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ProviderNotFound | 404 Not Found | Sending a |
ReturnURLInvalid | 406 Not Acceptable | The |
ReturnURLTooLong | 406 Not Acceptable | The |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/oauth_providers/create
https://www.saltedge.com/api/v5/oauth_providers/create
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_oauth_xf\", \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2020-06-07\" \
}, \
\"attempt\": { \
\"return_to\": \"https://example.com/\", \
\"from_date\": \"2020-07-08\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
}, \
\"return_connection_id\": false \
} \
}" \
https://www.saltedge.com/api/v5/oauth_providers/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_oauth_xf\", \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2020-06-07\" \
}, \
\"attempt\": { \
\"return_to\": \"https://example.com/\", \
\"from_date\": \"2020-07-08\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
}, \
\"return_connection_id\": false \
} \
}" \
https://www.saltedge.com/api/v5/oauth_providers/create
Sample response
{
"data": {
"connection_id": "111111111111111111",
"connection_secret": "secret",
"attempt_id": "777777777777777777",
"token": "GENERATED_TOKEN",
"expires_at": "2024-10-08T15:41:04Z",
"redirect_url": "https://www.saltedge.com/api/v5/oauth_providers/redirect?token=GENERATED_TOKEN"
}
}
{
"data": {
"connection_id": "111111111111111111",
"connection_secret": "secret",
"attempt_id": "777777777777777777",
"token": "GENERATED_TOKEN",
"expires_at": "2024-10-08T15:41:04Z",
"redirect_url": "https://www.saltedge.com/api/v5/oauth_providers/redirect?token=GENERATED_TOKEN"
}
}
Reconnect
Used to reconnect a connection for an OAuth provider.
After receiving the response, the customer will be redirected to the return_to
URL.
Mobile clients receive a connection_secret
parameter in the return_to
URL if the connection was successfully connected and an error_message
parameter if the connection failed to connect for some reason.
Please note that return_to
is optional for clients only if shared (owned by Salt Edge) provider keys are used (defaults to client’s home_url
). If clients use their own provider keys, return_to
is required and should be a valid URL that was registered within the provider that is being connecting to.
Parameters
connection_id
string
The id
of the connection that is to be reconnected
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers.
Defaults to false
.
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers.
Defaults to false
.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
AllAccountsExcluded | 406 Not Acceptable | You have excluded all the accounts from the connection fetching process |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ReturnURLInvalid | 406 Not Acceptable | The |
ReturnURLTooLong | 406 Not Acceptable | The |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/oauth_providers/reconnect
https://www.saltedge.com/api/v5/oauth_providers/reconnect
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"connection_id\": \"111111111111111111\", \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2020-06-07\" \
}, \
\"attempt\": { \
\"return_to\": \"https://example.com/\" \
}, \
\"return_connection_id\": false \
} \
}" \
https://www.saltedge.com/api/v5/oauth_providers/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"consent\": { \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
], \
\"from_date\": \"2020-06-07\" \
}, \
\"attempt\": { \
\"return_to\": \"https://example.com/\" \
}, \
\"return_connection_id\": false \
} \
}" \
https://www.saltedge.com/api/v5/oauth_providers/reconnect
Sample response
{
"data": {
"connection_id": "111111111111111111",
"connection_secret": "secret",
"attempt_id": "777777777777777777",
"token": "GENERATED_TOKEN",
"expires_at": "2024-10-08T15:41:04Z",
"redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
{
"data": {
"connection_id": "111111111111111111",
"connection_secret": "secret",
"attempt_id": "777777777777777777",
"token": "GENERATED_TOKEN",
"expires_at": "2024-10-08T15:41:04Z",
"redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Connections
A connection represents a set of credentials required to access the accounts and transactions through a specific provider.
Within Account Information API, a connection can have one of the following statuses:
active
- the current set of credentials is valid and allows us to fetch the data properly;inactive
- an error appeared while fetching the connection. An inactive connection cannot be refreshed, thus only reconnected;A connection will have
inactive
status in the following cases:- Any attempt that fails with
Invalid credentials
error will mark the connection’s status asinactive
- Any attempt that fails with
Provider Unavailable
with one of the following error messages:Account blocked. Please, contact your provider.
Provider does not have any account records available at this time.
Provider asked to update your account settings.
No active accounts were found. Please, contact your provider.
Provider is disabled.
- Any attempt that fails with
disabled
- in case of non-compliance with our Terms of Service, we can contact the application’s owner and disable the connection.
Attributes
id
string
The id
of the connection
secret
string
The secret key associated with a specific connection
. It allows to read the information related to a connection using API keys of type app
.
provider_id
string
The id
of the provider the connection belongs to
provider_code
string
The code of the provider the connection belongs to
provider_name
string
The name of the provider the connection belongs to
daily_refresh
boolean
Whether the connection will be refreshed daily
customer_id
string
Customer’s id
created_at
string (date-time)
Time and date when the connection was added
updated_at
string (date-time)
The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed
last_success_at
string (date-time)
Time when the connection was successfully fetched
status
string
Possible values: active
, inactive
, disabled
.
country_code
string
Code of the country the provider belongs to
next_refresh_possible_at
string (date-time), optional
When the next refresh will be available. May contain null
value if connection has automatic_fetch
set as false
, or is already processing
store_credentials
boolean
Whether the credentials were stored on our side
show_consent_confirmation
boolean
Whether any consent was given for this connection on Salt Edge side
id
string
The id
of the connection
secret
string
The secret key associated with a specific connection
. It allows to read the information related to a connection using API keys of type app
.
provider_id
string
The id
of the provider the connection belongs to
provider_code
string
The code of the provider the connection belongs to
provider_name
string
The name of the provider the connection belongs to
daily_refresh
boolean
Whether the connection will be refreshed daily
customer_id
string
Customer’s id
created_at
string (date-time)
Time and date when the connection was added
updated_at
string (date-time)
The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed
last_success_at
string (date-time)
Time when the connection was successfully fetched
status
string
Possible values: active
, inactive
, disabled
.
country_code
string
Code of the country the provider belongs to
next_refresh_possible_at
string (date-time), optional
When the next refresh will be available. May contain null
value if connection has automatic_fetch
set as false
, or is already processing
store_credentials
boolean
Whether the credentials were stored on our side
show_consent_confirmation
boolean
Whether any consent was given for this connection on Salt Edge side
Sample object
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:41:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:41:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:41:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:41:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:41:04Z"
}
},
"holder_info": {
"names": [
"John Doe"
],
"emails": [
"john.doe@example.com",
"johndoe@gmail.com"
],
"phone_numbers": [
"+40981233422"
],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2024-10-08T14:41:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:41:04Z"
}
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:41:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:41:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:41:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:41:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:41:04Z"
}
},
"holder_info": {
"names": [
"John Doe"
],
"emails": [
"john.doe@example.com",
"johndoe@gmail.com"
],
"phone_numbers": [
"+40981233422"
],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2024-10-08T14:41:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:41:04Z"
}
List
Returns all the connections accessible to your application for a certain customer.
The connections are sorted in ascending order of their id
, so the newest connections will come last.
We recommend you fetch the whole list of connections to check whether any of the properties have changed.
You can read more about next_id
field in the pagination section of the reference.
Parameters
customer_id
string
The id
of the customer, allows to fetch connections only for a certain customer
from_id
string, optional
The id
of the connection which the list starts with
customer_id
string
The id
of the customer, allows to fetch connections only for a certain customer
from_id
string, optional
The id
of the connection which the list starts with
Possible Errors
Error class | HTTP code | Description |
---|---|---|
CustomerNotFound | 404 Not Found | A customer with such |
ValueOutOfRange | 400 Bad Request | Sending a value (e.g. |
URL
https://www.saltedge.com/api/v5/connections?customer_id={customer.id}
https://www.saltedge.com/api/v5/connections?customer_id={customer.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
Sample Response
{
"data": [
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
],
"meta": {
"next_id": "111111111111111112",
"next_page": "/api/v5/connections?customer_id=222222222222222222&from_id=111111111111111112"
}
}
{
"data": [
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
],
"meta": {
"next_id": "111111111111111112",
"next_page": "/api/v5/connections?customer_id=222222222222222222&from_id=111111111111111112"
}
}
Show
Returns a single connection object.
Parameters
connection_id
string
Id
of the connection
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}
https://www.saltedge.com/api/v5/connection
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/connection
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2020-05-07T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2020-05-07T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-06-02T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-06-02T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-06-02T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2020-06-02T16:16:19Z"
}
},
"last_success_at": "2020-06-02T16:16:19Z",
"next_refresh_possible_at": "2020-06-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2020-06-02T09:41:23Z"
}
}
{
"data": {
"country_code": "MD",
"created_at": "2020-05-07T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2020-05-07T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-06-02T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-06-02T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-06-02T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2020-06-02T16:16:19Z"
}
},
"last_success_at": "2020-06-02T16:16:19Z",
"next_refresh_possible_at": "2020-06-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2020-06-02T09:41:23Z"
}
}
Create
When not using Salt Edge Connect, your app will have to pass the user’s values of provider’s fields within the payload.
The credentials object should be modeled after the provider’s fields.
For instance, if the provider’s required fields contain a field with the value of name
equal to username
, the credential object should contain a username
attribute with the value being the actual username.
For example, here’s a provider:
{
"data": {
"code": "bigbank_us",
"required_fields": [
{
"english_name": "Pass Code",
"localized_name": "Pass Code",
"name": "code",
"nature": "text",
"position": 1
}
]
}
}
The user should be prompted to input Pass Code
.
If they input Pass Code (in this case, the user has input “hunter2”), your app should send the following data in the credentials
object:
{
"code": "hunter2"
}
Here’s another example that includes a select:
{
"data": {
"code": "anotherbank_us",
"required_fields": [
{
"english_name": "Password",
"localized_name": "Password",
"name": "password",
"nature": "password",
"position": 1
},
{
"nature": "select",
"name": "image",
"english_name": "Image",
"localized_name": "Imagine",
"position": 2,
"optional": false,
"field_options": [
{
"name": "1",
"english_name": "Home",
"localized_name": "Casa",
"option_value": "home",
"selected": false
},
{
"name": "2",
"english_name": "Car",
"localized_name": "Automobil",
"option_value": "car",
"selected": false
}
]
}
]
}
}
In this case, your app should prompt the users to input Password and offer them a select with the options of “Casa” and “Automobil” (the localized_name
or english_name
values, depending on your service).
The credentials should contain the name of the selected field (in this case image
) as the key and the user’s selected option_value
as its value.
Let’s say the user has input hunter2
as password and has chosen “Automobil” from the select.
The credentials
object should look like this:
{
"password": "hunter2",
"image": "car"
}
Using this route requires a consent object to be passed. This means that the consent confirmation should be handled on the client’s side, and the ‘access terms’ the customer agreed on should be passed.
Please see the sequence diagram on the flow described above.
Parameters
customer_id
string
The id
of the customer
country_code
string
The country code of the desired provider
provider_code
string
The code of the desired provider
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
customer_id
string, optional
The id
of the customer
country_code
string
The country code of the desired provider
provider_code
string
The code of the desired provider
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
Response
A complete Connection object.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionDuplicated | 409 Duplicated | The client tried to create a connection that already exists |
ConnectionFetchingStopped | 406 Not Acceptable | Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process |
ConnectionLimitReached | 406 Not Acceptable | The client tried to create more connections than possible for a client which is in |
CountryNotFound | 404 Not Found | Sending a |
CustomerLocked | 406 Not Acceptable | Customer is locked. May be unlocked |
CustomerNotFound | 404 Not Found | A customer with such |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
FileNotProvided | 400 Bad Request | Provider with the |
FileNotSaved | 400 Bad Request | File was not saved because of an error |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ProviderNotFound | 404 Not Found | Sending a |
RateLimitExceeded | 406 Not Acceptable | Too many connections are being processed at the same time from one application |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connections
https://www.saltedge.com/api/v5/connection
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_simple_xf\", \
\"consent\": { \
\"from_date\": \"2020-06-07\", \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-07-07\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
}, \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connections
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_simple_xf\", \
\"consent\": { \
\"from_date\": \"2020-06-07\", \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-07-07\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
}, \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connection
Sample request (with file providers)
curl -v -include \
-H "Accept: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
-F "data[provider_code]=ofx_xo" \
-F "data[country_code]=XO" \
-F "data[consent][scopes][]=account_details" \
-F "data[customer_id]=222222222222222222" \
https://www.saltedge.com/api/v5/connections
curl -v -include \
-H "Accept: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
-F "data[provider_code]=ofx_xo" \
-F "data[country_code]=XO" \
-F "data[consent][scopes][]=account_details" \
https://www.saltedge.com/api/v5/connection
Sample request (with file providers, using file_url)
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"country_code\": \"XO\", \
\"provider_code\": \"mint_csv_xo\", \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
}, \
\"consent\": { \
\"from_date\": \"2020-06-07\", \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
} \
}" \
https://www.saltedge.com/api/v5/connections
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XO\", \
\"provider_code\": \"mint_csv_xo\", \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
}, \
\"consent\": { \
\"from_date\": \"2020-06-07\", \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
} \
}" \
https://www.saltedge.com/api/v5/connection
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": "2020-06-07",
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": "2024-10-08",
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
}
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": "2020-06-07",
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": "2024-10-08",
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
}
Reconnect
In order to reconnect a connection, your app needs to send the credentials object, connection’s id
, consent object and/or attempt object. This means that the consent confirmation should be handled on the client’s side, and the ‘access terms’ the customer agreed on should be passed.
Parameters
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
override_credentials
boolean, optional
If sent as true
, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Defaults to false
.
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
override_credentials
boolean, optional
If sent as true
, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Defaults to false
.
Response
A complete Connection object.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
AllAccountsExcluded | 406 Not Acceptable | You have excluded all the accounts from the connection fetching process |
BackgroundFetchLimitExceeded | 406 Not Acceptable | Background fetch limit (4 times in a 24 hour period) was exceeded (without the user’s presence). This restriction applies only to PSD2 providers. |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionFetchingStopped | 406 Not Acceptable | Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
RateLimitExceeded | 406 Not Acceptable | Too many connections are being processed at the same time from one application |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}/reconnect
https://www.saltedge.com/api/v5/connection/reconnect
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
}, \
\"consent\": { \
\"scopes\": [ \
\"account_details\" \
] \
}, \
\"override_credentials\": true \
} \
}" \
https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
}, \
\"consent\": { \
\"scopes\": [ \
\"account_details\" \
] \
}, \
\"override_credentials\": true \
} \
}" \
https://www.saltedge.com/api/v5/connection/reconnect
Sample request (with file providers)
curl -v -include \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect
curl -v -include \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": true,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
}
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": true,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2024-10-08T14:01:04Z"
}
}
Interactive
If the currently fetching connection requires any interactive credentials for fetching, Salt Edge will send the Interactive callback. Make sure to specify the Interactive URL
in your client account by accessing callbacks page.
Upon receiving the interactive callback, your app should ask the users for interactive credentials and send them to the /interactive
route for the connection. After that, the fetching process will continue as usual.
In case of dynamic_select
field nature, when it has extra: { multiple: true }
flag - you should send the option_value
of the user selected options in an Array
of strings:
{
"data": {
"credentials": {
"accounts": ["account1", "account2"]
}
}
}
In case of dynamic_select
field nature, when it has extra: { multiple: false }
flag - you should send the option_value
of the user selected option as a single String
value:
{
"data": {
"credentials": {
"language": "english"
}
}
}
Please note that in some cases (e.g. when fetching Fake Bank with SMS
connections), during the interactive
stage a provider may not require any interactive fields (see interactive_fields_names
), thus you should send an empty object in the credentials field:
{
"data": {
"credentials": {}
}
}
Parameters
customer_id
string
The id
of the customer
country_code
string
The country code of the desired provider
provider_code
string
The code of the desired provider
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
customer_id
string, optional
The id
of the customer
country_code
string
The country code of the desired provider
provider_code
string
The code of the desired provider
credentials
object
The credentials required to access the data
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
file_url
boolean, optional
URL of a file. Is used when creating a connection for a provider with file
mode
Response
A complete Connection object.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentScopesInvalid | 406 Not Acceptable | The value of consent |
AispConsentScopesNotAllowed | 406 Not Acceptable | The value of consent |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionDuplicated | 409 Duplicated | The client tried to create a connection that already exists |
ConnectionFetchingStopped | 406 Not Acceptable | Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process |
ConnectionLimitReached | 406 Not Acceptable | The client tried to create more connections than possible for a client which is in |
CountryNotFound | 404 Not Found | Sending a |
CustomerLocked | 406 Not Acceptable | Customer is locked. May be unlocked |
CustomerNotFound | 404 Not Found | A customer with such |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
FileNotProvided | 400 Bad Request | Provider with the |
FileNotSaved | 400 Bad Request | File was not saved because of an error |
InvalidAispConsentFromDate | 406 Not Acceptable | Invalid consent |
InvalidAispConsentPeriod | 406 Not Acceptable | Invalid consent period_days value or not allowed by provider |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
ProviderNotFound | 404 Not Found | Sending a |
RateLimitExceeded | 406 Not Acceptable | Too many connections are being processed at the same time from one application |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}/interactive
https://www.saltedge.com/api/v5/connection/interactive
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"sms\": \"AB123\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connections/111111111111111111/interactive
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"sms\": \"AB123\" \
} \
} \
}" \
https://www.saltedge.com/api/v5/connection/interactive
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": false,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": false,
"finished_recent": false,
"from_date": null,
"id": "777777777777777777",
"interactive": true,
"locale": "en",
"partial": true,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": [
"sms"
],
"interactive_html": "<input type='text' name='smsi placeholder=iSms'>",
"name": "interactive",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_interactive_xf",
"provider_name": "Fake Bank with SMS",
"status": "active",
"updated_at": "2024-10-08T14:01:04Z"
}
}
{
"data": {
"country_code": "XF",
"created_at": "2024-10-07T14:41:04Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": false,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T14:01:04Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": false,
"finished_recent": false,
"from_date": null,
"id": "777777777777777777",
"interactive": true,
"locale": "en",
"partial": true,
"store_credentials": true,
"success_at": "2024-10-08T14:01:04Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:04Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T14:01:04Z",
"id": "888888888888888888",
"interactive_fields_names": [
"sms"
],
"interactive_html": "<input type='text' name='smsi placeholder=iSms'>",
"name": "interactive",
"updated_at": "2024-10-08T14:01:04Z"
}
},
"last_success_at": "2024-10-08T14:01:04Z",
"next_refresh_possible_at": "2024-10-08T15:41:04Z",
"provider_id": "1234",
"provider_code": "fakebank_interactive_xf",
"provider_name": "Fake Bank with SMS",
"status": "active",
"updated_at": "2024-10-08T14:01:04Z"
}
}
Refresh
Allows you to trigger a refetch of the data associated with a specific connection.
Note that you can refresh a connection only if it has an active consent.
If the response is successful, it will contain the next_refresh_possible_at
value, and you can expect the usual callbacks of the fetching workflow.
Parameters
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge. Defaults to false
.
include_fake_providers
boolean, optional
If sent as true
, the customers of live clients will be able to connect fake providers. Defaults to false
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Defaults to personal
.
Response
A complete Connection object.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentExpired | 406 Not Acceptable | Refresh is not possible because the consent has expired |
AispConsentRevoked | 406 Not Acceptable | Refresh is not possible because the consent has been revoked |
AllAccountsExcluded | 406 Not Acceptable | You have excluded all the accounts from the connection fetching process |
BackgroundFetchLimitExceeded | 406 Not Acceptable | Background fetch limit (4 times in a 24 hour period) was exceeded (without the user’s presence). This restriction applies only to PSD2 providers. |
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionDisabled | 406 Not Acceptable | The client tried to connect, reconnect or fetch a connection, but it appears to be disabled |
ConnectionFetchingStopped | 406 Not Acceptable | Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
DateOutOfAispConsentRange | 400 Bad Request | The passed |
DateTimeFormatInvalid | 400 Bad Request | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 Bad Request | Sending a datetime value that does not fit in admissible range |
FetchScopesNotAllowed | 406 Not Acceptable | The value of |
InvalidFromDate | 406 Not Acceptable | Invalid |
InvalidToDate | 406 Not Acceptable | Invalid |
JsonParseError | 400 Bad Request | We have received some other request format instead of JSON, or the body could not be parsed |
ProviderDisabled | 406 Not Acceptable | The accessed provider has the |
ProviderInactive | 406 Not Acceptable | The requested provider has the |
RateLimitExceeded | 406 Not Acceptable | Too many connections are being processed at the same time from one application |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}/refresh
https://www.saltedge.com/api/v5/connection/refresh
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connections/111111111111111111/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"attempt\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/v5/connection/refresh
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2020-07-06T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": true,
"categorize": true,
"created_at": "2020-07-06T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-07-06T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-07-06T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-07-06T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"last_success_at": "2020-07-06T16:16:19Z",
"next_refresh_possible_at": "2020-07-06T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2020-07-06T09:41:23Z"
}
}
{
"data": {
"country_code": "MD",
"created_at": "2020-07-06T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": true,
"categorize": true,
"created_at": "2020-07-06T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-07-06T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-07-06T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-07-06T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"last_success_at": "2020-07-06T16:16:19Z",
"next_refresh_possible_at": "2020-07-06T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2020-07-06T09:41:23Z"
}
}
Update
Update status
, store_credentials
, daily_refresh
or categorization
of a connection.
Parameters
Not all the connections can be automatically updated by Salt Edge, even if daily_refresh
flag is set to true
.
In case a particular provider requires user interaction during update (like SMS, OTP, etc), Salt Edge
will not attempt to update it.
status
string, optional
Possible values: inactive
.
daily_refresh
boolean, optional
Whether the connection will be refreshed daily
store_credentials
boolean, optional
Allows to not store credentials on Salt Edge side.
Note: The usage of this flag is not available for file
providers.
In order to update the connection, reconnect is required. It will not be possible to use refresh option if store_credentials
is set to false
Defaults to true
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
.
If nothing is sent, the categorization is kept as it was.
status
string, optional
Possible values: inactive
.
daily_refresh
boolean, optional
Whether the connection will be refreshed daily
store_credentials
boolean, optional
Allows to not store credentials on Salt Edge side.
Note: The usage of this flag is not available for file
providers.
In order to update the connection, reconnect is required. It will not be possible to use refresh option if store_credentials
is set to false
Defaults to true
.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
.
If nothing is sent, the categorization is kept as it was.
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
WrongRequestFormat | 400 Bad Request | The JSON request is incorrectly formed |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}
https://www.saltedge.com/api/v5/connection
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"status\": \"inactive\", \
\"store_credentials\": false, \
\"daily_refresh\": true, \
\"categorization\": \"personal\" \
} \
}" \
https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"status\": \"inactive\", \
\"store_credentials\": false, \
\"daily_refresh\": true, \
\"categorization\": \"personal\" \
} \
}" \
https://www.saltedge.com/api/v5/connection
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2020-07-06T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2020-07-06T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-07-06T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-07-06T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-07-06T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2020-07-06T16:16:19Z"
}
},
"last_success_at": "2020-07-06T16:16:19Z",
"next_refresh_possible_at": null,
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "inactive",
"store_credentials": false,
"updated_at": "2020-07-06T09:41:23Z"
}
}
{
"data": {
"country_code": "MD",
"created_at": "2020-07-06T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"categorization": "personal",
"show_consent_confirmation": false,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2020-07-06T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:04Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2020-07-06T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-07-06T16:16:19Z",
"show_consent_confirmation": false,
"consent_id": "555555555555555555",
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2020-07-06T16:16:19Z",
"id": "888888888888888888",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2020-07-06T16:16:19Z"
}
},
"last_success_at": "2020-07-06T16:16:19Z",
"next_refresh_possible_at": null,
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "inactive",
"store_credentials": false,
"updated_at": "2020-07-06T09:41:23Z"
}
}
Remove
Removes a connection from our system and revokes the consent.
All the associated accounts and transactions to that connection will be destroyed as well.
Salt Edge will send a destroy callback to your web application. Make sure to specify the Destroy URL
in your client account by accessing callbacks page.
Parameters
connection_id
string
Id
of the connection
connection_id
string
Id
of the connection
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ClientRestricted | 406 Not Acceptable | The client is in |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
RateLimitExceeded | 406 Not Acceptable | Too many connections are being processed at the same time from one application |
URL
https://www.saltedge.com/api/v5/connections/{connection.id}
https://www.saltedge.com/api/v5/connection
Method
DELETE
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/connection
Sample Response
{
"data": {
"id": "111111111111111111",
"removed": true
}
}
{
"data": {
"id": "111111111111111111",
"removed": true
}
}
Consents
A consent represents the end-user’s permission to access its data. The limits of this access are granted by the customer and are required to access the accounts, transactions and holder information through a specific provider.
The limits of a consent are represented by:
- data that is allowed to be accessed;
- period of time the data can be accessed for;
- interval of time to which the accessed data belongs to.
Attributes
id
string
The id
of the consent
scopes
array of strings
Data that is allowed to be fetched. Possible values inside array: account_details
, holder_information
, transactions_details
.
period_days
integer
The period the consent will be valid for
expires_at
string (date-time)
The date when the consent will expire
from_date
string (date)
The date from which the data has been allowed to be fetched
to_date
string (date)
The date until which the data has been allowed to be fetched
status
string
Consent status. Possible values: active
, expired
, revoked
.
collected_by
string
Entity who collected the consent. Possible values: client
, saltedge
.
revoked_at
string (date-time)
The date when consent was revoked
revoke_reason
string
Revoke reason. Possible values: expired
, client
, provider
, saltedge
.
created_at
string (date-time)
When the consent was created
updated_at
string (date-time)
When the consent was updated
id
string
The id
of the consent
scopes
array of strings
Data that is allowed to be fetched. Possible values inside array: account_details
, holder_information
, transactions_details
.
period_days
integer
The period the consent will be valid for
expires_at
string (date-time)
The date when the consent will expire
from_date
string (date)
The date from which the data has been allowed to be fetched
to_date
string (date)
The date until which the data has been allowed to be fetched
status
string
Consent status. Possible values: active
, expired
, revoked
.
collected_by
string
Entity who collected the consent. Possible values: client
, saltedge
.
revoked_at
string (date-time)
The date when consent was revoked
revoke_reason
string
Revoke reason. Possible values: expired
, client
, provider
, saltedge
.
created_at
string (date-time)
When the consent was created
updated_at
string (date-time)
When the consent was updated
List
Returns all the consents accessible to your application for a certain customer or a connection.
The consents are sorted in ascending order of their id
, so the latest consents will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
connection_id
string, optional
The id
of the connection containing the consents
customer_id
string, optional
The id
of the customer containing the consents, required unless connection_id
parameter is sent.
from_id
string, optional
The id
from which the next page of consents starts
from_id
string, optional
The id
from which the next page of consents starts
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
CustomerNotFound | 404 Not Found | A customer with such |
URL
https://www.saltedge.com/api/v5/consents?connection_id={connection.id}
https://www.saltedge.com/api/v5/consents
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/consents?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/consents
Sample Response
{
"data": [
{
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
],
"meta": {
"next_id": "555555555555555556",
"next_page": "/api/v5/consents?connection_id=111111111111111111&from_id=555555555555555556"
}
}
{
"data": [
{
"id": "555555555555555555",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
],
"meta": {
"next_id": "555555555555555556",
"next_page": "/api/v5/consents?from_id=555555555555555556"
}
}
Show
Returns the consent object.
Parameters
connection_id
string, optional
The id
of the connection containing the consent, required unless customer_id
parameter is sent
customer_id
string, optional
The id
of the customer containing the consents, required unless connection_id
parameter is sent.
consent_id
string
The id
of the consent
consent_id
string
The id
of the consent
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentNotFound | 404 Not Found | A consent with such an |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
CustomerNotFound | 404 Not Found | A customer with such |
URL
https://www.saltedge.com/api/v5/consents/{consent.id}?connection_id={connection.id}
https://www.saltedge.com/api/v5/consents/{consent.id}
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/consents/555555555555555555?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/consents/555555555555555555
Sample Response
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
}
{
"data": {
"id": "555555555555555555",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
}
Revoke
Allows you to revoke a consent for a connection or a customer.
Attributes
connection_id
string, optional
The id
of the connection containing the consent, required unless customer_id
parameter is sent
customer_id
string, optional
The id
of the customer containing the consents, required unless connection_id
parameter is sent.
consent_id
string
The id
of the consent
consent_id
string
The id
of the consent
Possible Errors
Error class | HTTP code | Description |
---|---|---|
AispConsentAlreadyRevoked | 406 Not Acceptable | The consent has already been revoked |
AispConsentNotFound | 404 Not Found | A consent with such an |
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
CustomerNotFound | 404 Not Found | A customer with such |
URL
https://www.saltedge.com/api/v5/consents/{consent.id}/revoke?connection_id={connection.id}
https://www.saltedge.com/api/v5/consents/{consent.id}/revoke
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/consents/555555555555555555/revoke?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
https://www.saltedge.com/api/v5/consents/555555555555555555/revoke
Sample Response
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"collected_by": "client",
"revoked_at": "2024-10-08T14:41:04Z",
"revoke_reason": "client",
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
}
{
"data": {
"id": "555555555555555555",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:04Z",
"from_date": "2024-09-08",
"to_date": null,
"collected_by": "client",
"revoked_at": "2024-10-08T14:41:04Z",
"revoke_reason": "client",
"created_at": "2024-10-08T11:41:04Z",
"updated_at": "2024-10-08T11:41:04Z"
}
}
Parameters object
The following represents the consent parameters object that is passed in requests.
scopes
array of strings
Data to be allowed for fetching.
The allowed values for this parameter must fall within the client’s allowed_fetch_scopes
and/or provider’s supported_fetch_scopes
restrictions. To change the client’s allowed scopes, please contact our Sales team.
Note: account_details
scope covers both accounts
and accounts_without_balance
attempt’s fetch_scopes.
Possible values inside array: account_details
, holder_information
, transactions_details
.
from_date
string (date), optional
Date to be allowed for fetching the data from. This parameter is used when scopes
parameter contains transactions_details
. The allowed values for this parameter must be within exactly 365 days ago.
to_date
string (date), optional
Date to be allowed for fetching the data until. The allowed values for this parameter must be equal or more than from_date
. Defaults to null
.
period_days
integer, optional
Determines the period the consent will be valid for. Defaults to null
(limitless) or provider’s max_consent_days
. The allowed value for this parameter must not be higher than the provider’s max_consent_days
.
scopes
array of strings
Data to be allowed for fetching.
The allowed values for this parameter must fall within the client’s allowed_fetch_scopes
and/or provider’s supported_fetch_scopes
restrictions. To change the client’s allowed scopes, please contact our Sales team.
Note: account_details
scope covers both accounts
and accounts_without_balance
attempt’s fetch_scopes.
Possible values inside array: account_details
, holder_information
, transactions_details
.
from_date
string (date), optional
Date to be allowed for fetching the data from. This parameter is used when scopes
parameter contains transactions_details
. The allowed values for this parameter must be within exactly 365 days ago.
to_date
string (date), optional
Date to be allowed for fetching the data until. The allowed values for this parameter must be equal or more than from_date
. Defaults to null
.
period_days
integer, optional
Determines the period the consent will be valid for. Defaults to null
(limitless) or provider’s max_consent_days
. The allowed value for this parameter must not be higher than the provider’s max_consent_days
.
Attempts
Represents a detailed description of a particular connection attempt. They are meant to provide you with more information about the established connections for further usage in technical and statistical purposes.
Attributes
api_mode
string
The API mode of the customer that queried the API. Possible values: app
, service
.
api_version
string
The API version in which the attempt was created
automatic_fetch
boolean
Whether the connection related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh
in connection
categorize
boolean
Whether attempt is categorized Defaults to true
.
created_at
string (date-time)
When the attempt was made
custom_fields
object
The custom fields that had been sent when creating connection/connect_session/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
.
remote_ip
string
The IP of the device that created the attempt
exclude_accounts
array of strings
The ids
of accounts that do not need to be refreshed
user_present
boolean
Whether the request was initiated by the end-user of your application
customer_last_logged_at
string (date-time)
The datetime when user was last active in your application
fail_at
string (date-time)
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for attempt
fail_message
string
Message that describes the error class
fetch_scopes
array of strings
Fetching mode. Possible values inside array: accounts
, accounts_without_balance
, holder_info
, transactions
.
finished
boolean
Whether the connection had finished fetching
finished_recent
boolean
Whether the connection had finished data for recent range
from_date
string (date)
Date from which the data had been fetched
id
string
Id
of the attempt
interactive
boolean
Whether the connection related to the attempt is interactive
locale
string
The language of the Connect widget and of the returned error message(s) in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the connection was partially fetched
store_credentials
boolean
Whether the credentials were stored on our side
success_at
string (date-time)
When the attempt succeeded and finished
to_date
string (date-time)
Date until which the data has been fetched
updated_at
string (date-time)
When last attempt update occurred
show_consent_confirmation
boolean
Whether any consent was given for this connection
include_natures
array of strings
The natures of the accounts that need to be fetched
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
.
The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during connect_session/reconnect or connect_session/refresh.
mark_as_pending
: leaves identified duplicated transactions inPending
status for clients that establish connections with providers having a non-nullcustom_pendings_period
.mark_as_duplicate
: identifies transactions as duplicated and sets theduplicated
flag totrue
.delete_transactions
: removes identified duplicated transactions.
api_mode
string
The API mode of the customer that queried the API. Possible values: app
, service
.
api_version
string
The API version in which the attempt was created
automatic_fetch
boolean
Whether the connection related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh
in connection
categorize
boolean
Whether attempt is categorized Defaults to true
.
created_at
string (date-time)
When the attempt was made
custom_fields
object
The custom fields that had been sent when creating connection/connect_session/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
.
remote_ip
string
The IP of the device that created the attempt
exclude_accounts
array of strings
The ids
of accounts that do not need to be refreshed
user_present
boolean
Whether the request was initiated by the end-user of your application
customer_last_logged_at
string (date-time)
The datetime when user was last active in your application
fail_at
string (date-time)
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for attempt
fail_message
string
Message that describes the error class
fetch_scopes
array of strings
Fetching mode. Possible values inside array: accounts
, accounts_without_balance
, holder_info
, transactions
.
finished
boolean
Whether the connection had finished fetching
finished_recent
boolean
Whether the connection had finished data for recent range
from_date
string (date)
Date from which the data had been fetched
id
string
Id
of the attempt
interactive
boolean
Whether the connection related to the attempt is interactive
locale
string
The language of the Connect widget and of the returned error message(s) in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the connection was partially fetched
store_credentials
boolean
Whether the credentials were stored on our side
success_at
string (date-time)
When the attempt succeeded and finished
to_date
string (date-time)
Date until which the data has been fetched
updated_at
string (date-time)
When last attempt update occurred
show_consent_confirmation
boolean
Whether any consent was given for this connection
include_natures
array of strings
The natures of the accounts that need to be fetched
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
.
The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during connect_session/reconnect or connect_session/refresh.
mark_as_pending
: leaves identified duplicated transactions inPending
status for clients that establish connections with providers having a non-nullcustom_pendings_period
.mark_as_duplicate
: identifies transactions as duplicated and sets theduplicated
flag totrue
.delete_transactions
: removes identified duplicated transactions.
The values of the interactive
and automatic_fetch
attributes are subject to change, since the customers can activate or deactivate the interactive requirements separately with their bank or the bank may change its authorization flow (for example, requiring SCA).
Sample object
{
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"daily_refresh": false,
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888888",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
}
{
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"daily_refresh": false,
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888888",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
}
Stages
The following represents the objects you get in the stages
field of the attempt object.
created_at
string (date-time)
When the stage was created
id
string
The id
of the stage
interactive_fields_names
array of strings, optional
The interactive fields that are currently required by the provider. Appears only for the interactive connections Defaults to null
.
interactive_html
string, optional
HTML code that shows the current interactive state of the connection. Appears only for the interactive connections Defaults to null
.
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
.
updated_at
string (date-time)
When the stage was last updated
created_at
string (date-time)
When the stage was created
id
string
The id
of the stage
interactive_fields_names
array of strings, optional
The interactive fields that are currently required by the provider. Appears only for the interactive connections Defaults to null
.
interactive_html
string, optional
HTML code that shows the current interactive state of the connection. Appears only for the interactive connections Defaults to null
.
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
.
updated_at
string (date-time)
When the stage was last updated
List
Returns a paginated list of all attempts for a certain connection.
connection_id
string
The id
of the connection whose attempts are to be fetched
URL
https://www.saltedge.com/api/v5/attempts?connection_id={connection.id}
https://www.saltedge.com/api/v5/attempts
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/attempts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/attempts
Sample response
{
"data": [
{
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888888",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
}
],
"meta": {
"next_id": "777777777777777778",
"next_page": "/api/v5/attempts?connection_id=111111111111111111&from_id=777777777777777778"
}
}
{
"data": [
{
"api_mode": "app",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"last_stage": {
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888888",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
}
],
"meta": {
"next_id": "777777777777777778",
"next_page": "/api/v5/attempts?from_id=777777777777777778"
}
}
Show
Returns a single attempt object.
connection_id
string
The id
of the connection whose attempts are to be fetched
attempt_id
string
The id
of attempt
attempt_id
string
The id
of attempt
URL
https://www.saltedge.com/api/v5/attempts/{attempt.id}?connection_id={connection.id}
https://www.saltedge.com/api/v5/attempts/{attempt.id}
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/attempts/777777777777777777?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/attempts/777777777777777777
Sample response
{
"data": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"stages": [
{
"created_at": "2024-10-08T12:41:05Z",
"id": "888888888888888881",
"interactive_fields_names": null,
"interactive_html": null,
"name": "start",
"updated_at": "2024-10-08T12:41:05Z"
},
{
"created_at": "2024-10-08T12:51:05Z",
"id": "888888888888888882",
"interactive_fields_names": null,
"interactive_html": null,
"name": "connect",
"updated_at": "2024-10-08T12:51:05Z"
},
{
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888883",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
]
}
}
{
"data": {
"api_mode": "app",
"api_version": "5",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorize": true,
"created_at": "2024-10-08T12:41:05Z",
"customer_last_logged_at": "2024-10-08T11:41:05Z",
"custom_fields": {
},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [
],
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": [
"accounts",
"transactions"
],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2024-10-08T13:41:05Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:05Z",
"show_consent_confirmation": true,
"include_natures": [
"account",
"card",
"bonus"
],
"stages": [
{
"created_at": "2024-10-08T12:41:05Z",
"id": "888888888888888881",
"interactive_fields_names": null,
"interactive_html": null,
"name": "start",
"updated_at": "2024-10-08T12:41:05Z"
},
{
"created_at": "2024-10-08T12:51:05Z",
"id": "888888888888888882",
"interactive_fields_names": null,
"interactive_html": null,
"name": "connect",
"updated_at": "2024-10-08T12:51:05Z"
},
{
"created_at": "2024-10-08T13:41:05Z",
"id": "888888888888888883",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2024-10-08T13:41:05Z"
}
]
}
}
Parameters object
The following represents the attempt parameters object that is passed in requests.
fetch_scopes
array of strings, optional
from_date
string (date), optional
to_date
string (date), optional
Date until which you want to fetch data for your connection. Defaults to null
(today). The allowed values for this parameter must be equal or more than from_date
and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.
fetched_accounts_notify
boolean, optional
Whether Salt Edge should send a success callback after fetching accounts. Defaults to false
.
custom_fields
object, optional
A JSON object, which will be sent back on any of your callbacks. Defaults to {}
.
locale
string, optional
The language of the Connect widget and of the returned error message(s) in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_natures
array of strings, optional
The natures of the accounts that need to be fetched. Check accounts attributes for possible values. If null
, all accounts will be fetched. Defaults to null
.
customer_last_logged_at
string (date-time), optional
The datetime when user was last active in your application
exclude_accounts
array of strings, optional
Array of account ids
which will not be fetched. Applied to reconnect
and refresh
atempts. Defaults to []
.
store_credentials
boolean
Whether the credentials should be stored on Salt Edge side
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
. The default is set to mark_as_pending
.
The provided value remains unchanged until other value is sent on connect_session/reconnect or connect_session/refresh.
mark_as_pending
- leaves identified duplicated transactions inPending
status for clients that establish connections with providers having a non-nullcustom_pendings_period
mark_as_duplicate
- identifies transactions as duplicated and sets theduplicated
flag totrue
delete_trasactions
- removes identified duplicated transactions
user_present
boolean, optional
Whether the request was initiated by the end-user of your application. It is taken into account only for PSD2-compliant providers and used for reconnect
and refresh
.
return_to
string, optional
The URL the user will be redirected to, defaults to client’s home URL. If the provider has api
mode and interactive true
then this field is mandatory
.
fetch_scopes
array of strings, optional
from_date
string (date), optional
to_date
string (date), optional
Date until which you want to fetch data for your connection. Defaults to null
(today). The allowed values for this parameter must be equal or more than from_date
and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.
fetched_accounts_notify
boolean, optional
Whether Salt Edge should send a success callback after fetching accounts. Defaults to false
.
custom_fields
object, optional
A JSON object, which will be sent back on any of your callbacks. Defaults to {}
.
locale
string, optional
The language of the Connect widget and of the returned error message(s) in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_natures
array of strings, optional
The natures of the accounts that need to be fetched. Check accounts attributes for possible values. If null
, all accounts will be fetched. Defaults to null
.
customer_last_logged_at
string (date-time), optional
The datetime when user was last active in your application
exclude_accounts
array of strings, optional
Array of account ids
which will not be fetched. Applied to reconnect
and refresh
atempts. Defaults to []
.
store_credentials
boolean
Whether the credentials should be stored on Salt Edge side
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
. The default is set to mark_as_pending
.
The provided value remains unchanged until other value is sent on connect_session/reconnect or connect_session/refresh.
mark_as_pending
- leaves identified duplicated transactions inPending
status for clients that establish connections with providers having a non-nullcustom_pendings_period
mark_as_duplicate
- identifies transactions as duplicated and sets theduplicated
flag totrue
delete_trasactions
- removes identified duplicated transactions
user_present
boolean, optional
Whether the request was initiated by the end-user of your application. It is taken into account only for PSD2-compliant providers and used for reconnect
and refresh
.
return_to
string, optional
The URL the user will be redirected to, defaults to client’s home URL. If the provider has api
mode and interactive true
then this field is mandatory
.
user_present
is used only for PSD2-compliant providers
and has nothing to do with prioritizing or speeding up the fetching of connections made via screen-scraping or other technology. If user_present
is set to false
, a limit of 4 background fetches will be enforced as per PSD2, all requests that exceed this limit will return a BackgroundFetchLimitExceeded. Note that for create
/reconnect
default value is set to true
, for refresh
default value is set to false
.
Accounts
Any connection can have one or more accounts. The accounts are bound to a currency so that all the transactions within a single account are in the same currency.
Sometimes, the provider allows the user to have several currencies grouped under the same account. For example, if a user holds a debit card that supports 3 currencies, the corresponding connection will have 3 accounts, each with one of the debit card’s currencies.
Attributes
id
string
The id
of the account
name
string
The unique name of the account
Note: The name directly identifies the account. In case the account’s name has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
nature
string
The type of the account
Note: for credit_card
nature, the balance represents the sum of all negative transactions, the positive ones do not count.
Possible values: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
.
balance
number
The account’s current balance
currency_code
string
One of the possible values for currency codes. Maximum 3 letters.
Note: The currency directly identifies the account. In case the account’s currency code has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
extra
object
Extra data associated with the account
connection_id
string
The id
of the connection the account belongs to
created_at
string (date-time)
Time and date when the account was imported
updated_at
string (date-time)
The last time when the account’s balance was changed or new transactions were imported
id
string
The id
of the account
name
string
The unique name of the account
Note: The name directly identifies the account. In case the account’s name has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
nature
string
The type of the account
Note: for credit_card
nature, the balance represents the sum of all negative transactions, the positive ones do not count.
Possible values: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
.
balance
number
The account’s current balance
currency_code
string
One of the possible values for currency codes. Maximum 3 letters.
Note: The currency directly identifies the account. In case the account’s currency code has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
extra
object
Extra data associated with the account
connection_id
string
The id
of the connection the account belongs to
created_at
string (date-time)
Time and date when the account was imported
updated_at
string (date-time)
The last time when the account’s balance was changed or new transactions were imported
Sample Object
{
"id": "333333333333333333",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:05Z",
"updated_at": "2024-10-08T12:41:05Z"
}
{
"id": "333333333333333333",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:05Z",
"updated_at": "2024-10-08T12:41:05Z"
}
List
You can see the list of accounts of a connection.
The accounts are sorted in ascending order of their ids
, so the newest accounts will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
connection_id
string
The id
of the connection whose attempts are to be fetched
customer_id
string, optional
The id
of the customer containing the accounts, required unless connection_id
parameter is sent. It will be ignored if connection_id
is present
from_id
string, optional
The id
of the account which the list starts with
customer_id
string, optional
The id
of the customer containing the accounts, required unless connection_id
parameter is sent. It will be ignored if connection_id
is present
from_id
string, optional
The id
of the account which the list starts with
Possible Errors
Error class | HTTP code | Description |
---|---|---|
ConnectionNotFound | 404 Not Found | We could not find a connection with the requested |
URL
https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}
https://www.saltedge.com/api/v5//accounts
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/accounts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/accounts
Sample Response
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"extra": {
"client_name": "Fake name"
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T11:41:05Z",
"updated_at": "2024-10-08T11:41:05Z"
},
{
"id": "333333333333333334",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:05Z",
"updated_at": "2024-10-08T12:41:05Z"
}
],
"meta": {
"next_id": "333333333333333335",
"next_page": "/api/v5/accounts?connection_id=111111111111111111&from_id=333333333333333335"
}
}
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"extra": {
"client_name": "Fake name"
},
"created_at": "2024-10-08T11:41:05Z",
"updated_at": "2024-10-08T11:41:05Z"
},
{
"id": "333333333333333334",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:05Z",
"updated_at": "2024-10-08T12:41:05Z"
}
],
"meta": {
"next_id": "333333333333333335",
"next_page": "/api/v5/accounts?from_id=333333333333333335"
}
}
Nature
An account can be of one of the several types, as described by the nature
field:
Payment account natures:
- account (nature assigned to current account or when the account type could not be identified)
- card (the type of card could not be identified)
- checking
- credit_card
- debit_card
- ewallet
- loan*
- mortgage*
- savings*
* Depending on the bank, it can be handled as payment
or non-payment
account
Non-payment account natures:
- bonus
- insurance
- investment
- credit
Although these values do not affect neither the account’s behavior, nor its properties, they might provide some additional information to the end-user.
Extra
The following represents the object you get in the extra
field of the account object.
General accounts extra fields:
account_name
string
Changeable name of the account.
account_number
string
Internal bank account number.
assets
array of strings
Array of crypto codes and their amounts assigned to investment account.
available_amount
number
Available amount in the account’s currency.
balance_type
string
Examples: interimAvailable
, closingBooked
, interimBooked
, authorised
, expected
, BOOKED
, CLAV
, CLBD
, XPCD
, OTHR
, etc.
Note: The value is specific to the financial institution and can vary depending on the API standard, the bank’s implementation, the account’s type, country/region peculiarities, etc. This field holds an informative meaning. Usually, it is used to verify the balance consistency between customers of the same bank or between banks within the same country.
blocked_amount
number
The amount currently blocked in account’s currency.
card_type
string
Type of the card
account. Possible values: american_express
, china_unionpay
, diners_club
, jcb
, maestro
, master_card
, uatp
, visa
, mir
.
cards
array of strings
List of masked card numbers linked to the account.
client_name
string
Account client owner.
closing_balance
number
Account balance at the end of an accounting period.
credit_limit
number
Maximum amount of money that is allowed to be spent in account’s currency.
current_date
string (date)
Date of provider statement generation (applicable to banks).
current_time
string (date-time)
Time of provider statement generation (applicable to banks).
expiry_date
string (date)
Card expiry date.
iban
string
Account’s IBAN.
bban
string
Basic Bank Account Number.
interest_rate
number
Interest rate of the account as percentage value.
interest_type
string
Type of account interest used with interest_rate.
floating_interest_rate
object
Minimum and maximum value of the interest rate.
remaining_payments
number
The number of remaining payments to pay off the loan.
penalty_amount
number
The amount of the penalty.
next_payment_amount
number
Next payment amount for loans or credits.
next_payment_date
string (date)
Next payment date for loans or credits.
open_date
string (date)
The date when any type of account/card was opened.
opening_balance
number
Account balance that is brought forward from the end of one accounting period to the beginning of a new accounting period.
partial
boolean
Account transactions were not imported or imported partially because of some internal error on the provider’s side.
provider_account_id
string
A unique ID assigned by the Provider to identify an account within its system.
raw_balance
string
- The original account balance response returned by the bank.
- It is added only for
regulated: true
providers. - It is returned only if the separate
balances
parameter is present in the bank’s original response.
sort_code
string
Routing number(US)/BSB code(Australia)/sort code(UK).
statement_cut_date
string (date)
Date when current statement becomes previous one.
status
string
Shows whether the account is active
, inactive
or unauthorized
.
swift
string
Account SWIFT code.
total_payment_amount
number
Total payment amount for loans or credits.
transactions_count
object
Number of transactions, separated by posted and pending.
payment_type
string
Account payment method.
cashback_amount
number
Accumulated CashBack / Cash Benefit.
monthly_total_payment
number
The amount a borrower was paid for a month.
minimum_payment
number
The lowest amount you can pay on your credit card to avoid penalties.
account_name
string
Changeable name of the account.
account_number
string
Internal bank account number.
assets
array of strings
Array of crypto codes and their amounts assigned to investment account.
available_amount
number
Available amount in the account’s currency.
balance_type
string
Examples: interimAvailable
, closingBooked
, interimBooked
, authorised
, expected
, BOOKED
, CLAV
, CLBD
, XPCD
, OTHR
, etc.
Note: The value is specific to the financial institution and can vary depending on the API standard, the bank’s implementation, the account’s type, country/region peculiarities, etc. This field holds an informative meaning. Usually, it is used to verify the balance consistency between customers of the same bank or between banks within the same country.
blocked_amount
number
The amount currently blocked in account’s currency.
card_type
string
Type of the card
account. Possible values: american_express
, china_unionpay
, diners_club
, jcb
, maestro
, master_card
, uatp
, visa
, mir
.
cards
array of strings
List of masked card numbers linked to the account.
client_name
string
Account client owner.
closing_balance
number
Account balance at the end of an accounting period.
credit_limit
number
Maximum amount of money that is allowed to be spent in account’s currency.
current_date
string (date)
Date of provider statement generation (applicable to banks).
current_time
string (date-time)
Time of provider statement generation (applicable to banks).
expiry_date
string (date)
Card expiry date.
iban
string
Account’s IBAN.
bban
string
Basic Bank Account Number.
interest_rate
number
Interest rate of the account as percentage value.
interest_type
string
Type of account interest used with interest_rate.
floating_interest_rate
object
Minimum and maximum value of the interest rate.
remaining_payments
number
The number of remaining payments to pay off the loan.
penalty_amount
number
The amount of the penalty.
next_payment_amount
number
Next payment amount for loans or credits.
next_payment_date
string (date)
Next payment date for loans or credits.
open_date
string (date)
The date when any type of account/card was opened.
opening_balance
number
Account balance that is brought forward from the end of one accounting period to the beginning of a new accounting period.
partial
boolean
Account transactions were not imported or imported partially because of some internal error on the provider’s side.
provider_account_id
string
A unique ID assigned by the Provider to identify an account within its system.
raw_balance
string
- The original account balance response returned by the bank.
- It is added only for
regulated: true
providers. - It is returned only if the separate
balances
parameter is present in the bank’s original response.
sort_code
string
Routing number(US)/BSB code(Australia)/sort code(UK).
statement_cut_date
string (date)
Date when current statement becomes previous one.
status
string
Shows whether the account is active
, inactive
or unauthorized
.
swift
string
Account SWIFT code.
total_payment_amount
number
Total payment amount for loans or credits.
transactions_count
object
Number of transactions, separated by posted and pending.
payment_type
string
Account payment method.
cashback_amount
number
Accumulated CashBack / Cash Benefit.
monthly_total_payment
number
The amount a borrower was paid for a month.
minimum_payment
number
The lowest amount you can pay on your credit card to avoid penalties.
Investment accounts extra fields:
investment_amount
number
Total invested amount.
unit_price
number
Price per unit (used with units).
units
number
Amount of units owned (used with unit_price).
indicative_unit_price
number
Indicative price per unit (used with units).
interest_income
number
Amount of interest income/profit.
interest_amount
number
Interest amount in currency.
profit_amount
number
Amount of profit/loss of investment account.
profit_rate
number
Investment account rate of profit/loss as percentage value.
asset_class
string
Class of investment asset.
product_type
string
Investment product type.
total_unit_value
number
Total units value of fund holding.
fund_holdings
object
Fund holdings list with own values such as investment_percentage
, balance
, bid_price
, value
, value_date
, total_quantity
, available_quantity
, actual_price
, actual_value
.
investment_amount
number
Total invested amount.
unit_price
number
Price per unit (used with units).
units
number
Amount of units owned (used with unit_price).
indicative_unit_price
number
Indicative price per unit (used with units).
interest_income
number
Amount of interest income/profit.
interest_amount
number
Interest amount in currency.
profit_amount
number
Amount of profit/loss of investment account.
profit_rate
number
Investment account rate of profit/loss as percentage value.
asset_class
string
Class of investment asset.
product_type
string
Investment product type.
total_unit_value
number
Total units value of fund holding.
fund_holdings
object
Fund holdings list with own values such as investment_percentage
, balance
, bid_price
, value
, value_date
, total_quantity
, available_quantity
, actual_price
, actual_value
.
Insurance accounts extra fields:
premium_frequency
string
Frequency of premium payments.
policy_status
string
Current policy status.
life_assured_name
string
Name of the person who is assured.
premium_amount
number
Premium amount to be paid.
single_premium_amount
number
Single premium amount to be paid.
financial_consultant
string
Financial consultant name.
total_reversionary_bonus
number
Reversionary bonus accumulated amount.
gross_surrender
number
Current Gross Surrender value.
guaranteed_gross_surrender
number
Guaranteed Gross Surrender value.
reversionary_bonus_cash_value
number
Cash value of reversionary bonus.
owned_policy_amount
number
Amount currently own on policy.
policy_loan_limit
number
Maximum amount of additional Policy Loan.
policy_converted_to_paid_up
number
New assured sum if Policy is converted to paid up.
paid_up_conversion_reversionary_bonus
number
Reversionary bonus amount after Policy to paid up
conversion.
policy_components
object
Policy components with own values such as status
, amount_assured
, amount_premium
, start_date
, expiry_date
, premium_expiry_date
, assured_name
.
premium_frequency
string
Frequency of premium payments.
policy_status
string
Current policy status.
life_assured_name
string
Name of the person who is assured.
premium_amount
number
Premium amount to be paid.
single_premium_amount
number
Single premium amount to be paid.
financial_consultant
string
Financial consultant name.
total_reversionary_bonus
number
Reversionary bonus accumulated amount.
gross_surrender
number
Current Gross Surrender value.
guaranteed_gross_surrender
number
Guaranteed Gross Surrender value.
reversionary_bonus_cash_value
number
Cash value of reversionary bonus.
owned_policy_amount
number
Amount currently own on policy.
policy_loan_limit
number
Maximum amount of additional Policy Loan.
policy_converted_to_paid_up
number
New assured sum if Policy is converted to paid up.
paid_up_conversion_reversionary_bonus
number
Reversionary bonus amount after Policy to paid up
conversion.
policy_components
object
Policy components with own values such as status
, amount_assured
, amount_premium
, start_date
, expiry_date
, premium_expiry_date
, assured_name
.
Transactions
A transaction represents a movement of funds. Any transaction can represent a monetary transfer, withdrawal, income or expense interchange. Transactions are retained in a connection’s accounts, and are imported from one of the providers.
Category
Account Information API uses an algorithm for the automatic categorization of transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories. We also expose an API route for your applications to improve the categorization process based on your end-users’ behavior.
Duplication
Although we import most of the data from the providers thoroughly checking the transactions for duplicates, the providers might change the format of some data, causing us to return transactions that have different data, but are duplicates to your end-users. You can use the duplicate action in order to let us know about a duplicate so that we can take immediate actions.
Attributes
id
string
Id of the transaction
mode
string
Possible values: normal
, fee
, transfer
.
status
string
Possible values: posted
, pending
.
made_on
string (date)
The date when the transaction was made
amount
number
Transaction’s amount
currency_code
string
Transaction’s currency code
description
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
account_id
string
The id
of the account the transaction belongs to
created_at
string (date-time)
Time and date when the transaction was imported
updated_at
string (date-time)
The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client
id
string
Id of the transaction
mode
string
Possible values: normal
, fee
, transfer
.
status
string
Possible values: posted
, pending
.
made_on
string (date)
The date when the transaction was made
amount
number
Transaction’s amount
currency_code
string
Transaction’s currency code
description
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
account_id
string
The id
of the account the transaction belongs to
created_at
string (date-time)
Time and date when the transaction was imported
updated_at
string (date-time)
The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client
Sample object
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "Money spent on company advertising",
"category": "advertising",
"extra": {
"merchant_id": "b3e8ec2349df872072c051e0c...",
"original_amount": -3974.6,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:05Z",
"updated_at": "2024-10-07T14:41:05Z"
}
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"