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 an account

a. Input all the necessary data and create an account on the Sign Up page.

b. Confirm your Email.

c. Add your technical team members who will work on the next integration steps on the Team page and choose the specific roles for them.

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.

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.

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.

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

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.

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.

• Download Swagger JSON for Services
• Download Swagger JSON for Mobile Apps without a backend

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, and fake_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.

Encrypted credentials

Any endpoint that accept or require a “credentials” object (like Creating connections), can also accept encrypted_credentials instead of credentials.

where credentials_json is the original credentials object encoded as a JSON string.

This feature is enabled separately for each client and is subject to additional fees. For more information please contact us.

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 to oauth.
• 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.

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.

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.

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 ActionNotAllowedErrorerror. 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 is application/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-04-17T11:13:51.358Z"
  }
}

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-04-17T11:13:51.364Z"
  }
}

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-04-16T11:13:51Z"
  }
}

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-04-16T12:13:51Z",
    "interactive_fields_names": ["image"]
  },
  "meta": {
    "version": "5",
    "time": "2024-04-16T11:13:51Z"
  }
}

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-04-16T11:13:51Z"
  }
}

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-04-16T12:13:51Z",
    "interactive_fields_names": [],
    "custom_fields":            { "key": "value" }
  },
  "meta": {
    "version": "5",
    "time":    "2024-04-16T11:13:51Z"
  }
}

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": {}
  }
}

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-04-16T11:13:51Z"
  }
}

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-04-16T11:13:51Z"
  }
}

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

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

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 and ProviderUnavailable (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.

AISP API Reference

• Errors can occur if the client configures API requests incorrectly.
• These errors are not displayed to end-users.
  

Client Configuration

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

Response

Possible Errors

No specific errors

Providers

A provider is a source of financial data. We recommend you update all of the providers’ fields at least daily.

Attributes

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

Possible Errors

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

Possible Errors

Fields

There are several types of fields as marked by their nature attribute.