general

Overview

Salt Edge Partners Payment Initiation API aims to make payment initiation as simple as a cURL for any company that does not need to get a PSD2 Payment Initiation Service Provider license.

If you have any questions regarding how Salt Edge Partners Payment Initiation API works and how it can be used, 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;
• Customer - a customer of the client who is consuming Salt Edge Partners API;
• Lead - a verified end-user email associated with customer record;
• Payment - a payment that was made using Payment Initiation API;
• Payment template - a set of required and optional fields that need to be filled in order to successfully execute a payment;
• Payment field - an attribute of the payment template. Could be required or optional;

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 Payment Initiation API: creating a lead, initiating a payment, granting consent, authenticating in the bank interface.

Get invitation

Request an invitation through contact us or our sales team. In your request please mention which service is intended to be used: Partner Account Information, Partner Payment Initiation or both of them.

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 initiate any payment 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 payments.

$ export CUSTOMER_ID=222222222222222222

See lead reference and customers reference for related API endpoints.

Choose provider

In order to choose a provider that supports payments we need to execute a request.

The response will be a list of providers that support payments.

Each payment provider can support multiple ways of initiating a payment. Each of this method is called a payment template.

For instance, we can see from the response that provider fake_client_xf supports payment templates SEPA, FPS, and SWIFT.

Choose payment template

Since the provider fake_client_xf supports the following payment templates SEPA, FPS, and SWIFT, we can execute payments using only one of them.

For the purposes of this guide, let’s stick with SEPA. We need to save the payment template identifier (in this case SEPA), because we will use it later.

$ export PAYMENT_TEMPLATE=SEPA

To get the payment templates fields, we need to execute the following request.

The response will be a payment template object with payment fields.

From the response, we can see that payment template SEPA requires the following fields (none of them have optional flag set to true, thus all are mandatory):

• end_to_end_id
• customer_last_logged_at
• customer_ip_address
• creditor_name
• creditor_country_code
• currency_code
• amount
• description
• creditor_iban

The data type for each of these fields is represented by the nature field.

Please note, that within the same payment template the set of required and optional payment fields for one provider can vary from the set for other providers.

For example, the below providers have the following required_payment_fields for SEPA template:

1) Erste Bank and Sparkassen (erste_bank_sparkassen_oauth_client_at)

• debtor_iban
• creditor_iban
• amount
• currency_code
• description

2) Intesa Sanpaolo (intesa_sanpaolo_oauth_client_it)

• debtor_iban
• creditor_iban
• creditor_name
• amount
• currency_code
• description
• creditor_country_code

Note: According to the SEPA template, the following fields are supposed to be optional debtor_iban, creditor_name and creditor_country_code. However, they became required for those specific implementations from the above.

Thus, we recommend inspecting the provider to see its specific set of required_payment_fields and make sure to pass them during the payment creation.

Initiate payment

To initiate a payment via Salt Edge Widget, we need to execute a request to create a payment.

The response will contain the connect_url. This is the URL we will visit to authorize the user and initiate the payment.

If you intend to collect payment consent on your side and the user will select the provider in your application, please make sure that your users are acknowledged by the related Terms and Conditions and Privacy Policy by integration of the following text in your application: “By clicking Proceed you agree to be bound by fino run GmbH Terms and Conditions and Privacy Policy.”

A payment can be generated from your Dashboard, by pressing the Invite button on the Leads page.

Select the Payment Initiation - the purpose of the lead creation step and fill in the mail of your user.

After the button Invite is pressed, a page to select the provider is opened.

Fill in the payment fields (if they are not pre filled as in the case of fake providers).

Copy the connect URL and visit it for the next steps.

Visit Payment Widget URL

Visit the connect_url from the previous API response. You will be presented with a form for user credentials input. Input username and secret as per the on-screen instructions and press Proceed.

After that, you will see the consent window.

In case the provider has interactive fields, a form will be presented for filling these fields.

After confirming, it will start to initiate the payment.

After that, we will have to wait for the payment process to finish.

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.

Salt Edge Payment 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:

• 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).
• The Two-factor authentication must be enabled for your account and all your teammates;
• Be sure to indicate Incident reporting Email in the dashboard settings on the Company page.
• Perform at least one successful payment initiation test with each provider from your key market.

After your Account Manager at Salt Edge has reviewed the app’s integration with Partners Payment Initiation API and made sure that payment initiation tests were successfully performed, the account’s status will be upgraded to live.

Payment Widget

Payment Widget handles all the user interaction during a payment initiation process:

• user credentials input
• interactive confirmation
• progress reporting
• error reporting

After your application has received an URL for executing a payment using Salt Edge Payment Widget, you can redirect your end-user to it. There, they will see a screen that lets them pick a provider to execute a payment.

Your user will also be asked to input credentials and, if needed, any of the interactive credentials. After the process is done, the user will be redirected back to your application URL, or to the URL specified as return_to argument to create payment endpoint.

Embed widget in your app

At the moment, the only way to embed Salt Edge Widget in your application is to open it in a pop-up. When opening it in a pop-up using window.open, it will post notifications during the payment process. To enable these notifications when you request an URL for executing payments, you can pass an optional argument javascript_callback_type with the value post_message.

This tells Salt Edge Widget to use postMessage for sending messages to a parent window. You can then subscribe to those messages by calling window.addEventListener("message", callback) in the parent window.

Callbacks

The most important parts of Partners Payment Initiation API (e.g. Payment initiation) are asynchronous.

Every Web application has to provide a set of valid URLs which will be used to notify about the payment progress. Other applications can poll Salt Edge Partners Payment Initiation API in order to retrieve the current payment status.

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 Payment Initiation 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 (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks do not follow redirects!

Signature

In order for the client to identify that the request is coming from Payment Initiation 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 Payment Initiation 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/payments/callbacks/success|{"data":{"payment_id":"131313131313131313","customer_id":"222222222222222222","custom_fields":{},"status": "processing"},"meta":{"version":"1","time":"2021-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 an operation has caused a change in the data we store for a particular payment.

For instance, after you’ve redirected your users to the Payment Widget page and they have selected a provider, gave consent and pressed Proceed, we’ll send you a success callback. This callback will contain the customer identifier, the id of the newly created payment and its status. Afterwards, your application will be able to use the show payment route and query the information about this payment.

Whenever there is more information about the payment, 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 payment data at each callback, as some information might change during the fetching process.

For instance, when your user has initiated a payment using Salt Edge Payment Widget, we will send the following success callback:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2024-04-17T11:13:57.382Z"
  }
}

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

Failure

Sometimes, a payment might fail to go through. This might happen because for some reason it could not be performed. In this case, you will receive a fail callback, containing a JSON similar to the following:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "status": "rejected",
    "error_class": "PaymentFailed",
    "error_message": "Payment cancelled"
  },
  "meta": {
    "version": "1",
    "time": "2024-04-17T11:13:57.393Z"
  }
}

After you get this callback, you need to request the payment to check for its updates. Please note that even if there’s an error, the payment_id will still be stored.

Notify

After a new payment was created via Partners Payment Initiation, Salt Edge can inform you about the payment’s progress via a notify callback.

Your app can expect the notify callback several times, but you can use this information to inform your end-user about the payment’s progress.

The possible stages sent in a notify callback are described here.

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

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "submission",
    "stage_id": "242424242424242424",
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2024-04-16T11:13:57Z"
  }
}

For some of the payments you might not receive all the stages.

Errors

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

Attributes

Payment status

• failed - the payment failed due to an error on the bank’s side.
• unknown - the payment didn’t reach the end status on the bank’s side. The status can be unknown until we get an updated status from the bank (either rejected or accepted).
• rejected - the payment was rejected either by the user or by the bank. It can be rejected explicitly or due to different errors on the bank’s side.
• no payment object created - an error happened before the payment was created.

Bank integration layer

• Errors could take place either between Salt Edge Partner Payment Initiation API 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 and ExecutionTimeout errors should be reported to Salt Edge.
• The rest of the errors from the below table are caused by incorrect actions of end-users.

Payments API Reference

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

Partners Configuration

• Errors can happen if the partners’s account isn’t configured properly.
• They will not affect payments as none of these errors will allow initiating a payment.
• These errors should be reported to Salt Edge.

FAQ

Can you set up scheduled payments for varied or fixed amounts?

Scheduled Payments support only fixed amounts under existing Payment Initiation API.

Can I issue cross border payments via Partner Payment Initiation API?

Yes, depending on the ASPSP (Provider) API payment product availability.

Can a merchant be added as a trusted beneficiary?

Beneficiary APIs are currently available as premium APIs, with only a small number of banks supporting such functionality. Salt Edge plans to add support for Beneficiary APIs in the future.

Which banks can I use to make payments from a Business Account?

Providers with an supported_account_types array that includes business accounts.

How long will payments take to settle?

This strongly depends on the Payment Product, payment scheme and the ASPSP’s (Provider) internal process.

How can I reconcile a payment?

Using end_to_end_id and/or reference that you can receive via AISP APIs on the creditor account.

How and when do I get a payment_id?

When creating a Payment Order, you need to populate Payment attributes which include a mandatory field as the end_to_end_id, which will be sent to the ASPSP Payment Initiation endpoints. Once the Payment Order is accepted by the Debtor ASPSP for execution, the same end_to_end_id will be sent to the Creditor ASPSP as a part of remittance information. Each Payment Order is also associated with a Salt Edge payment_id to allow listing payments with all associated payment attributes.

Do I have to send the provider_code for each payment request?

Payment Initiation API is not linked to existing connected banks of the Customer. You need to provide the provider_code if you are trying to execute a payment from a Bank or connection known by the Customer.

What is the difference between optional and required payment fields?

Required fields are mandatory for a payment to be initiated, while optional fields are supported by the provider for additional information. However, if optional fields are passed but aren’t present in the optionalpaymentfields, they will be logged on Salt Edge side and not used for the payment initiation process.

Why the very same payment template can have different sets of required and optional payment fields for different providers?

Depending on the standard, the bank implemented PISP and decided to expose functionality so the set of required and optional fields for a payment template can vary for different providers. Some optional fields from a template may become required for a specific bank.

What are the recommendations for the description field?

Most ASPSPs have certain limitations in place when it comes to the formatting of the unstructured payment remittance information (description). Using alphanumeric characters along with ., ,, -, /, ?, (, ), +, ' and spaces as well as keeping the length of the description under 1000 characters should be a safe approach for most ASPSPs (RegExp: /[A-Za-z0-9.-,()+'? ]{2,1000}/). ASPSPs may extend these constraints depending on their core banking system, payment schema and other relevant factors.

How cross-border payments work in Fiducia hub?

At this moment there is no possibility to do a full check prior to the payment initiation whether the payment goes under SEPA or cross-border payment schemes with Fiducia hub providers.

This is how SEPA and cross-border payments are handled on Fiducia’s end:

In principle, a distinction must be made between a normal SEPA credit transfer and a foreign credit transfer. This distinction is to be made on the part of the third party provider and not on the part of the third party provider interface.

Example: A payment is to be made to a beneficiary in France, but in US dollars or with a special fee regulation/instruction, or only one account number is known for the beneficiary, etc.

On Salt Edge’s end SEPA and cross-border payments are handled under SEPA and SWIFT payment templates correspondingly.

Considering there are payment conditions and criteria which can’t be controlled or influenced by TPPs, if the criteria are not met according to the response received from the bank during payment initiation, Salt Edge will return the following errors:

1) PaymentFailed with the message Cross Border Payment is not supported. Please retry using SEPA payment scheme.
2) PaymentFailed with the message Please retry using the cross-border (SWIFT) payment scheme.

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 Financial Institution which can execute payments. We recommend you update all of the providers’ fields at least daily.

Attributes

Show

Provider show allows you to inspect a single provider in order to give your users a proper interface to input their credentials. The response will have an array of required_fields and interactive_fields.

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 Payment Widget page will let you select the fake country and its providers.

Only regulated: true providers support payments via supported payment_templates configuration. It means that it is possible to make a payment only via such regulated providers that have any payment templates listed in payment_templates array.

The API supplies a number of fake providers:

• Fake Interactive Bank with Client Keys (CAPTCHA) (fake_interactive_client_xf) - asks to enter a fake captcha code in addition to a username and a password (embedded);
• Fake Interactive Bank with Client Keys (decoupled) (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).
• Fake OAuth Bank with Client Keys (fake_oauth_client_xf) - asks for authorization (OAuth redirect);
• Fake Bank with Client Keys (fake_client_xf) - requires a username and a password (embedded);
• Fake OAuth Interactive Redirect with Client Keys (fake_oauth_interactive_client_xf);
• Fake Bank with Delayed Payment Authorization (fake_delayed_oauth_client_xf);
• Fake Bank with Invalid Interactive Redirection (fake_invalid_interactive_redirect_xf);
• Fake OAuth Bank with Invalid Authorize URL (fake_with_invalid_authorize_xf);
• Fake Bank with Error (fake_with_error_client_xf).

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 an error because the PSU (the 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.
• 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.
• Payment rejected - Error class: PaymentFailed. Error message: Payment cancelled.
• Payment cancelled - Error class: PaymentFailed. Error message: Payment cancelled.
• Insufficient funds - Error class: PaymentFailed. Error message: Insufficient funds.
• Invalid attribute - Error class: PaymentFailed. Error message: Invalid value for currency_code.
• Payment failed - Error class: PaymentFailed. Error message: Payment failed.
• 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), Fake OAuth Interactive Redirect with Client Keys (fake_oauth_interactive_client_xf) and Fake Bank with Delayed Payment Authorization (fake_delayed_oauth_client_xf) allows selecting the successful scenario you would like to test. The choices are as follows:

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

Note: Check the provider’s instructions in the Payment Widget page for the appropriate credentials.

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 Payment Widget 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 the Payment Widget 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) of the Partner’s application.

Create

Allows to create or return an existing lead. The response contains the email of the lead and the associated customer_id which can be used for creating a payment 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 (i.e. customer) may be asked to manually input the details during the payment session. This depends on the partner configuration, as part of Anti-Money Laundering verifications. 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