Data types

All of the responses returned by Salt Edge API are in the JSON format. The description of the data types encoded in a JSON response is below.

boolean
true or false

a boolean value

date

a date in the YYYY-MM-DD format

datetime

a date in the ISO-8601 format

float

a value corresponding to a real number using the double-precision representation

integer

a value corresponding to a 64-bit unsigned integer number

object

a string representing a JSON object (please refer to the RFC 4627 for more information)

string

a UTF-8 compatible sequence of characters

boolean
true or false

a boolean value

date

a date in the YYYY-MM-DD format

datetime

a date in the ISO-8601 format

float

a value corresponding to a real number using the double-precision representation

integer

a value corresponding to a 64-bit unsigned integer number

object

a string representing a JSON object (please refer to the RFC 4627 for more information)

string

a UTF-8 compatible sequence of characters

Security

Encryption

All sensitive data is encrypted using 2048-bit keys, which allows us to set a secure environment for the client. None of the sent credentials are saved within the system as plain text, and are always encrypted using an asymmetric encryption algorithm. If there is something wrong with the client’s data, they will be notified with a specific message.

We are continuously monitoring Salt Edge API, securing it from malware attacks, and constantly updating the security layers of our infrastructure. Salt Edge offers you a stable and attack-proof environment where you can keep all your credentials intact, and hidden from a potential attacker.

Certificate

We recommend you to check the Salt Edge SSL certificate fingerprint on every connection.

HTTP Public Key Pinning (HPKP)

Salt Edge returns a Public-Key-Pins header in all of its responses. Modern browsers like Chrome and Firefox already use it to validate the public key of Salt Edge certificate. Additionally, you can use this header to validate the certificate on your backends during API consumption. For more information see https://developer.mozilla.org/en-US/docs/Web/HTTP/PublicKeyPinning.

Bug Bounty Program

Salt Edge truly believes that collaborating closely with experienced security researchers from across the globe is an essential part of identifying and mitigating security vulnerabilities in Salt Edge infrastructure. Therefore, Salt Edge is happy to reward the researchers that have identified original and previously unreported vulnerabilities.

If you believe to have found a security vulnerability, we encourage you to visit our Bug Bounty Program.

Signature

For live clients absolutely all requests should be signed. For the clients with other statuses, it is optional:

  • If the signature headers aren’t sent, the request will be performed without any signature validations;
  • If the signature headers are sent, the request signature will be verified.

Before all, service clients should provide their public key by inserting its content in keys and secrets page.

The private key should be securely stored on your server.

In case of possible security breach, the private key should be regenerated and the public key should be updated in your profile.

Signature headers

For a better understanding of how to adapt the corresponding headers in your application, take a look at the sample applications for platforms such as:

The following headers are required for your request to be considered signed:

  • Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. The maximum value is 1 hour from now in UTC, otherwise ExpiresAtInvalid error will be raised;
  • Signature - base64 encoded SHA256 signature of the string represented in the form Expires-at|request_method|original_url|post_body|sha256_of_uploaded_file| - 5 parameters concatenated with a vertical bar |, signed with the client’s private key.

The fields request_method, original_url, post_body and sha256_of_uploaded_file from the Signature header represent:

  • request_method - uppercase method of the HTTP request. Example: GET, POST, PATCH, PUT, DELETE, etc.;
  • original_url - the full requested URL, with all its complementary parameters;
  • post_body - the request post body. Should be left empty if it is a GET request, or the body is empty;
  • sha256_of_uploaded_file - the uploaded file digested through SHA256 algorithm. Should be left empty if it is a GET request, or no file uploaded.

An example of the string that is to be used to generate the signature looks as follows:

  • GET string example: 1413802718|GET|https://www.saltedge.com/api/v5/providers?from_id=123|;
  • POST string example (without file): 1413802718|POST|https://www.saltedge.com/api/v5/customers/|{"data":{"identifier":"my_unique_identifier"}};
  • POST string example (with file): 1413802718|POST|https://www.saltedge.com/api/v5/customers/|{"data":{"identifier":"my_unique_identifier"}}|6979a174280bdf7319940c59fabbd2b8|.

RSA keys generation instruction

1) Install openssl package

Mac OS X

Install via Homebrew: brew install openssl

Windows

Windows complete package .exe installer

Ubuntu Linux

apt-get install openssl

Mac OS X

Install via Homebrew: brew install openssl

Windows

Windows complete package .exe installer

Ubuntu Linux

apt-get install openssl

2) Create the RSA Key Pair

For Mac OS X and Ubuntu Linux:

  • Type in the command line:

    openssl genrsa -out private.pem 2048
    openssl rsa -pubout -in private.pem -out public.pem
    

For Windows:

  • After the package has been installed, a folder with name: OpenSSL-Win32 should appear at the install path.

  • Next, open a Command Prompt and change your current directory to this folder by typing:

    cd C:\OpenSSL-Win32\bin, where C:\OpenSSL-Win32 should be replaced with the install path.

  • Then you can generate RSA keys by typing:

    openssl genrsa -out private.pem 2048
    openssl rsa -pubout -in private.pem -out public.pem
    

then follow the instructions that appear afterwards.

The pseudocode to generate the signature

base64(sha256_signature(private_key, "Expires-at|request_method|original_url|post_body|sha256_of_uploaded_file|"))

Headers example:

Expires-at: 1413466421
Signature: 0o6LgMnlG7FX5tWLoKd6V5jlktodP8I/3vWqh1pOZvPgMn/WPq5YqZWPc0teey135RO2muFThcvuZJtcbaUje1UWFHyWhTh89guHJ47pgBB7w0LMkRw3XskEsafEUZketeTY/NtyeU7ETHHm2Tlw8IJho+gk51Rtp7JJPanw2OZG/6BElFcL0qGs4ohTmJUKKsdI1eo5jseFqF+sX0T4dRYqL7ebhDCD8YsYdsZ9zxlX88+YtUQnEqGbswOH4saGaQNH9NjxST2NS8MFtCU7uwZGybBk4i0l1wtbTJwfgaa+yb2L7l0ltIgxZFJzQOShpVOgI+o8fUg31lOblmMVkpyvXJ/n5Ed2u0nA1yMWkQUPpu03Xkh2RG7qbBOEq6+A374OnhUDwi5TUqYrY89paPwq/A7z2lc56Q84T+NrSLdi0x0aejpp6Cn90Yqpbs04dIio579+KyLm/8XoZ4p9k7vz6vTpDITyTAc93/KHnqeT1hTp7AWMaxuGfEI361fyZLDzkSvnHq4QzMkJOKhPELxSji99dm0LCSZpUiUhTTU3G09LvLBCEFLvbGJzxlO7NgqOGVPMlEc4fJqzU/jrTfkodn4DtzaOJghlXynithKIUBAkpNY9QGPOQIMvcbOZfhilm+bjWuYeNpeALvbqY3ONcibHLjc8ItAVMzORSFg=

Authentication

For more information about the Expires-at and Signature headers, see Signature page of the guides.

All of the resources queried through the API are protected by 4 different headers, on different levels of security, as shown on the diagramm below:

Headers diagramm v5

App ID and Secret

The App-id and Secret headers should be passed in with every request. Keep in mind that you can obtain these keys on your API keys page.

Here’s an example request listing all the countries that the API currently supports.

Services and Apps authentication

There 2 types of access to Salt Edge API - as a service or as an app. The type of access is set up by the type of the API key that you are using while accessing the API:

  • service - intended to be used by backends, all the API endpoints are available

  • app - intended to be used by Applications without a backend. Some endpoints for this type of Secret are not available, because mobile applications can be easily compromised/reverse engineered, hence the are security constraints in place to mitigate this

Customer secret

In order to create connect_sessions, connections and oauth providers, your app should pass the Customer-secret header inside the request, so the API can identify which customer the entity belongs to.

Connection secret

Since an app should be able to query information only about the connections it created, requests that query or modify connections should be signed with a Connection-secret header.

URL

https://www.saltedge.com/api/v5/transactions?account_id={account.id}

https://www.saltedge.com/api/v5/transactions?account_id={account.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/transactions?account_id=100
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/transactions?account_id=100

Versioning

Any incompatible changes to the API will result in incremented versions of the API, which will change the resource URLs.

At some point, the current version will be announced as Deprecated and you will have 12 months to switch your applications to a newer version of the API. All clients will be notified of any deprecation in the API.

New fields can be added to the current API version, at any time without preliminary warning with subsequent documentation added afterward. However, already documented fields cannot be modified or removed. Please rely solely on them.

Clients Dashboard

As a client, it’s possible to let others access your Salt Edge API dashboard. For this, you first have to create those users, so they, in their turn, can access the information provided by the interface.

In the creation form, you will see a field, describing user’s roles. The roles and their meanings are as follows:

  • Access connections(logins) - see the connections(logins) list;
  • Manage connections(logins) - refresh/reconnect/delete a connection(login);
  • Access customers - see customers list;
  • Manage customers - delete a customer;
  • Access invoices - see invoices list;
  • Manage invoices - pay an invoice;
  • Access company info - see client profile data, address;
  • Manage company info - update client profile data, address;
  • Access secret data - see client secrets, public key;
  • Manage secret data - generate new client secrets, update public key, destroy all data (being test|pending);
  • Access callbacks - see client’s callback URLs;
  • Manage callbacks - update client’s callback URLs;
  • Access teammates - see the team behind your client;
  • Manage teammates - add, edit and delete teammates;
  • Access providers stats - see each provider’s availability and last error;
  • Access accounts - see accounts list and details;
  • Access transactions - see transactions list and details;
  • Access all tickets - see and interact with support tickets created by all teammates (otherwise, only personal tickets can be accessed);
  • Access payments - see the list of Payments in the Dashboard;
  • Manage payments - manage Payments;
  • Generate reports - generate and download Activity Reports.

When a client is created, only the account holder can cancel client profile and destroy data.

Client Provider Keys

Account Information Services Support

Salt Edge now supports Account Information 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:

  • 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;

  • 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;

  • The rest of the process is exactly the same as with usual providers.

API Connect - Salt Edge Connect

In case of using API Connect 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 for a fake SMS code in addition to username and 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(login) create/reconnect or connect session create/reconnect.
All of the providers that are supported in this mode have _client_ in their provider code.
In case your Provider isn’t supported by our API, please fill this form and we’ll integrate it in due time.


eIDAS Certificates

Salt Edge API supports only soft issued eIDAS 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 eIDAS certificate in Salt Edge system, you should accomplish the following steps:

  1. Go to client dashboard.

  2. In client dashboard go to Account > eIDAS Certifcates

  3. Choose certificate type you want to create (QWAC or QSEAL) and press Generate CSR.

  4. Fill the form and click generate. Download generated CSR. (Private key that will be generated on this step is kept securely, so no one has access to it).

  5. Send CSR to QTSP (you can get test certificate, or buy production certificate)

  6. Get certificate from QTSP

  7. Go to Account > eIDAS Certifcates and press edit on previously created record.

  8. Insert received certificate in PEM format into form and press update.

  9. Choose certificate that you want to use for identification, press edit and mark it as active.

Your Account

While using Salt Edge API, your application can have one of the several statuses, each with its limitations.

Pending

Upon registration, your application has the Pending status. You can only access the fake providers (Account Information | Payment Initiation), and use up to 10 fake connections(logins). When you perform an action that is not permitted for pending clients, we respond with a ClientPending error.

When your app is not in Live status, you can also destroy data, which lets you destroy all the customers with their corresponding connections(logins), accounts and transactions.

In order to upgrade the status from Pending, you have to:

We will examine your application and upgrade it to the Test status in two business days.

Test

In order to retrieve real bank account data through Salt Edge API, please access the request test access page and fill in the form. When done, press the “Request Test Access” button.

In the Test status, your app can already use real providers, but it’s still limited to 100 connections(logins).

When you are ready to transfer to a limitless usage, use the instructions from the Live section below. Note that all of the data will be preserved, but you can also destroy it if you wish to start with a clean slate.

In order to become Live, the client application should use HTTPS for all API callbacks.

Live

a. Test the API integration to ensure that everything works properly with both fake and real providers. Contact us at any time with the feedback.

b. Get in touch with our sales team to sign the NDA and Service Agreement.

c. We will need to evaluate the integration of Salt Edge API on your side for all the platforms the Salt Edge service will be available on (e.g. web, Android, iOS, etc.). We suggest referring to the Before going Live guide and the Development Requirements and Guidelines. We recommend submitting the implementation for review at least 7 days before the planned production release date.

d. When you are compliant from both legal and technical perspectives you’ll be able to request the Live Access.

e. Review and add any missing teammates (e.g. finance team for invoicing purposes, support team to access the dashboard, etc.).

The Live status allows the application to use Salt Edge API without any restrictions.

In Live status, you will not be able to see all of your accounts’ and transactions’ details in your dashboard.

Restricted

Your application will have the Restricted status if the payment hasn’t been received. While in this status, your application is in a read-only state, hence it cannot create or reconnect connections(logins), refresh them, or create new connect_sessions.

Disabled

In case of any non-compliance with Terms of Service or Before going LIVE guide, we will contact you to solve the issues. When several attempts to contact the client fail or if any of the non-compliances are not fixed within two days time, the application will be transferred to the Disabled status. In this status, all API requests will return a ClientDisabled error.

Salt Edge API Access Terms

Data Volume Fetching Limits

Salt Edge API was developed to provide real time access to End Users’ financial or other data available from the End User’s Financial Institution. Access to the Salt Edge API is subject to the following data fetching limits:

  • up to two (2) fetches of new data from any Financial Institution per second (7,200 per hour);
  • limited to one (1) fetch of new data from any Financial Institution per day per End User;
  • if there is a failure to fetch or retrieve new data from a Financial Institution, Client is allowed to make up to two (2) additional attempts to retry fetching new data for the associated End User per day. Retried fetches are subject to the same limitations on fetching calls per second set forth in the first paragraph;
  • Salt Edge gives Client the option to enable automatic fetching of new data per each End User’s connection to a Financial Institution. Salt Edge’s standard automatic fetching time starts at 2AM and ends at 6AM in local time of the capital of the country where the Financial Institution is located. In certain cases, the automatic fetching time is from 2AM to 6AM UTC.

Data Volume Limits

This Section applies to Client if Client is using the Saltedge Categorization API separately. The Saltedge Categorization API was developed to provide real time categorization of Transaction Data. Accessing the Saltedge Categorization API is subject to the following limits:

  • categorization request to the Saltedge Categorization API must not exceed one hundred (100) Objects;
  • up to two (2) requests of categorization of Transaction Data per second (7,200 per hour).

To learn more about Terms of Service using Salt Edge API, go here.

Mobile SDKs

Salt Edge supplies a set of SDKs that can be used to build mobile and desktop apps. Right now we have the following libraries:

Note that this guide uses Salt Edge Connect as the interface for the users to connect to their bank accounts. If you’d like to use the REST API to connect, you can consult the full Reference or the documentation of the corresponding SDK.

1. Sign up for Salt Edge

Go to the Sign up page and sign up for a Salt Edge account. You will need to give your app a name, provide us with an email and a password you will use to authenticate to the admin page.

2. Follow the instructions supplied with the SDK

Each of the SDKs provides a description of how to set up the SDK, integrate it, and start fetching the customer data. Please refer to the corresponding README files.

The SDK also provides a sample app and the instructions as how to run the app.

FAQ

How often shall I sync all my data with Salt Edge ?

Salt Edge regularly updates all the data in the system, that is why we recommend synchronizing your data with the data Salt Edge provides you.

Our data is being updated on the following basis:

  • countries - rarely, maximum once per day;
  • currencies - rarely, maximum once per day;
  • currency rates - everyday, at 12:00 UTC;
  • categories - updated only on a new API version release;
  • providers and provider fields - new providers are added frequently, but the providers or their fields are updated rarely (around 10 changes per month, mostly on bank interface update). We recommend updating the providers and their fields once a day.

What is your pricing policy ?

Salt Edge takes a personalized approach to each and every client. To get a quote, please contact our Sales team.

How does connection(login) refresh work?

Automatic data refresh works for every connection(login), except the ones that satisfy any of these conditions:

  • If there was an error introducing your client’s credentials to connection(login) (InvalidCredentials) - in this case the connection(login) will be set as inactive (due to the old credentials being wrong);
  • If less time time than shown in provider.refresh_timeout (usually 1 hour) passed between the updates;
  • If the connection(login) credentials have not been saved (store_credentials flag is set to false);
  • If the provider.mode field is set to file.

Are the connections(logins) automatically refreshed?

Salt Edge regularly updates all the connections(logins) that satisfy the following conditions:

  • Connection’s(login’s) daily_refresh attribute has the true value;
  • The connection’s(login’s) status is set to active;
  • Connection’s(login’s) provider_mode is set to any value except file;
  • The automatic_fetch attribute of the last attempt has the true value;
  • The last stage of the attempt has the name of finish.

If these conditions are met, the connection(login) will be updated according to the time specified in refresh start time in the local time of the country the connection(login) belongs to.

I encountered “ActionNotAllowed” error. What should I do?

By default, all Salt Edge API clients can use Salt Edge Connect for quick and easy API integration into their app or service. API Connect allows the clients to perform connection(login) actions directly via the API. Access to these routes requires the client to adhere to high security standards, as it involves handling of sensitive customer information. Access to the API Connect routes is subject to manual review and activation and is granted to the ISO 27001 certified parties, registered AISPs and PISPs, as well as selected companies adhering to leading industry security requirements.

Who owns the financial institutions logos appearing in the Salt Edge API?

Salt Edge does not own the marks, brands and/or logos of the various financial institutions (banks, e-wallets, payment system providers) that appear in the Salt Edge API. We only display them for Salt Edge clients’ convenience and ease of use. Such marks, brands and/or logos are the property of their respective owners and are used for identification purposes only. Their display in the Salt Edge API is not sponsored by the respective owners, and does not imply any product or service endorsement by, or affiliation with, Salt Edge. The use of these marks, brands and logos is at Salt Edge clients’ own risk, who are solely responsible for obtaining any applicable permission or authorization from the respective owners. Salt Edge does not make any representation or warranty, express or implied, with respect to such marks, brands and/or logos and expressly disclaims any responsibility or liability arising therefrom.