general

Overview

Spectre 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 (Payoneer, 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 what can be done with Spectre 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 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:

• Client - an application consuming Spectre API;
• Customer - a customer of the client who is consuming Spectre API;
• Provider - a bank or an online payments system;
• Login - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
• Attempt - an attempt which is created when user connects his financial institution;
• Account - one of the accounts associated with a login. It can be a credit card account, a savings account, one of the online accounts, etc;
• Transaction - a single financial transaction made within an account;
• Category - one of the 79 categories assigned to a transaction.

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.

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:

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/revers engineered, hence the are security constraints in place to mitigate this

Customer secret

In order to create tokens, logins 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.

Login secret

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

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 Spectre 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/keys_and_secrets and create a “Service” API key. You can leave “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 Spectre API, we need to create a Customer. A Customer in Spectre API is the end-user of your application.

We need to save the Customer id (in this case “111”), because we will use it later to create connections.

$ export CUSTOMER_ID=111

See customers reference for Customer related API endpoints.

Create connect token

Once we have the Customer id (in this case id “111”), we can create a connection.

There are 2 ways to create connections in Spectre 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 token endpoint.

We will receive in response a connect_url. This is the url we will visit to create the connection.

See tokens reference for more information and API endpoints related to Salt Edge Connect.

Visit connect url

Initially, all Spectre 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, we 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 “Connect”.

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 logins

In Spectre API, a distinct bank connection is called a Login. Each Spectre Customer can have multiple Logins. When we visited Salt Edge Connect and connected “Fake Bank Simple” we effectively created a Login for our Customer in the system. So to retrieve all data for this Login we first need to retrieve the Login 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 1227) to retrieve its accounts.

$ export LOGIN_ID=1227

See logins reference for more information on Login endpoints.

Fetch accounts for logins

Having the Login 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 142) to retrieve all transactions for this account.

$ export ACCOUNT_ID=142

Fetch transactions for an account

Having 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 Spectre 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 syncronizing data with Spectre 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.

Changelog

This page differs depending on which API version you are browsing at the moment.

Authentication

• Client-id and Service-secret headers are no longer supported. In V4, each Client is able to create an unlimited amount of API keys for API use. You can manage your keys on the Keys and Secrets page.

• Each request will now have consistent auth headers: App-id + Secret for both Apps and Services (ex: logins#create).

Removed

• client#info route;
• categorize flag/field from Attempt object and from logins#create. Instead, the new categorization flag was added to the same route. Possible values: none, personal, business, default: personal.

Changed

• All IDs are returned as strings in API responses and HTTP callbacks;
• Categories objects from /api/v4/categories now include business and personal categories list;
• md5 digest from imported file hash was changed to sha256;
• sha1 digest from request signature was changed to sha256;
• sha1 digest from callback signature was changed to sha256;
• fetch_type was replaced by fetch_scopes, required on login/token create and is optional on login/token reconnect or refresh;
• Consent window is now shown by default, unless show_consent_confirmation is false. In other cases, it will be shown only when fetch_scopes has changed;
• Consents can now have an expiration date. It can be set by passing the consent duration in the consent_period_days flag.

Added

• identification_mode - provider attribute that shows whether the requests to the provider are made with your authorization headers or with Salt Edge’s;
• Support for merchant identification;
• identify_merchant - flag that shows if merchant identification is enabled for a login;
• Support for encrypted_credentials that can be sent on logins#create, logins#reconnect and logins#interactive;
• consent_period_days - flag that allows limiting the time the consent is valid;
• override_credentials and override_credentials_strategy flags that allow overriding previous credentials when reconnecting a Login via an API request or Token respectively;
• New callbacks header - Signature-key-version which holds the version of the private key used to sign the callback. You can find the public_key that corresponds to this version here;
• transactions#remove that allows transaction removal older than a specified period.

• New currencies:

  • ERN - Eritrean nakfa (232)
  • ITL - Italian lira (380)
  • ECS - Ecuadorian sucre (218)
  • DEM - German mark (276)
  • KYD - Cayman Islands dollar (136)
  • CYP - Cypriot pound (196)
  • FRF - French franc (250)
  • SIT - Slovenian tolar (705)

• number and dynamic_select natures to provider fields;

• immediate flag added to categories#learn route.

• Provider logos (see logo_url in provider attributes)

New errors

• ApiKeyNotFound - the API key with the provided App-id and Secret does not exist or is inactive;
• AppIdNotProvided - missing App-id from headers;
• FetchScopesInvalid - client sent invalid values. Ex: fetch_scopes: [accounts];
• FetchScopesNotAllowed - client sent not supported values. Ex: he has access only to holder_info (Credit bureau for ex.) but sent fetch_scopes: [accounts].

Upgrade guide

This guide explains the changes you will have to keep in mind when upgrading from v3 to v4 of Spectre API. Follow these steps:

• Visit Keys and Secrets page of your Client Dashboard and create a new API key with “service” key type;
• Change the routes that are polled in your system from v3 to v4;
• Replace Client-id and App-secret headers in all your requests with App-id and Secret headers corresponding to the key created in step 1;
• Make sure you use the right public_key to verify the authenticity of the received callbacks.

Before going LIVE

In order to have the Salt Edge accounts transferred to LIVE mode the following steps should be followed:

• Please provide Salt Edge representative with app’s test account to verify Spectre API integration;
• 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;
• Your application should be working correctly with all of the fake banks;
• Your application should not create any duplicated customers (i.e. connecting the same provider with the same credentials, for the same user, using different customer entities);
• The end user should be able to create, reconnect, refresh and delete logins;
• After deleting a user from your system, you should send a delete request;
• Your application should handle correctly the refresh_timeout in provider entity;
• Your application should handle correctly the LoginDuplicated error;
• Your application should show the instructions for providers;
• Your application should not allow usage of disabled providers;
• Your application should use the duplicate route for a better user experience;
• The Multi-factor authentication must be enabled for your account and all your Client users;
• In order to avoid legal issues with end-users and data providers, the client should ensure that end-users read and agree to End User License Terms.
• Be sure to indicate Incident Reporting Email in the dashboard settings;

After all of the verifications have been made by a Salt Edge representative, the account will be transferred to LIVE mode.

Know Your Customer

Account holder info

This feature allows the client 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 support team to enable holder info for your client account.

Upon enabling the feature you will receive a holder_info field inside provider object. This field will provide information on the account holder details that can be fetched from the queried provider.

Login attribute holder_info returns the information fetched from 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 login information, e.g. accounts and transactions.

In order to test the holder_info attribute, you can connect the fakebank_simple_xf fake provider.

Encrypted credentials

Any endpoint that accept or require a “credentials” object (like Creating logins), 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.

Try Spectre API 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

Spectre 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 you 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 Spectre API will be authenticated using your API key.

Salt Edge Connect

You can easily test Connect from your Dashboard page by pressing Create Connection button.

After your application has received a token for connecting or reconnecting a login, 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 their credentials and, if needed, any of the interactive credentials.

For example, a user picked Italy as the country and the American Express as the provider. This is what they will see:

To start the fetching process, they will have to press “Connect”. Afterwards, they will be informed about their connection progress.

After the fetching is done, the user will be redirected back to your application.

Embeding connect in your appication

When you request for a connect token, 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;
• external object, calling window.external.SaltBridge;
• external object, calling window.external.Notify;
• postMessage, calling window.addEventListener(“message”….

Salt Edge Connect will send any of these callbacks only in case when javascript_callback_type was specified in the token 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":{"login_id":"997674448","stage":"fetching","secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM", "custom_fields":{"key":"value"}}}

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 login callback:

saltbridge://connect/{"data":{"duplicated_login_id":"994317674","stage":"error","custom_fields":{"key":"value"}}}

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 a 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 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:

• Standart callback
• Duplicated login callback

Possible stage values for each callback type are fetching, success and error.

Fetching

{
  "data": {
    "login_id": "997674448",
    "stage": "fetching",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "fetching",
    "custom_fields": {
      "key": "value"
    }
  }
}

Success

For instance, when your user has created a login using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "login_id": "997674448",
    "stage": "success",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "success",
    "custom_fields": {
      "key": "value"
    }
  }
}

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": {
    "login_id": "997674448",
    "stage": "error",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "error",
    "custom_fields": {
      "key": "value"
    }
  }
}

API Connect

If you do not wish to connect logins using Salt Edge Connect, you can perform all the login actions using our API.

In order to connect a new login, you should use the logins create route described in the API reference. After connecting the login, your application will receive the corresponding callbacks so you can fetch your newly created login.

If the login you wish to connect is an interactive one, you will receive the 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.

Refreshing data

If the login had an error while connecting, and it had an InvalidCredentials error during the fetching process, you should reconnect the login and send the correct credentials in your request body.

When the login is connected correctly, and you received all the accounts and transactions details, you can refresh the login anytime, and keep the login data up-to-date.

Note

API Connect requires high security standards for data handling on client’s side. This integration method is only available for the certified and/or selected partners. For more information, feel free to contact us.

Callbacks

The most important parts of Spectre API (e.g. Login management) are asynchronous. Applications can poll Spectre API in order to retrieve the updated information.

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 Spectre 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 Spectre 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 not follow redirects!

Request Identification

In order for the client to identify that the request is coming from Spectre API, there are two options:

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 Spectre 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 4.0 which corresponds to the following public key:

  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzi1XL1b0XwUYVHj7/AR6
  Hr0YN34wH/bDOIub0nwt0s/s3tD+DPxNB85xpMEZrLikPW5PAKkQ/oC3OyPYxKOb
  8TNhzGmQhEfyCkbdRwxNZqRMRwuOc+N4sdBtQKPN8+XF3RIcRZAk25JGROtb1M2o
  d/Nb9QqdQwMjdk6W+Vdq5Sj25Tj2efJc8zmBJkNXR4WtW45p4XSdjSEjuVCSZjOy
  +N8/Od8MGixC99jYbiKm3RrVDJCgDi4YYnNRI0QgxZRpJKbQX/WeZiYOrbctG3m8
  l1/Hpkv3w1QHz/YFIshCOKwUL+xg1hLMaW4IH7XFHenE+JlUKdCqhcWyi7oIDkyr
  7wIDAQAB
  -----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":{"login_id":"1234","customer_id":"4321","custom_fields":{}},"meta":{"version":"4","time":"2017-01-03T13: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 Spectre API you can use Client Certifcate Authentication.

Instructions

1. Go to Account -> Callbacks and press Mutual TLS Settings

2. Press Generate CSR.

3. Set Certificate attributes if needed and press Generate.

4. Download CSR.

5. 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
   

6. Upload generated certificate via following form.

To see how it could be implemented on 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 login.

For instance, after you’ve redirected your user to the Connect page and they have selected their provider, filled in the credentials and pressed Connect, we’ll send you a success callback. This callback will contain the customer identifier and the ID of the newly created login. Afterwards, your application will be able to use the show login route and query the information about this login. You could also fetch the login’s accounts and query the accounts (if any exist at the moment we sent the callback).

Whenever we have more information about the login, 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 login 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 login using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2020-10-26T16:53:58.879Z"
  }
}

You can now use the show login route and obtain the provider, country and some other attributes of the new login.

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": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "error_class": "InvalidCredentials",
    "error_message": "Invalid credentials."
  },
  "meta": {
    "version": "4",
    "time": "2020-10-26T16:53:58.890Z"
  }
}

After you get this callback, you need to request the login to check for its updates. Please note that even if there’s an error, we still store the login.

If you would like to delete the erroneous login, you can use the remove login route. In case of an InvalidCredentials error, we recommend you to use a Reconnect.

In order to avoid login duplication errors on new login creation, when you read the login after a fail callback, we recommend you remove the login in case of last_fail_error_class is equal to InvalidCredentials and the login has zero linked accounts.

Additional callbacks

There are three additional callbacks that your app needs to implement in order to use the API-only version of Spectre.

Notify

Since you issue a create request to create a Login, Salt Edge can inform you about the progress the new login is going through using a Notify callback.

Your app can expect the notify callback several times, depending on the type of the login, but you can use this information to inform your user 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.

Note that for some of the logins, you might not receive all the stages.

Notify callback will not be triggered for daily attempts.

Here’s an example callback sent to the /notify route of your app:

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "start"
  },
  "meta": {
    "version": "4",
    "time": "2020-10-25T16:53:58Z"
  }
}

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 login 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 user 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 login’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": {
    "login_id": "123",
    "customer_id": "34445",
    "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": "2020-10-25T17:53:58Z",
    "interactive_fields_names": ["image"]
  },
  "meta": {
    "version": "4",
    "time": "2020-10-25T16:53:58Z"
  }
}

In case of a dynamic_select field (sent only for Providers in AISP flow), the callback will also include interactive_fields_options, which you need to present to the user:

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "interactive",
    "html": "<p>Please select accounts from the list:</p>",
    "session_expires_at": "2018-04-18T11: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": "4",
    "time": "2018-04-18T10:27:10Z"
  }
}

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 case we expect to receive only 1 selected option value as a String.

When 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 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": {
    "login_id":                 "123",
    "customer_id":              "34445",
    "html":                     "",
    "redirect_url":             "https://bank.com/authorize"
    "stage":                    "interactive",
    "session_expires_at":       "2020-10-25T17:53:58Z",
    "interactive_fields_names": [],
    "custom_fields":            { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time":    "2020-10-25T16:53:58Z"
  }
}

Your application should redirect the user to redirect_url field value of the interactive callback payload. Once the end-user will be authorized on the provider’s side, they will be redirected to the return_to URL indicated in the create login 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=123"
    }
  }
}

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 login gets removed, we will send a callback to your application’s destroy URL, if such exists.

Here’s an example callback sent to your app’s /destroy route:

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2013-05-17T14:29:35Z"
  }
}

Service

Whenever the login had issues in the past and a change was made in login’s provider codebase, your application will receive a callback telling that a refresh is needed in order to update login’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": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "reason": "updated"
  },
  "meta": {
    "version": "4",
    "time": "2020-10-25T16:53:58Z"
  }
}

Merchant Identification

Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.

This option is country based and currently is available in 17 countries - UK, Ireland, Italy, Netherlands, Germany, Czech Republic, Austria, Hungary, Poland, Romania, Latvia, Spain, Portugal, Australia, Russia, India, Singapore and the list will continue to grow.

Also, you can test it, using the fakebank_simple_xf provider, available for the fake XF country.

How to use

To start using this option, all you need to do is:

• pass identify_merchant: true on logins #create, #refresh, #reconnect or tokens #create, #refresh, #reconnect. When the login creation succeeds and only if the merchant is identified, you will receive a merchant_id in the extra field of the transaction;
• send all the merchant_ids you want to fetch the additional info for, to merchants.

Errors

The API can return multiple errors for any operation, each having its meaning and usage.

Error attributes

List

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 Spectre API.

Parameters

Response

Possible Errors

• ClientDisabled
• ClientNotFound

Providers

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

Attributes

Show

Provider show allows you to inspect the 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.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• ProviderNotFound

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.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• DateOutOfRange
• ValueOutOfRange

Fields

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

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.

Note: The options for dynamic_select are not stored in the Provider, they are generated dynamically and sent in an Interactive callback.

Fake

In order to help 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.

The API supplies a number of fake providers:

• fakebank_simple_xf - requires a username and password;
• fakebank_select_xf - has a dropdown list with some options for the user to choose from;
• fakebank_image_xf - the user needs to solve a CAPTCHA for authentication;
• fakebank_interactive_xf - asks for a fake SMS code;
• fakebank_two_step_interactive_xf - asks for interactive data twice during the fetching process;
• fakebank_semi_interactive_xf - occasionally requires an SMS code;
• fakebank_with_optional_fields_xf - similar to fakebank_interactive_xf, but with some of the interactive fields marked as optional;
• fakebank_api_with_fields_xf - similar to fakebank_simple_xf, used for ensuring API providers availability;
• fakebank_oauth_xf - asks for authorization;
• fakebank_oauth_with_pending_xf - similar to fakebank_oauth_xf, returns pending transactions;
• fakebank_oauth_with_n_transactions_xf - similar to fakebank_oauth_xf, returns more than 1000 transactions;
• fakebank_with_updates_xf - generates up to 4 transactions on every connect, refresh, reconnect with random amounts and modes;
• fake_demobank_xf - generates multiple accounts with different currencies, and different account natures;
• fakebank_with_token_xf - requires a username and a fake token;
• fakebank_with_error_xf - allows you to test the appearing errors when connecting a new provider;
• fakebank_oauth_with_pending_and_available_balance_xf - similar to fakebank_oauth_with_pending_xf, having accounts, which have different values for balance and available_balance;
• fakebank_with_possible_duplicates_xf - each attempt generates a transactions with same made_on, amount, currency_code but different description. On second attempt and later it marks those transaction with extra[:possible_duplicate] flag;
• fakebank_with_rememberable_credentials_xf - remembers all the answers to secret questions and doesn’t ask them in the interactive stage if they were introduced correctly on previous attempts.
• fakebank_with_file_csv_xf - extracts transactions from a csv file. You can download the sample here.

The Fake Bank with Error allows to select which error you would like to test. The choices are as follows:

• No Erorrs - works the same as fakebank_simple_xf;
• No Errors with Partial Data - returns accounts and transactions, where partial flag is set to true;
• ExecutionTimeout - no accounts and transactions, raises the ExecutionTimeout error;
• FetchingTimeout - no accounts and transactions, raises the FetchingTimeout error;
• ProviderUnavailable - no accounts and transactions, raises the ProviderUnavailable error;
• ProviderError - no accounts and transactions, raises error with a generic message An error has occurred. Please report this error..

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 for a fake SMS code in addition to username and password (embedded).

Check the provider’s instructions in the Connect page for the appropriate credentials. You can use these providers in order to test the codes, the format of the transactions, errors, etc.

Customers

A customer represents a single end-user of the Spectre API. The customer uses the API to create Logins, 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:

You need to store the id returned from the response in your application, which is necessary when creating logins. We give you the following customer API actions so that the customer will be successfully identified within Salt Edge.

Create

Creates a customer, returning the customer object.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• DuplicatedCustomer
• JsonParseError
• WrongRequestFormat

Show

Returns the customer object.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound

List

List all of your app’s customers. This route is available only for web applications, not mobile ones.

Possible Errors

• ClientDisabled
• ClientNotFound

Remove

Deletes a customer, returning the customer object. This route is available only for web applications.

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Lock

Locks a customer and its data, returning the customer object.

All customer related data including logins, accounts, transactions, attempts will not be available for reading, updating or deleting even by Salt Edge. This route is available only for web applications.

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Unlock

Unlocks a customer and its data, returning the customer object. This route is available only for web applications.

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Tokens

We use tokens to identify clients who will use Salt Edge Connect. With a token, you will be able to let your users connect, reconnect or refresh a login. Note that the token will expire in 60 seconds if you do not access Salt Edge Connect. After the token has been used to redirect the user to Salt Edge Connect, the user will have 10 minutes to fill in the necessary data. Afterwards, the user’s session will expire.

Before acquiring a token, you should be sure that the user exists in the system, or you should create one.

If your status is Pending, you will receive a ClientPending error when connecting any login not from the fake providers.

You can read more about tokens in the Tokens guides page.

Create

Allows you to create a token, which will be used to access Salt Edge Connect for login creation. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• ClientRestricted
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ProviderNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongProviderMode
• WrongRequestFormat

Reconnect

Allows you to create a token, which will be used to access Salt Edge Connect to reconnect a login. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

Parameters

Possible Errors

• AllAccountsExcluded
• ClientDisabled
• ClientNotFound
• ClientRestricted
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

Refresh

Allows you to create a token, which will be used to access Salt Edge Connect to refresh a login. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

In some cases, refresh will automatically call reconnect:

• refresh is called before the value specified in next_refresh_possible_at;
• next_refresh_possible_at is null.

Parameters

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 request that exceeds this limit will return a BackgroundFetchLimitExceeded

Possible Errors

• AllAccountsExcluded
• BackgroundFetchLimitExceeded
• ClientDisabled
• ClientNotFound
• ClientRestricted
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

OAuth Providers

Spectre API also allows your app to import data from a list of OAuth-supporting providers. The OAuth workflow, in this case, is reduced to a couple of HTTP calls and redirects.

Connecting OAuth providers logins is done via the same mechanism as when connecting a usual login - using tokens for connecting, 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 user can provide Salt Edge access to their financial data, making it available for your app. After the user has approved Salt Edge in the OAuth provider’s interface, they will be redirected to the return_to page.

Create

Used to create a login for an OAuth provider. After receiving the response, the customer will be redirected to return_to URL.

Note that mobile clients receive a login_secret parameter in the return_to URL if the login was successfully connected and an error_message parameter. return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If clients use their own provider keys, return_to is required and should be a valid url that was registered within the provider they are connecting to.

Parameters