general

Overview

Payment Initiation API aims to make payment providers as simple as a cURL.

Payment Initiation API is available for authorized Payment Initiation Service Providers under PSD2 in the EU and Open Banking in the UK.

Integrations

The Salt Edge platform is incredibly easy to integrate with. We’ve built the Salt Edge Connect interface so your application could start executing payments.

Formats

We use JSON for all the requests and responses, including the errors.

Glossary

Most of the API revolves around several important concepts:

• Customer - an end-user of the client who is consuming Payment Initiation API;
• Provider - a bank or an online payment system;
• Payment - a payment that was made using Payment Initiation API.

Quick Start

Before we proceed, make sure you have a Client account or you should create one on the Sign Up page.

Any request to Payment Initiation API is authenticated, so before we are able to fetch any data we need to create API keys. To do that, visit Keys and Secrets and create a Service API key. You can leave the “Public key” field blank.

Providers that support payments require a provider key in order to be used. To create one, visit Provider Keys.

Note: Only providers that have available payment templates support payments execution.

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

Create customer

Before we can create any payments, we need to create a Customer. A Customer in Payment Initiation API is the end-user of your application.

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

See customers reference for Customer related API endpoints.

Choose provider

Firstly, we need to choose a provider that supports payments and has client provider keys. 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 in previous steps we only added client keys for provider fake_client_xf, we can only execute payments using payment templates supported by this provider - SEPA, FPS, and SWIFT.

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) N26 (token.io) (n26_oauth_client_de)

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

3) 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 in Salt Edge Connect, 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.

Visit connect url

Visit the connect_url from the previous API response. You will be presented with a form for user credentials input. Put “fake” in search and choose a Fake Bank:

Input username and secret as per the on-screen instructions and press Proceed.

After that, you will see the consent window.

After confirming, it will start to initiate the payment.

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

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

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 below button to do that.

Step 3

Payment Initiation 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 Keys and Secrets page, then add the environment.

Once added, you can select it in the top right corner, and all the requests to Payment Initiation API will be authenticated using your API key.

Try in Swagger

Step 1

Import Swagger JSON, click the button below to do that.

Download Swagger JSON

Salt Edge Connect

The most simple and easy way to execute payments in Payment Initiation API is to use Salt Edge Connect.

Salt Edge Connect is a web page that 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 Connect, 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.

You can easily test Connect from your Dashboard page by pressing New Payment button or by using the create payment route.

Embed connect in your app

At the moment, the only way to embed Salt Edge Connect 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 Connect 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 Payment Initiation API (e.g. Payment initiation) are asynchronous.

Every Web application has to provide a set of valid URLs which we will use to notify about the payment progress. Other applications can poll 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 Payment Initiation tab on the callbacks page.

Due to security reasons, the callbacks can be sent to ports 80/HTTP (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks do not follow redirects.

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":"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"))

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 Connect 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 we have 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 Connect, we will send the following success callback:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2021-04-09T14:38:00.945Z"
  }
}

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. It may happen because for some reason we could not perform the payment it. 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": "2021-04-09T14:38:00.964Z"
  }
}

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, we still store the payment_id.

Notify

After a new payment was created in the payment initialization process, Salt Edge can inform you about the progress the payment is going through using a notify callback.

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

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": "2021-04-08T14:38:00Z"
  }
}

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

Interactive

Some of the providers require an additional step in the payment initialization process, asking users to input an SMS, Token, solve a CAPTCHA, etc.

Whenever we encounter that the payment initialization process requires an interactive step, we will send the interactive callback to the interactive route set in your app’s profile. Your app should prompt the users for the interactive credentials and send them to the confirm 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 payment’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 /confirm route:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "status": "processing",
    "html": "<div id='interactive'><img src='https://docs.saltedge.com/images/saltedge_captcha.png' width='10' height='10' alt='some description' title='some description'></div>",
    "stage": "interactive",
    "stage_id": "242424242424242424",
    "session_expires_at": "2021-04-08T15:38:01Z",
    "interactive_fields_names": ["image"],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2021-04-08T14:38:01Z"
  }
}

Interactive Redirect

Some OAuth providers require 2 redirects for payment authorization. In these cases, for the 2nd redirect Salt Edge will send an interactive callback with redirect_url field:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "status": "processing",
    "html": "",
    "redirect_url": "https://bank.com/authorize"
    "stage": "interactive",
    "stage_id": "242424242424242424",
    "session_expires_at": "2021-04-08T15:38:01Z",
    "interactive_fields_names": [],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2021-04-08T14:38:01Z"
  }
}

In these cases, your application should redirect the user to redirect_url field value of the interactive callback payload. Once the end-users are authorized on the provider’s side, they will be redirected to the return_to url indicated in the initiate payment request, with a bunch of parameters appended to it by the provider that are needed for authorizing the payment. Those parameters need to be sent to the payments confirm route as query_string field.

Errors

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

Client Configuration

• Errors can happen if the client’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

Does Salt Edge support Bulk Payments?

Support for Bulk Payments is planned in the Salt Edge API v6 during 2021.

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

Scheduled Payments support only fixed amounts under existing Payment Initiation API. Variable Recurring Payments are planned for the Salt Edge API v6 during 2021.

Do I need a PIS licence to initiate payments?

Yes, Salt Edge Clients should be authorized PISP in the UK and/or EU with a valid set of eIDAS (Open Banking UK) certificates.

Can I issue cross border payments?

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.

Do I need to onboard with each bank?

It depends on the ASPSP’s (provider’s) API. If it allows Dynamic Registration and onboarding using eIDAS or Open Banking UK certificates, Salt Edge provides a Dynamic Registration option in the Client Dashboard.

Otherwise, you will need to register and onboard with each ASPSP (Provider) manually and upload the required information to the Provider keys section of the Client Dashboard. For more information, please refer to the Client Provider Keys section.

How do I register several applications?

By Signing Up multiple Client Accounts. We are looking to provide Application Management from the Client Dashboard during 2021.

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.

Is it possible to make a payment with a Partners API using a partner AppId or is it restricted only to the Payment Initiation API?

Payments are not available in Partners API for now.

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. If optional fields are passed, however, they not even present in the optional_payment_fields, they will be logged on our side, but not used for payment initiation.

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 functionality it decided to expose, 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 provider.

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 140 characters should be a safe approach for most ASPSPs (RegExp: /[A-Za-z0-9.-,()+'? ]{1,140}/). ASPSPs may extend these constraints depending on their core banking system, payment schema and other relevant factors.

api

Pay with Connect

The easiest way to initiate payments using Payment Initiation API is to use Salt Edge Connect, which handles all the authentication interaction with the user. After you execute the request, you will receive a connect_url field, which you need to redirect the user to in order to process with the payment flow.

Please see the sequence diagram for details on how to handle payments via Connect.

Parameters

Possible Errors

Pay with Direct API

If you wish to handle the credentials, consent and authorization for payments yourself, you can create payments directly via the API.

Create

Your app will have to pass the user’s values of provider’s fields within the payload in the credentials object. Please note that you still have to use redirects (see OAuth in all cases when the provider mode is oauth).

The credentials object should be modeled after the provider’s fields. For instance, if the provider’s required fields contain a field with the value of name equal to username, the credential object should contain a username attribute with the value being the actual username.

For example, here’s a provider:

{
  "data": {
    "code": "bigbank_us",
    "required_fields": [
      {
        "english_name": "Pass Code",
        "localized_name": "Pass Code",
        "name": "code",
        "nature": "text",
        "position": 1
      }
    ]
  }
}

The user should be prompted to input Pass Code. If they input Pass Code (in this case, “hunter2”), your app should send the following data in the credentials object:

{
  "code": "hunter2"
}

Here’s another example that includes a select:

{
  "data": {
    "code": "anotherbank_us",
    "required_fields": [
      {
        "english_name": "Password",
        "localized_name": "Password",
        "name": "password",
        "nature": "password",
        "position": 1
      },
      {
        "nature":         "select",
        "name":           "image",
        "english_name":   "Image",
        "localized_name": "Imagine",
        "position":       2,
        "optional":       false,
        "field_options": [
          {
            "name":           "1",
            "english_name":   "Home",
            "localized_name": "Casa",
            "option_value":   "home",
            "selected":       false
          },
          {
            "name":           "2",
            "english_name":   "Car",
            "localized_name": "Automobil",
            "option_value":   "car",
            "selected":       false
          }
        ]
      }
    ]
  }
}

In this case, your app should prompt the user to input Password and offer selecting the options of “Casa” and “Automobil” (the localized_name or english_name values, depending on your service). The credentials should contain the name of the select field (in this case image) as the key and the user’s selected option_value as its value. Let’s say the user has input hunter2 as the password and has chosen “Automobil” from the select.

The credentials object should look like this:

{
  "password": "hunter2",
  "image": "car"
}

Please see the sequence diagram for details on how to handle embedded payments correctly.

Payments workflow does not currently support encrypted credentials.

Parameters

Possible Errors

OAuth

Since initiating payments with OAuth providers implies a redirect, the flow for these providers is similar to Pay with Connect. 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 PISP access to make payments, making it available for your app. After the users have approved PISP in the OAuth provider’s interface, they will be redirected to the return_to page.

• Note that return_to is optional for clients only if a shared (owned by Salt Edge) provider key is used (defaults to the client’s home_url).
• If clients use their own provider keys, return_to is mandatory and should be a valid URL that was registered within the chosen provider.

Please see the sequence diagram for details on how to handle OAuth payments directly.

Parameters

Possible Errors

Authorize

Used to authorize a payment for an OAuth provider when using client owned provider keys. In this flow, once the end-users are authorized on the provider’s side, they are redirected to the return_to URL indicated in the previous request, with a bunch of parameters appended to it by the provider that are needed for authorizing the payment.

Examples:

<return_to url>?code=bc4521d3&state=Pd8b4d0eb
<return_to url>#code=bc4521d3&state=Pd8b4d0eb

For both cases, the query_string that is needed to authorize the payment is code=bc4521d3&state=Pd8b4d0eb.

Please note that in some PSD2 specifications the end-user will be redirected to return_to with no additional parameters due to the lack of need to make additional Authorization requests. For such cases, an empty query_string value is acceptable, for example:

{
  "data": {
    "payment_id": "131313131313131313",
    "query_string": ""
  }
}

If the provider returned an error on return_to redirect, thar error should be sent the same way as a successful redirect would be, namely, with parameters in the query_string field:

{
  "data": {
    "payment_id": "131313131313131313",
    "query_string": "error=InternalServerError&message=PSU+SCA+error&state=Pd8b4d0eb"
  }
}

Parameters

Possible Errors