general

Overview

Salt Edge Partners API aims to provide access to financial information for any company that does not need to get a PSD2 Account Information Service Provider license, as simple as a cURL.

• Import financial information from UK and EU banks via PSD2 APIs (Open Banking Standard, NextGenPSD2 Berlin Group, CBI Globe, Polish API, etc.)
• Securely import financial information from online banking interfaces of multiple countries;
• Automatically synchronize accounts and transactions on a daily basis;
• Automatically enrich financial transactions by categorization and merchant identification;
• Keep a well-organized and up-to-date list of currency rates.

If you have any questions regarding what can be done with Salt Edge Partners API, feel free to contact us.

If you have any questions regarding your company’s eligibility for using the Partners API, please contact our Sales team.

Integrations

The Salt Edge platform is easy to integrate. However, if you think that 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 providers are located;
• Provider - a bank or an online payments system;
• Lead - a verified end-user email associated with Salt Edge Limited customer record;
• Partner Consent - a permission given to Salt Edge Limited to share fetched data with registered partner;
• Customer - a customer of the client who is consuming Salt Edge Partners API;
• Connection - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
• Consent - the permission from an end-user to fetch data;
• Attempt - an attempt which is created when an end-user connects a financial institution;
• 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;
• Transaction - a single financial movement made within an account;
• Merchant - a company that sells goods or provides services to the customer;
• 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

This quick start guide will show the easiest path of integrating with Partners API: creating a lead, granting consent, authenticating in the bank interface, fetching financial data on success.

Get invitation

Request an invitation through contact us or our sales team.

Create an account

a. Get an invitation to visit the Sign Up page, then generate a secure password to confirm partner account creation.

b. 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 Salt Edge Partners API is authenticated, so before you are able to fetch any data you need to create Service API keys. To do that, visit https://www.saltedge.com/clients/api_keys and create a Service API key. You can leave Public key field blank as when you will go LIVE, signing the requests will become mandatory.

Salt Edge Partners API is supporting only Service API keys use. All communication should be done from a centralized Web Service to grant control over the data flows, security and privacy.

Each request to Partners 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. Start testing different connection types by using Fake and Sandbox providers to make sure that the application can handle any scenario that might happen with a real data provider (e.g. bank or standard).

Create lead

Before we can create any connections using Salt Edge Partners API, we need to create a Lead. A Lead in Salt Edge Partners API is the verified end-user email of your application.

The result of this request will be a Customer id and Email.

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 lead reference and customers reference for related API endpoints.

Create lead session

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

To initiate a connection you need to execute a request to create lead session endpoint.

You will receive in response a redirect_url. This is the URL your end-user will visit to create the connection.

See Lead sessions reference for more information and related API endpoints.

Visit Connect Widget URL

Initially, all Salt Edge registered partners are in pending status and only have access to fake and sandbox providers. Let’s connect one of them. Visit the redirect_url from the previous API response and search for “Fake Bank Simple”.

Iframe embedding is not allowed in a webview. The Salt Edge Connect (widget) should be opened in a new browser window or in a pop-up window.

Once selected, we will be presented with a form for end-user credential input, from this provider. Input “username” and “secret” as per the on-screen instructions and press “Connect”.

Afterward, we will have to wait for the connection process to finish so that we can proceed with retrieving all its data via the API.

Fetch connections

In Salt Edge Partners API, a distinct bank connection is called a Connection. Each Salt Edge Partners API Customer can have multiple Connections. When we visited Redirect URL and connected “Fake Bank Simple”, we created a Connection associated with our Customer in the system. 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.

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 transactions for the account.

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.
• Since new Salt Edge partners are in pending mode and have access only to fake and sandbox 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 Salt Edge Partners 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.

- Iframe embedding is not allowed in a webview. The Salt Edge Connect (widget) should be opened in a new browser window or in a pop-up window.
- Salt Edge Connect (widget) supports only the 2 last versions of modern browsers.

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

Salt Edge Partners API requires APP_ID and SECRET headers in order to authenticate as partner. 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 Salt Edge API will be authenticated using your API key.

Before going LIVE

In order to upgrade your Partner account status to LIVE mode, the following steps should be followed:

• Provide your Account Manager at Salt Edge with a test account in your app to verify Partners 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 the signature in accordance with the instructions.
• Your application should handle correctly a few fake banks (fake_oauth_client_xf, fake_client_xf are mandatory) and at least one Sandbox (to your discretion).
• The partner consent should be revoked when the connection is deleted from the app.
• The lead should be able to refresh and reconnect (mandatory for recurring access) an existing connection to a financial provider.
• The Two-factor authentication must be enabled for your account and all your teammates;
• In order to avoid legal issues with end-users and data providers, the client must ensure that end-users read and agree to End-user Dashboard Terms of Service and End-user Dashboard Privacy Policy, both as incorporated by reference into Partner’s own Terms of Service and Privacy Policy.
• Be sure to indicate Incident reporting Email in the dashboard settings on the Company page.

After your Account Manager at Salt Edge has reviewed the app’s integration with Partners API, the account’s status will be upgraded to live. The review usually takes two business days if no issues are detected.

Callbacks

The most important parts of Salt Edge Partners 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. Applications can also poll Salt Edge Partners 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 Salt Edge Partners 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 port 80/HTTP only in test and pending modes.
Port 443/HTTPS is accepted by all modes.
Also, the callbacks do not follow redirects!

Signature

Signature

In order for the client to identify that the request is coming from Salt Edge Partners API, there is a Signature header in the request.

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 Salt Edge Partners 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-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"))

Success

We send a callback to your application’s success URL whenever any triggered operation has caused a change in the data we store for a particular connection.

For instance, the user was redirected to the Connect page, selected a provider, filled in the credentials and pressed Proceed, we’ll 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 fetch the full connection data, along with the accounts and transactions at each callback, as some information might change during the fetching process.

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

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "finish"
  },
  "meta": {
    "version": "5",
    "time": "2024-04-17T11:13:47.809Z"
  }
}

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 end-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:47.813Z"
  }
}

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

You can also receive a fail callback if the lead revokes the partner’s consent of the connection:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "error_class": "PartnerConsentRevoked",
    "error_message": "The partner consent was revoked by the end-user"
  },
  "meta": {
    "version": "5",
    "time": "2024-04-17T11:13:47.813Z"
  }
}

Additional callbacks

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

Notify

Salt Edge can inform you about the progress of a connection using Notify callback.

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 user about what’s happening with the 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 connections, 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": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "start"
  },
  "meta": {
    "version": "5",
    "time": "2024-04-16T11:13:47Z"
  }
}

Destroy

Whenever a connection gets removed, we will send a callback to your application’s destroy URL, if such exists.

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

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222"
  },
  "meta": {
    "version": "5",
    "time": "2020-05-17T14:29:35Z"
  }
}

Service

If the connection had issues in the past and a change was made in connection’s provider codebase, your application will receive a callback informing you that a refresh is needed in order to update the 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:47Z"
  }
}

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;

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.

Holder info route 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 connection information, e.g. accounts and transactions.

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

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 means that either the user has not finished the authorization on the bank’s end or has not returned from the bank’s end to us, for an unknown reason. 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 bank for assistance and clarifications.

In order for Salt Edge to be able to handle such cases, while reporting them to us, please provide the following details on what happened during authorization on the bank’s end:

1. When the user was redirected to the bank’s page, how did that page open? In the same window or in a new window? Here a screenshot (all the sensitive data to be hidden) or a screen recording would help.
2. Overall, did the authorization complete successfully on the bank’s end? If not, during which authorization step did the process end?
   
3. Afterwards, was the user redirected back to the application, or did the user close the window themselves?
4. Also, did the user notice any unexpected behavior while connecting? (a blank screen, a specific error mentioned on the page, etc.)
   
5. If the authorization completed successfully on the bank’s end, please ask the user to describe how the error has occurred.
   

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

Partner 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 Salt Edge Partners 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.

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.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• DateOutOfRange
• ValueOutOfRange

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_with_dynamic_select_xf - allows to test the dynamic_select credentials field;
• fakebank_image_xf - the user needs to solve a CAPTCHA for authentication;
• fakebank_inactive_xf - reproduces the ProviderInactive error;
• fakebank_interactive_xf - asks for a fake SMS code;
• fake_delayed_oauth_client_xf - will delay the payment initiation by a few seconds;
• fake_client_xf - requires a username and password (embedded);
• fake_oauth_client_xf - asks for authorization (OAuth redirect);
• fake_interactive_client_xf - asks to enter a fake captcha code in addition to a username and a password (embedded);
• fake_interactive_decoupled_client_xf - decoupled interactive flow (e.g. push notification), asks to wait 10 seconds in Connect widget and then click Proceed to continue in addition to a username and a password (embedded).
• fakebank_two_step_interactive_xf - asks for interactive data twice during the fetching process;
• fakebank_semi_interactive_xf - occasionally requires an SMS code;
• fake_oauth_interactive_client_xf - has an interactive redirect during the attempt besides the first authorize redirect;
• fake_oauth_interactive_no_callback_client_xf - allows testing scenario for additional redirect during the SCA process;
• fakebank_with_optional_fields_xf - similar 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;
• fake_with_partial_data_xf - has a dropdown list with some options for the user to choose from. Allows to test 3 different scenarios of partial data: incomplete accounts data, incomplete transactions data, and an error;
• fakebank_oauth_with_pending_xf - similar 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;
• fake_business_demobank_xf - simulates the flow of a non-regulated API provider;
• fakebank_with_token_xf - requires a username and a fake token;
• fake_with_dynamic_registration_oauth_client_xf - linked to a fake dynamic registration. Once the dynamic registration is executed, the provider keys will be added automatically;
• fakebank_oauth_with_pending_and_available_balance_xf - similar 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;
• fake_oauth_eidas_client_xf - will raise an error if QWAC or QSeal certificates are not configured correctly in the client’s account;
• fakebank_with_crypto_assets_xf - simulates the flow of a crypto provider;
• fakebank_with_natures_xf - allows testing all the possible supported_account_natures;
• fakebank_with_file_csv_xf - extracts transactions from a csv file. You can download the sample here; Note: Testing this provider allows the client to test categorization and merchant identification for a desired country. For that, it is required to configure the Country and Account Currency fields accordingly;
• fake_with_error_client_xf - allows testing multiple errors.

The Fake Bank with Error (fake_with_error_client_xf) allows selecting the error you would like to test. The choices are as follows:

• Invalid SCA redirect URL - no error. The user will be redirected to an invalid URL. As a result, the connection will fail with ProviderAccessNotGranted because the PSU (user) couldn’t complete the authorization step.
• Token Expired - Error class: InvalidCredentials. Error message: Invalid token.
• Consent Invalid- Error class: InvalidCredentials. Error message: Consent is not valid.
• Access declined - Error class: InvalidCredentials. Error message: Access declined. Please contact your bank’s customer service.
• Too many requests - Error class: ProviderUnavailable. Error message: Too many requests.
• ExecutionTimeout- Error class: ExecutionTimeout. Error message: ExecutionTimeout error.
• InteractiveAdapterTimeout - Error class: InteractiveAdapterTimeout. Error message: Interactive timeout.
• InvalidInteractiveCredentials - Error class: InvalidInteractiveCredentials. Error message: Interactive action failed.
• AccountValidationError - Error class: AccountValidationError. Error message: ‘Simple account 2’ already exists in account list.
• Payment failed with delay - The payment will fail after 20 to 25 second from the moment of initialization. Error class: PaymentFailed. Error message: Payment failed.

Fake OAuth Bank with Client Keys (fake_oauth_client_xf) allows selecting the successful scenario you would like to test. The choices are as follows:

• Grant access - The payment/attempt will be accepted.
• Accepted payment with delay - The payment will be accepted after 20 to 25 second from the moment of initialization.

The ProviderNotFound error may be reproduced by trying any inexistent and invalid provider_code.

Note: The appropriate credentials for a particular provider are mentioned under the Instructions field on its Connect page.

Sandbox

Sandbox is a live-testing environment of a regulated provider that allows Partners and Clients to test providers under Salt Edge’s supervision.

In order to help with testing regulated providers, Salt Edge offers the sandbox environment of each PSD2 bank. A sandbox is identified by the word Sandbox in the provider_name (eg. Lloyds Bank (Sandbox)) with a designated provider_code containing XF as country code (eg.lloyds_oauth_client_gb_xf).

Just as with the fake providers, sandbox providers can be tested if your application is in Test or Pending status. In the Connect page, we will let you select the fake country (having the country code XF), and its sandbox providers.

The authorization instructions are mentioned under the Instructions field on its Connect page.

Note: Some Sandboxes may not be available for an indefinite period of time due to the limited support sources of a provider.

Leads

The leads are the end-users (PSUs) that can create connections and share data with a partner.

Create

Allows to create or return an existing lead, thus bypassing the Sign Up stage which requires user input. The response contains the email of the lead and the associated customer_id which can be used for creating a lead session. It also allows to send Know Your Customer (KYC) information about the lead, both personal and/or legal information. If some of the KYC information is not sent via API, the lead may be asked about it during the payment session, depending on the partner configuration, as part of anti-money laundering check. If some of the KYC information is not known, the corresponding keys should not be sent.

Parameters

Possible Errors

• ActionNotAllowed
• ClientDisabled
• ClientNotFound
• ClientRestricted
• DateFormatInvalid
• JsonParseError
• WrongRequestFormat

Remove

Deletes partner association with a lead.

Once a lead is de-associated with a partner account, the lead will not be able to share the consent with the partner’s account again. The lead and the connections remain accessible from the End-user dashboard and can be shared with any other partner(s).

When it’s needed to allow a de-associated lead to share the connections with the partner again, then the partner should use leads create route. In this case, the original email used for the lead original creation should be sent as email parameter in the lead’s create request. Once it’s done, the lead will have the possibility to share the connection(s) with the partner again.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound

Lead session

Lead session is a temporary object that links the Connect session with a new connection object that will be created once the user grants consent to Salt Edge Partners API to fetch data.
If a lead for which a connection is to be created did not previously exist, an email will be sent to the lead with instructions on how to set a password to access the Salt Edge Dashboard account.

Create

Allows you to create a lead session.

Parameters

Possible Errors

• AispConsentScopesInvalid
• AispConsentScopesNotAllowed
• ClientDisabled
• ClientNotFound
• ClientRestricted
• ConnectionNotFound
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateOutOfAispConsentRange
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidAispConsentFromDate
• InvalidAispConsentPeriod
• InvalidFromDate
• InvalidToDate
• JsonParseError
• ProviderNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongProviderMode
• WrongRequestFormat

Reconnect

Allows you to create a lead session to reconnect an existing connection.

Reconnect requires a new consent to be given. The consent confirmation in this case can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer has to agree should be sent).

Reconnect will prompt a new partner consent to be given and is only possible if the connection was previously shared with you.

Parameters

Possible Errors

• AispConsentScopesInvalid
• AispConsentScopesNotAllowed
• ClientDisabled
• ClientNotFound
• ClientRestricted
• ConnectionNotFound
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateOutOfAispConsentRange
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidAispConsentFromDate
• InvalidAispConsentPeriod
• InvalidFromDate
• InvalidToDate
• JsonParseError
• ProviderNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongProviderMode
• WrongRequestFormat

Refresh

Allows you to create a lead session to refresh an existing connection.

Refresh does not require a new consent, it is based on the limitations of the current active consent. If the latest consent has been revoked, only a reconnect is possible.

Parameters

Possible Errors

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

Partner consents

Partner consent is a part of the combined consent shown to the customer that allows Salt Edge to share account, transaction and holder info data with the registered partner, based on the right to data portability enforced by the EU General Data Protection Regulation (GDPR).

Attributes

List

Returns all the partner consents accessible to your application for a certain customer. The partner consents are sorted in ascending order of their id, so the latest partner consents will come last. You can read more about next_id field, in the pagination section of the reference.

Parameters

Possible Errors

• ClientDisabled
• ClientNotFound
• ConnectionNotFound
• CustomerNotFound

Show

Returns the partner consent object.

Parameters