Overview

All Payments API endpoints are available for service authentication only.

Spectre Payments API aims to make payments providers as simple as a cURL.

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 - a customer of the client who is consuming Payment Initiation API;
Provider - a bank or an online payments system;
Payment - a payment that was made using Salt Edge API

Quick Start

Before we proceed, make sure that you have a Spectre Client account (you can register at https://www.saltedge.com/client_users/sign_up).

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 https://www.saltedge.com/keys_and_secrets and create a “Service” API key. You can leave “Public key” field blank.

Providers that support payments require a provider key in order to be used. To create one, visit https://www.saltedge.com/clients/client_provider_keys.

Note that only providers that have Payment Templates available support payments.

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 “111”), because we will use it later to create payments.

See customers reference for Customer related API endpoints.

Sample Request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"test1\" \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/customers/

Sample Response

{
  "data": {
    "id":         "111",
    "identifier": "test1",
    "secret":     "SECRET"
  }
}

$ export CUSTOMER_ID=111

Choose provider

First we need to choose 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 payments provider can support multiple ways of initiating a payment. Each of this method is called a payment_template. We can see from the response that provider fake_client_xf supports payment templates sepa_instant_payment and sepa_instant_payment_with_account_select.

Sample Request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/providers

Sample Response

{
  "data": [
    {
      "id": "1063518971",
      "code": "fake_client_xf",
      "name": "Fake Bank with Client Keys",
      "mode": "api",
      "status": "active",
      "interactive": true,
      "instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\"\n",
      "home_url": "https://example.com",
      "forum_url": "http://forum.saltedge.com/themes/xf/forums/fake_client_xf/all",
      "logo_url": "https://test.cloudfront.net/logos/providers/xf/fake_client_xf.svg",
      "country_code": "XF",
      "created_at": "2018-07-02T11:53:11Z",
      "updated_at": "2018-07-02T11:53:11Z",
      "identification_mode": "client"
      "payment_templates": [
         "sepa_instant_payment",
         "sepa_instant_payment_with_account_select"
      ]
    },
    ...
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

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 providers - sepa_instant_payment and sepa_instant_payment_with_account_select.

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

$ export PAYMENT_TEMPLATE=sepa_instant_payment

To get the payment_template’s 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_instant_payment requires the following fields (none of them have optional flag set to true):

iban_from iban_to amount currency_code description

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

Sample Request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/templates/$PAYMENT_TEMPLATE

Sample Response

{
  "data": {
    "id": "1",
    "identifier": "sepa_instant_payment",
    "description": "SEPA Instant",
    "created_at": "2018-05-01T11:26:00Z",
    "updated_at": "2018-05-01T11:26:00Z",
    "payment_fields": [
      {
        "id": "10",
        "payment_template_id": "1",
        "name": "iban_from",
        "localized_name": "IBAN from",
        "nature": "text",
        "position": 1,
        "checksummable": false,
        "english_name": "IBAN from",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "11",
        "payment_template_id": "1",
        "name": "iban_to",
        "localized_name": "IBAN to",
        "nature": "text",
        "position": 2,
        "checksummable": false,
        "english_name": "IBAN to",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "12",
        "payment_template_id": "1",
        "name": "amount",
        "localized_name": "Amount",
        "nature": "text",
        "position": 3,
        "checksummable": false,
        "english_name": "Amount",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "13",
        "payment_template_id": "1",
        "name": "description",
        "localized_name": "Description",
        "nature": "text",
        "position": 4,
        "checksummable": false,
        "english_name": "Description",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "14",
        "payment_template_id": "1",
        "name": "currency_code",
        "localized_name": "Currency",
        "nature": "select",
        "position": 5,
        "checksummable": false,
        "english_name": "Currency",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      }
    ]
  }
}

Initiate payment

To initiate a payment in Salt Edge Connect, we need to execute a request to create payment using connect endpoint.

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

Sample Request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"template_identifier\": \"$PAYMENT_TEMPLATE\", \
                \"payee_description\": \"Amazon\", \
                \"payment_attributes\": { \
                  \"iban_to\": \"XF12345678123456781231\", \
                  \"iban_from\": \"XF123456789012345678\", \
                  \"currency_code\": \"EUR\", \
                  \"description\": \"One Pay for services\", \
                  \"amount\": \"100\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/connect

Sample Response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2018-07-03T07:23:58Z",
    "connect_url": "https://www.saltedge.com/payments/connect?token=GENERATED_TOKEN"
  }
}

Visit connect url

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

Input username and secret as per the on-screen instructions and press “PAY”.

After that, we will see the consent window.

After confirming, it will try 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.

Salt Edge Connect

The most simple and easiest way to execute payments in Salt Edge 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 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 their 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 an url specified as return_to argument to create payment api endpoint.

You can easily test Connect from your Dashboard page by pressing Create Payment button or by using the create payment API endpoint.

Embeding connect in your appication

At the moment, the only way to embed Salt Edge Connect in your application is to open it in a popup. When opening it in a popup 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 value post_message.

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

Sample Request

  window.addEventListener("message", function(event) {
      console.log(JSON.parse(event.data))
    }
  )

Sample Response

  {
    data: {
      payment_id:    "1",
      custom_fields: {},
      stage:         "start",
      status:        "processing"
    }
  }

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

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":"1234","customer_id":"4321","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 user to the Connect page and they have selected their provider, gave their consent and pressed Pay, 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": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2019-02-19T15:31:06.733Z"
  }
}

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

Failure

Sometimes a payment will fail to go through. It might happen because the interactive data was not sent by the user, provider access was not granted or we could not perform one of the steps of the payment process. In this case, you will receive a fail callback, containing a JSON similar to the following:

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "status": "rejected",
    "error_class": "ProviderAccessNotGranted",
    "error_message": "Provider access was not granted"
  },
  "meta": {
    "version": "1",
    "time": "2019-02-19T15:31:06.735Z"
  }
}

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.

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 user about what’s happening with their payment.

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

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

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

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "submission",
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2019-02-18T15:31:06Z"
  }
}

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 user for the interactive credentials and send them to the interactive route.

We also send a snippet of HTML so that it would be easier for your app to display the CAPTCHA or image to the user. If the provider requires filling a CAPTCHA, the img tag in the HTML will contain the image URL.

During this process, the 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 /interactive route:

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "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",
    "session_expires_at": "2019-02-18T16:31:06Z",
    "interactive_fields_names": ["image"],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2019-02-18T15:31:06Z"
  }
}

Interactive redirect

There are 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": "123",
    "customer_id": "34445",
    "status": "processing",
    "html": "",
    "redirect_url": "https://bank.com/authorize"
    "stage": "interactive",
    "session_expires_at": "2019-02-18T16:31:06Z",
    "interactive_fields_names": [],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2019-02-18T15:31:06Z"
  }
}

In these cases, your application should redirect the user to redirect_url field value of the interactive callback payload. Once the end-user will be authorized on the provider’s side, they will be redirected to the return_to url indicated in the 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 API can return multiple errors for any operation, each having its meaning and usage.

Error attributes

error_class: string
the class of the error, one of the listed below
error_message: string
a message describing the error
request: object
the body of the request that caused the error

Error codes

[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated

Sample response

{
  "error_class": "PaymentNotFound",
  "error_message": "Payment with id: '987' was not found.",
  "request": {
    "id": "987"
  }
}

Errors list

ApiKeyNotFound: the API key with the provided App-id and Secret does not exist or is inactive
AppIdNotProvided: The App-id was not provided in request headers
ClientDisabled: The client has been disabled. You can find out more about the disabled status on Disabled guides page
ClientNotFound: The API key used in the request does not belong to a client
ClientPending: The client is pending approval. You can find out more about the pending status on Pending guides page
ClientRestricted: The client is in the Restricted state. You can find out more about the restricted status on Restricted guides page
ConnectionFailed: Some network errors appear while fetching data
ConnectionLost: Internet connection was lost in the process
CountryNotFound: Sending a country_code that is not present in our system
CustomerNotFound: A customer with such customer_id could not be found
CustomerLocked: Customer is locked
CustomFieldsSizeTooBig: The custom_fields object has more than 1 KB
CustomFieldsFormatInvalid: The custom_fields field is not of type object
DateFormatInvalid: We have received an invalid Date format
DateOutOfRange: Sending a date value that does not fit in admissible range
DuplicatedCustomer: The customer you are trying to create already exists
EmailInvalid: The email is invalid
ExpiresAtInvalid: The Expires-at header is invalid, or is set to more than 1 hour from now in UTC
IdentifierInvalid: Invalid identifier sent for identifying the customer
InteractiveTimeout: It took too long to respond to the interactive question
InternalServerError: An internal error has occured
InvalidCredentials: The customer tried to initiate a payment with invalid credentials
InvalidEncoding: Invalid JSON encoded values
InvalidInteractiveCredentials: Interactive credentials that were sent are wrong
InvalidPaymentAttributes: Invalid payment attributes
JsonParseError: We have received some other request format instead of JSON, or the body could not be parsed
MissingExpiresAt: The Expires-at field is missing in the headers
MissingSignature: The Signature field is missing in the headers
PaymentFailed: Failed to create the payment
PaymentNotFound: Payment was not found
PaymentTemplateNotFound: Payment template was not found
PaymentTemplateNotSupported: The chosen provider does not support the desired payment template
PaymentAlreadyFinished: Payment already finished
PaymentAlreadyAuthorized: Payment already authorized
PaymentInitiationTimeout: Payment initiation timeout
ProviderAccessNotGranted: The customer denied access to his data from the provider’s page
ProviderDisabled: The accessed provider is disabled
ProviderError: There’s an error on the provider’s side which obstructs us from obtaining initiating the payment
ProviderInactive: The accessed provider is inactive at the moment
ProviderNotFound: Sending a provider_code that is not present in our system
ProviderKeyFound: The chosen provider does not have provider keys
ProviderNotInteractive: The payment’s provider has no interactive step
ProviderUnavailable: The provider is temporary unavailable
PublicKeyNotProvided: The client did not provide the public key in his account information
RateLimitExceeded: Too many logins are being processed at the same time from one application
RequestExpired: The request has expired, took longer than mentioned in the Expires-at header
ReturnURLInvalid: The return_to URL is invalid
ReturnURLTooLong: The return_to URL exceeds 2040 characters
RouteNotFound: The action you are trying to access deos not exist
SecretNotProvided: The Secret was not provided in request headers
SignatureNotMatch: The Signature header does not match with the correct one
TooManyRequests: Too many requests have occured for initiating payments from one IP address in a small period of time
ValueOutOfRange: Sending a value (e.g. id) which exceeds integer limit
WrongProviderMode: We do not support the received provider_mode
WrongRequestFormat: The JSON request is incorrectly formed

Pay with Connect

The easiest way to initiate payments using Salt Edge API is to use Salt Edge Connect, which handles all the authentication interaction with the user. After you will 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.

Parameters

customer_id: string, required
the ID of the customer received from customer create
provider_code: string, optional
the code of the desired provider. To access the list of providers that support payments, see providers list. If passed, make sure the chosen provider supports the desired payment template
payment_attributes: object, required
all attributes (required and optional) that are needed for a successful payment initiation received in show templates
template_identifier: string, required
payment template identifier received in show templates
payee_description: string, required
short description of the payment’s target (ex: company name, payee full name)
return_to: string, optional
the URL the user will be redirected to, defaults to client’s home URL
show_consent_confirmation: boolean, optional
if sent as false, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. Default value: true.
disable_provider_search: boolean, optional
if sent as true, together with provider_code, does not allow the user to change the preselected provider
javascript_callback_type: string, optional
allows you to specify what kind of callback type you are expecting. Possible values: post_message. Defaults to null, which means that you will not receive any callbacks.

URL

https://www.saltedge.com/api/payments/v1/payments/connect

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"5122311\", \
                \"provider_code\": \"fake_client_xf\", \
                \"payee_description\": \"Amazon\", \
                \"show_consent_confirmation\": true, \
                \"template_identifier\": \"sepa_instant_payment\", \
                \"payment_attributes\": { \
                  \"iban_to\": \"XF123456789012345678\", \
                  \"iban_from\": \"XF611904300234573201\", \
                  \"amount\": \"100\", \
                  \"description\": \"services\", \
                  \"currency_code\": \"EUR\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/connect

Sample response

{
  "data": {
    "expires_at": "2018-06-14T08:33:48Z",
    "connect_url": "https://www.saltedge.com/payments/connect?token=GENERATED_TOKEN"
  }
}

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. 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 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 their Pass Code. If they input their Pass Code (in this case, the user has input “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 their Password and offer them a select with 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 their password and has chosen “Automobil” from the select.

The credentials object should look like this:

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

Payments workflow does not currently support encrypted credentials.

Parameters

customer_id: string, required
the ID of the customer received from customer create
provider_code: string, required
the code of the desired provider. To access the list of providers that support payments, see providers list
credentials: object, required
the credentials required to initiate the payment
payment_attributes: object, required
all attributes (required and optional) that are needed for a successful payment initiation received in show templates
template_identifier: string, required
payment template identifier received in show templates
custom_fields: object, optional
a JSON object, which will be sent back on any of your callbacks

Possible Errors

ClientDisabled
ClientNotFound
ClientRestricted
CustomFieldsFormatInvalid
CustomerLocked
CustomerNotFound
InvalidCredentials
InvalidPaymentAttributes
JsonParseError
PaymentNotFound
PaymentTemplateNotFound
PaymentTemplateNotSupported
ProviderDisabled
ProviderInactive
ProviderNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"5122311\", \
                \"provider_code\": \"fake_client_xf\", \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                }, \
                \"payment_attributes\": { \
                  \"iban_to\": \"XF611904300234573201\", \
                  \"iban_from\": \"XF123456789012345678\", \
                  \"amount\": \"100\", \
                  \"description\": \"services\", \
                  \"currency_code\": \"EUR\" \
                }, \
                \"template_identifier\": \"sepa_instant_payment\" \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments

Sample response

{
  "data": {
    "id": "164",
    "provider_code": "fake_client_xf",
    "provider_name": "Fake Bank with Client Keys",
    "customer_id": "5122311",
    "created_at": "2018-05-10T08:02:57Z",
    "updated_at": "2018-05-10T08:02:57Z",
    "status": "processing",
    "template_identifier": "sepa_instant_payment",
    "payment_attributes": {
      "amount": "100",
      "iban_to": "XF123456789012345678",
      "iban_from": "XF611904300234573201",
      "description": "services",
      "currency_code": "EUR"
    },
    "stages": [
      {
        "name": "initiated",
        "created_at": "2018-05-10T08:02:57Z"
      }
    ]
  }
}

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 user has approved PISP in the OAuth provider’s interface, they will be redirected to the return_to page. return_to is optional for clients only if they use a shared (owned by Salt Edge) [provider key](/general/#clientproviderkeys (it is set as the client’s home_url by default). If clients use their own provider keys, return_to is required and should be a valid url that was registered within the chosen provider.

Parameters

customer_id: string, required
the ID of the customer received from customer create
provider_code: string, required
the code of the desired oauth provider. To access the list of providers that support payments, see providers list.
payment_attributes: object, required
all attributes (required and optional) that are needed for a successful payment initiation received in show templates
template_identifier: string, required
payment template identifier received in show templates
payee_description: string, required
short description of the payment’s target (ex: company name, payee full name)
return_to: string, required
the url the user will be redirected to after they authenticate on the provider’s side. If you used your own provider keys for the chosen provider, the url to which the end-user will be redirected will contain a bunch of parameters appended by the provider that you need to send to the authorize route in order to authorize the payment

Possible Errors

ClientDisabled
ClientNotFound
ClientRestricted
CustomerLocked
CustomerNotFound
InvalidPaymentAttributes
JsonParseError
PaymentTemplateNotFound
PaymentTemplateNotSupported
ProviderDisabled
ProviderInactive
ProviderNotFound
WrongProviderMode
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments/oauth

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"5122311\", \
                \"provider_code\": \"fake_oauth_client_xf\", \
                \"payee_description\": \"Amazon\", \
                \"template_identifier\": \"sepa_instant_payment\", \
                \"payment_attributes\": { \
                  \"iban_to\": \"XF123456789012345678\", \
                  \"iban_from\": \"XF611904300234573201\", \
                  \"amount\": \"100\", \
                  \"description\": \"services\", \
                  \"currency_code\": \"EUR\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/oauth

Sample response

{
  "data": {
    "payment_id": "123",
    "expires_at": "2019-02-19T16:31:06Z",
    "redirect_url": "https://www.saltedge.com/api/payments/v1/payments/redirect?token=GENERATED_TOKEN"
  }
}

Authorize

Used to authorize a payment for an OAuth provider when using client owned provider keys. In this flow, once the end-user will be authorized on the provider’s side, they will be 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.

Parameters

payment_id: string, required
the id of the payment that is being authorized
query_string: string, required
all the parameters appended to your return_to url upon being redirected from the provider back to your application

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
PaymentAlreadyAuthorized
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments/authorize

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"payment_id\": \"123\", \
                \"query_string\": \"code=bc4521d3&state=Pd8b4d0eb\" \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/authorize

Sample response

{
  "data": {
    "id": "123",
    "provider_code": "fake_oauth_client_xf",
    "provider_name": "Fake OAuth Bank with Client Keys",
    "customer_id": "5122311",
    "created_at": "2018-05-10T08:02:57Z",
    "updated_at": "2018-05-10T08:02:57Z",
    "status": "processing",
    "template_identifier": "sepa_instant_payment",
    "payment_attributes": {
      "amount": "100",
      "iban_to": "XF123456789012345678",
      "iban_from": "XF611904300234573201",
      "description": "services",
      "currency_code": "EUR"
    },
    "stages": [
      {
        "name": "initiated",
        "created_at": "2018-05-10T08:02:57Z"
      }
    ]
  }
}

Confirm

If the currently processing payment requires any interactive credentials, your app should ask the user for the interactive credentials and send them to the /confirm route. After that, the process will continue as usual.

In case of dynamic_select field nature, send the option_value of the user selected options in an array:

{
  "data": {
    "interactive_fields": {
      "accounts": ["account1", "account2"]
    }
  }
}

Please note that in some cases, on interactive stage provider may not require any interactive fields (see interactive_fields_names), thus you should send an empty object in the interactive_fields field:

{
  "data": {
    "interactive_fields": {}
  }
}

In case of an interactive redirect, once the use is redirected to your return_to url, the query string appendend to your return_to should be sent to confirm route:

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.

Parameters

interactive_fields: object, required
the credentials object based on the provider’s interactive fields

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
PaymentAlreadyFinished
PaymentNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments/{payment.id}/confirm

Method

PUT

Sample request (interactive confirmation)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"interactive_fields\": { \
                  \"confirmation_code\": \"123456\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/10/confirm

Sample request (interactive redirect)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"interactive_fields\": { \
                  \"query_string\": \"code=bc4521d3&state=Pd8b4d0eb\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/payments/10/confirm

Sample response

{
    "data": {
        "id": "10",
        "provider_code": "fake_client_xf",
        "provider_name": "Fake Bank with Client Keys",
        "customer_id": "5122311",
        "created_at": "2018-05-10T08:02:57Z",
        "updated_at": "2018-05-10T08:02:57Z",
        "status": "processing",
        "template_identifier": "sepa_instant_payment",
        "payment_attributes": {
          "amount": "100",
          "iban_to": "XF123456789012345678",
          "iban_from": "XF611904300234573201",
          "description": "services",
          "currency_code": "EUR"
        },
        "custom_fields": {},
        "stages": [
            {
                "name": "initialize",
                "created_at": "2018-05-10T10:38:11Z"
            },
            {
                "name": "start",
                "created_at": "2018-05-10T10:38:14Z"
            },
            {
                "name": "submission",
                "created_at": "2018-05-10T10:38:14Z"
            },
            {
                "name": "interactive",
                "created_at": "2018-11-13T12:11:17Z",
                "interactive_html": " <div id='saltedge-interactive' data-saltedge-type='radio' data-saltedge-name='type_index'><span>Please authorize payment for total of 100.35 EUR.</span><ol>  <li value=''>Payment fee.: 0.1 EUR</li><li value=''>Bank fee.: 0.25 EUR</li></ol></div>",
                "interactive_fields_names": [
                    "confirmation_code"
                ],
                "interactive_fields_options": null
            },
            {
                "name": "submission",
                "created_at": "2018-05-10T10:38:23Z",
                "interactive_fields": {
                    "iban": "XF123456789012345678"
                }
            }
        ]
    }
}

Cancel

Allows you to cancel the payment initiation process during the interactive step. See payments confirm.

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
PaymentAlreadyFinished
PaymentNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments/{payment.id}/cancel

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        https://www.saltedge.com/api/payments/v1/payments/10/cancel

Sample response

{
    "data": {
        "id": "10",
        "provider_code": "fake_client_xf",
        "provider_name": "Fake Bank with Client Keys",
        "customer_id": "5122311",
        "created_at": "2018-05-10T12:19:25Z",
        "updated_at": "2018-05-10T12:19:33Z",
        "status": "rejected",
        "template_identifier": "sepa_instant_payment",
        "payment_attributes": {
            "amount": "100",
            "iban_to": "XF611904300234573201",
            "iban_from": "XF123456789012345678",
            "description": "services",
            "currency_code": "EUR"
        },
        "custom_fields": {},
        "stages": [
            {
                "name": "initialize",
                "created_at": "2018-05-10T12:19:25Z"
            },
            {
                "name": "start",
                "created_at": "2018-05-10T12:19:25Z"
            },
            {
                "name": "submission",
                "created_at": "2018-05-10T12:19:25Z"
            },
            {
                "name": "interactive",
                "created_at": "2018-11-13T12:11:17Z",
                "interactive_html": " <div id='saltedge-interactive' data-saltedge-type='radio' data-saltedge-name='type_index'><span>Please authorize payment for total of 100.35 EUR.</span><ol>  <li value=''>Payment fee.: 0.1 EUR</li><li value=''>Bank fee.: 0.25 EUR</li></ol></div>",
                "interactive_fields_names": [
                    "confirmation_code"
                ],
                "interactive_fields_options": null
            },
            {
                "name": "finish",
                "created_at": "2018-05-10T12:19:33Z"
            }
        ]
    }
}

Providers

A provider is an Financial Institution which can execute payments. We recommend you update all of the provider’s fields at least daily.

Attributes

id: string
provider’s id
code: string
provider’s code
name: string
provider’s name
mode: string
possible values are: oauth, api
status: string
possible values are: active, inactive, disabled
interactive: boolean
whether the provider requires interactive input
identification_mode: string
whether the request to the provider is made with your authorization headers or with SaltEdge’s. Possible values are: client, saltedge
instruction: string
instructions on how to connect the bank, in English
home_url: string
the url of the main page of the provider
forum_url: string
the url for the Salt Edge Forum page, dedicated to the provider
logo_url: string
the url for the provider logo, may have a placeholder for providers with missing logos
country_code: string
code of the provider’s country
payment_templates: array of strings
identifiers of the payment templates that are supported by this provider
created_at: datetime
updated_at: datetime

Sample object

{
  "id": "123",
  "code": "fakebank_client_xf",
  "name": "Fake Bank with Client Keys",
  "mode": "api",
  "status": "active",
  "interactive": true,
  "identification_mode": "client",
  "instruction": "Please fill in all the fields.",
  "home_url": "http://example.com",
  "forum_url": "https://forum.saltedge.com/themes/xf/forums/fake_client_xf/all",
  "logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
  "country_code": "XF",
  "payment_templates": ["sepa_instant_payment"]
  "created_at": "2019-02-09T15:31:06Z",
  "updated_at": "2019-02-14T15:31:06Z"
}

Provider 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

provider_code: string
provider’s code

Possible Errors

ClientDisabled
ClientNotFound
ProviderNotFound

URL

https://www.saltedge.com/api/payments/v1/providers/{provider.code}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/providers/fake_client_xf

Sample response

{
  "data": {
    "id": "123",
    "code": "fake_client_xf",
    "country_code": "XF",
    "created_at": "2014-02-07T12:56:54Z",
    "forum_url": "https://forum.banksalt.com/themes/xf/forums/fake_client_xf/all",
    "logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
    "home_url": "http://example.com",
    "instruction": "Fill in all the fields",
    "interactive": true,
    "identification_mode": "client",
    "mode": "api",
    "name": "Fake Bank with Client Keys",
    "payment_templates": ["sepa_instant_payment"]
    "required_fields": [
      {
        "english_name": "Login",
        "localized_name": "Login",
        "name": "login",
        "nature": "text",
        "optional": false,
        "position": 1
      },
      {
        "english_name": "Password",
        "localized_name": "Password",
        "name": "password",
        "nature": "password",
        "optional": false,
        "position": 2
      }
    ],
    "status": "active",
    "updated_at": "2014-06-06T13:34:35Z"
  }
}

Listing providers

Returns all the providers we operate with. If a provider becomes disabled, it is not included in the list. You can read more about the next_id field, in the pagination section of the reference.

Providers that require a client provider key will be included only if you have created provider keys for them.

Parameters

from_id: string, optional
the id of the record starting the next page, defaults to null
from_date: date, optional
filtering providers created or updated starting from this date, defaults to null
country_code: string, optional
filtering providers by country, defaults to null
mode: string, optional
filtering providers by mode, possible values are: oauth, api
include_fake_providers: boolean, optional
whether you wish to fetch the fake providers, defaults to false
template_identifier: string, optional
return only providers that support the given payment template
provider_key_owner: string, optional
filtering providers by key owner, possible values are: client, saltedge. When value is set as client, only providers with client-set keys will be returned. Please see Client Provider Keys

Possible Errors

ClientDisabled
ClientNotFound
DateOutOfRange
ValueOutOfRange

URL

https://www.saltedge.com/api/payments/v1/providers

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/providers

Sample Response

{
  "data": [
    {
      "id": "123",
      "code": "fake_client_xf",
      "name": "Fake Bank with Client Keys",
      "mode": "api",
      "status": "active",
      "interactive": true,
      "identification_mode": "client",
      "instruction": "Please fill in all the fields.",
      "home_url": "http://example.com",
      "forum_url": "http://forum.banksalt.com/themes/xf/forums/fake_client_xf/all",
      "logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
      "country_code": "XF",
      "payment_templates": ["sepa_instant_payment"]
      "created_at": "2019-02-09T15:31:06Z",
      "updated_at": "2019-02-14T15:31:06Z"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Fake providers

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:

fake_client_xf - requires a username and password (embedded);
fake_oauth_client_xf - asks for authorization (OAuth redirect);

Both providers require for Client Provider Keys to be set. Check the provider’s instructions in the Connect page for the appropriate credentials.

Sandboxes

We also add all sandboxes and model banks as providers to XF country. Currenly Salt Edge has the following sandboxes:

bnpparibas_obp_client_sg_xf
bendigo_obp_client_au_xf
bnpparibas_obp_client_gb_xf
rba_obp_client_au_xf
tyro_obp_client_au_xf
anz_obp_client_au_xf
eftpos_obp_client_au_xf
cuscal_obp_client_au_xf
suncorp_obp_client_au_xf
bnpparibas_obp_client_it_xf
westpac_obp_client_au_xf
santander_obp_client_gb_xf
bnpparibas_obp_client_fr_xf
bnpparibas_obp_client_de_xf
commbank_obp_client_au_xf
bnpparibas_obp_client_be_xf
nab_obp_client_au_xf
forgerock_client_gb_xf
ozone_client_gb_xf

Customers

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

Create customer

Creates a customer, returning the customer object.

Parameters

identifier: string, required
a unique identifier of the new customer

Possible Errors

ClientDisabled
ClientNotFound
DuplicatedCustomer
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/customers

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"12rv1212f1efxchsdhbgv\" \
              } \
            }" \
        https://www.saltedge.com/api/payments/v1/customers/

Sample Response

{
  "data": {
    "id":         "18892",
    "identifier": "12rv1212f1efxchsdhbgv",
    "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
  }
}

Show customer

Returns the customer object.

Parameters

id: string, required
the id of the customer

Possible Errors

ClientDisabled
ClientNotFound
CustomerNotFound

URL

https://www.saltedge.com/api/payments/v1/customers/{customer.id}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/customers/18892

Sample Response

{
  "data": {
    "id":         "18892",
    "identifier": "12rv1212f1efxchsdhbgv",
    "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
  }
}

List customers

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

Possible Errors

ClientDisabled
ClientNotFound

URL

https://www.saltedge.com/api/payments/v1/customers

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/customers

Sample Response

{
  "data": [
    {
      "id":         "123",
      "identifier": "unique_customer_identifier",
      "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
    },
    {
      "id":         "124",
      "identifier": "unique_customer_identifier_2",
      "secret":     "Ct124tk12j0129i10-1j2k124kgk1lgqvUJ8CIC80-8"
    }
  ],
  "meta": {
    "next_id": "125",
    "next_page": "/api/payments/v1/customers?from_id=125"
  }
}

Remove customer

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

Possible Errors

ClientDisabled
ClientNotFound
CustomerNotFound
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/customers/{customer.id}

Method

DELETE

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/payments/v1/customers/124

Sample Response

{
  "data": {
    "deleted": true,
    "id":      "11215151"
  }
}

Lock customer

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

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

Possible Errors

ClientDisabled
ClientNotFound
CustomerNotFound
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/customers/{customer.id}/lock

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        https://www.saltedge.com/api/payments/v1/customers/124/lock

Sample Response

{
  "data": {
    "locked": true,
    "id":     "124"
  }
}

Unlock customer

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

Possible Errors

ClientDisabled
ClientNotFound
CustomerNotFound
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/customers/{customer.id}/unlock

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X PUT \
        https://www.saltedge.com/api/payments/v1/customers/124/unlock

Sample Response

{
  "data": {
    "unlocked": true,
    "id":     "124"
  }
}

Payments

The payment resource represents a detailed description of a particular payment. They are meant to provide you with more information about the executed payments for further usage in technical and statistical purposes.

Attributes

id: string
payment_attributes: object
filled payment template fields
template_identifier: string
the identifier of the payment template used for this payment
status: string
possible values are: processing, accepted, rejected, failed
stages: array of stage objects
information about stages through which the payment has passed
created_at: datetime
updated_at: datetime

Sample object

{
  "data": {
    "id": "398",
    "payment_attributes": {
      "amount": "120",
      "iban_to": "DE12345678123456781231",
      "description": "test",
      "currency_code": "EUR"
    },
    "status": "processing",
    "stages": [
      {
        "name": "initialize",
        "created_at": "2018-05-10T09:44:54Z"
      },
      {
        "name": "start",
        "created_at": "2018-05-10T09:44:55Z"
      },
      {
        "name": "interactive",
        "created_at": "2018-05-10T09:44:56Z",
        "interactive_html": "<div id='saltedge-interactive' data-saltedge-type='radio' data-saltedge-name='iban'>\n<span>Choose and input account iban:</span>\n<ol>\n<li value='XF123456789012345678'>XF123456789012345678 (800.0 EUR)</li><li value='XF876543210987654321'>XF876543210987654321 (800.0 USD)</li>\n</ol>\n</div>\n",
        "interactive_fields_names": [
          "iban"
        ]
      }
    ],
    "created_at": "2018-05-10T09:44:54Z",
    "updated_at": "2018-05-10T09:44:56Z"
  }
}

Show

Returns a single payment object.

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
PaymentNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments/{payment.id}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/payments/20

Sample response

{
    "data": {
        "id": "10",
        "provider_code": "fake_client_xf",
        "provider_name": "Fake Bank with Client Keys",
        "customer_id": "5122311",
        "created_at": "2018-05-10T12:42:16Z",
        "updated_at": "2018-05-10T12:42:36Z",
        "status": "accepted",
        "template_identifier": "sepa_instant_payment",
        "payment_attributes": {
            "amount": "100",
            "iban_to": "XF611904300234573201",
            "iban_from": "XF123456789012345678",
            "description": "services",
            "currency_code": "EUR"
        },
        "custom_fields": {},
        "stages": [
            {
                "name": "initialize",
                "created_at": "2018-05-10T12:42:16Z"
            },
            {
                "name": "start",
                "created_at": "2018-05-10T12:42:21Z"
            },
            {
                "name": "submission",
                "created_at": "2018-05-10T12:42:21Z"
            },
            {
                "name": "interactive",
                "created_at": "2018-05-10T12:42:22Z",
                "interactive_html": "<div id='saltedge-interactive' data-saltedge-type='radio' data-saltedge-name='type_index'><span>Please authorize payment for total of 100.35 EUR.</span><ol> <li value=''>Payment fee.: 0.1 EUR</li><li value=''>Bank fee.: 0.25 EUR</li></ol></div>",
                "interactive_fields_names": [
                    "confirmation_code"
                ],
                "interactive_fields_options": null
            },
            {
                "name": "submission",
                "created_at": "2018-05-10T12:42:36Z",
                "interactive_fields": {
                    "iban": "XF123456789012345678",
                    "confirmation_code": 123456
                }
            },
            {
                "name": "settlement",
                "created_at": "2018-05-10T12:42:36Z"
            },
            {
                "name": "completed",
                "created_at": "2018-05-10T12:42:36Z"
            },
            {
                "name": "finish",
                "created_at": "2018-05-10T12:42:36Z"
            }
        ]
    }
}

List

Returns all the payments accessible to your application. The payments are sorted in ascending order of their ID, so the newest payments will come last. We recommend you fetch the whole list of payments to check whether any of the properties have changed. You can read more about next_id field, in the pagination section of the reference.

Parameters

from_id: string, optional
the id of the record starting the next page, defaults to null
customer_id: string, optional
the id of the customer, allows to fetch payments only for a certain customer

Possible Errors

ClientDisabled
ClientNotFound
CustomerNotFound
JsonParseError
ValueOutOfRange
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/payments

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/payments

Sample response

{
  "data": [
    {
      "id": "100",
      "provider_code": "fake_client_xf",
      "provider_name": "Fake Bank with Client Keys",
      "customer_id": "5122311",
      "created_at": "2018-05-10T12:42:16Z",
      "updated_at": "2018-05-10T12:42:36Z",
      "status": "processing",
      "template_identifier": "sepa_instant_payment",
      "payment_attributes": {
        "amount": "100",
        "iban_to": "XF611904300234573201",
        "iban_from": "XF123456789012345678",
        "description": "services",
        "currency_code": "EUR"
      },
      "stages": [
        {
          "name": "initialize",
          "created_at": "2018-05-10T09:44:54Z"
        },
        {
          "name": "start",
          "created_at": "2018-05-10T09:44:55Z"
        },
        {
          "name": "interactive",
          "created_at": "2018-05-10T09:44:56Z",
          "interactive_html": "<div id='saltedge-interactive' data-saltedge-type='radio' data-saltedge-name='iban'><span>Choose and input account iban:</span><ol><li value='XF123456789012345678'>XF123456789012345678 (800.0 EUR)</li><li value='XF876543210987654321'>XF876543210987654321 (800.0 USD)</li></ol></div>",
          "interactive_fields_names": [
            "iban"
          ]
        }
      ]
    }
  ],
  "meta": {
      "next_id": "101",
      "next_page": "/api/payments/v1/payments?from_id=101"
  }
}

Stages

The following represents the objects you get in the stages field of the payment object.

name

string

the name of the stage. Possible values:

start - the payment process has just begun;
interactive - waiting for the interactive input;
submission - preparing a payment initiation request for submission to the financial institution;
settlement - payment initiation request accepted by financial institution, waiting for settlement to complete;
completed - payment initiation settlement completed, funds sent;
finish - wrapping up the payment process.

interactive_html

string

HTML code that shows the current interactive state of the payment. Appears only for interactive providers

interactive_fields_names

array of strings

the interactive fields that are currently required by the provider of the payment. Appears only for interactive providers

created_at

datetime

when the stage was created

Templates

The payment template resource contains a set of required and optional fields that need to be filled in order to successfully execute a payment. Different payment templates serve different purposes.

Attributes

id: string
identifier: string
unique identifier of the template
description: string
deprecated: boolean
whether the payment template is deprecated or not. Deprecated payment templates will be removed in next api version.
payment_fields: array of payment fields objects
created_at: datetime
updated_at: datetime

Sample object

{
  "id": "1",
  "identifier": "sepa_instant_payment",
  "description": "SEPA Instant",
  "deprecated": false,
  "created_at": "2018-05-01T11:26:00Z",
  "updated_at": "2018-05-01T11:26:00Z",
  "payment_fields": [
    {
      "id": "10",
      "payment_template_id": "1",
      "name": "iban_from",
      "localized_name": "IBAN from",
      "nature": "text",
      "position": 1,
      "english_name": "IBAN from",
      "extra": {
        "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
      },
      "optional": false,
      "created_at": "2018-05-02T12:35:08Z",
      "updated_at": "2018-05-02T12:35:08Z"
    },
    {
      "id": "11",
      "payment_template_id": "1",
      "name": "iban_to",
      "localized_name": "IBAN to",
      "nature": "text",
      "position": 2,
      "english_name": "IBAN to",
      "extra": {
        "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
      },
      "optional": false,
      "created_at": "2018-05-02T12:35:08Z",
      "updated_at": "2018-05-02T12:35:08Z"
    },
    {
      "id": "12",
      "payment_template_id": "1",
      "name": "amount",
      "localized_name": "Amount",
      "nature": "number",
      "position": 3,
      "english_name": "Amount",
      "extra": {
        "validation_regexp": "^[-+]?[0-9]*\\.?[0-9]+$"
      },
      "optional": false,
      "created_at": "2018-05-02T12:35:08Z",
      "updated_at": "2018-05-02T12:35:08Z"
    },
    {
      "id": "13",
      "payment_template_id": "1",
      "name": "description",
      "localized_name": "Description",
      "nature": "text",
      "position": 4,
      "english_name": "Description",
      "extra": {
        "validation_regexp": "^.{2,1000}$"
      },
      "optional": false,
      "created_at": "2018-05-02T12:35:08Z",
      "updated_at": "2018-05-02T12:35:08Z"
    },
    {
      "id": "14",
      "payment_template_id": "1",
      "name": "currency_code",
      "localized_name": "Currency",
      "nature": "select",
      "position": 5,
      "english_name": "Currency",
      "extra": {},
      "optional": false,
      "created_at": "2018-05-02T12:35:08Z",
      "updated_at": "2018-05-02T12:35:08Z"
    }
  ]
}

Show

Returns a single payment template object.

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
PaymentTemplateNotFound
RateLimitExceeded
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/templates/{template.identifier}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/templates/sepa_instant_payment

Sample response

{
  "data": {
    "id": "1",
    "identifier": "sepa_instant_payment",
    "description": "SEPA Instant",
    "deprecated": false,
    "created_at": "2018-05-01T11:26:00Z",
    "updated_at": "2018-05-01T11:26:00Z",
    "payment_fields": [
      {
        "id": "10",
        "payment_template_id": "1",
        "name": "iban_from",
        "localized_name": "IBAN from",
        "nature": "text",
        "position": 1,
        "english_name": "IBAN from",
        "extra": {
          "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
        },
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "11",
        "payment_template_id": "1",
        "name": "iban_to",
        "localized_name": "IBAN to",
        "nature": "text",
        "position": 2,
        "english_name": "IBAN to",
        "extra": {
          "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
        },
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "12",
        "payment_template_id": "1",
        "name": "amount",
        "localized_name": "Amount",
        "nature": "number",
        "position": 3,
        "english_name": "Amount",
        "extra": {
          "validation_regexp": "^[-+]?[0-9]*\\.?[0-9]+$"
        },
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "13",
        "payment_template_id": "1",
        "name": "description",
        "localized_name": "Description",
        "nature": "text",
        "position": 4,
        "english_name": "Description",
        "extra": {
          "validation_regexp": "^.{2,1000}$"
        },
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      },
      {
        "id": "14",
        "payment_template_id": "1",
        "name": "currency_code",
        "localized_name": "Currency",
        "nature": "select",
        "position": 5,
        "english_name": "Currency",
        "extra": {},
        "optional": false,
        "created_at": "2018-05-02T12:35:08Z",
        "updated_at": "2018-05-02T12:35:08Z"
      }
    ]
  }
}

List

Returns all the available payment templates.

Parameters

from_id: string, optional
the id of the record starting the next page, defaults to null
deprecated: boolean, optional
filtering payment templates by deprecation. All payment templates will be returned if no value set.

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
ProviderNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/payments/v1/templates

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: APP_ID" \
        -H "Secret: SECRET" \
        -X GET \
        https://www.saltedge.com/api/payments/v1/templates

Sample response

{
  "data": [
    {
      "id": "1",
      "identifier": "sepa_instant_payment",
      "description": "SEPA Instant",
      "deprecated": false,
      "provider_id": 1006496956,
      "created_at": "2018-05-01T11:26:00Z",
      "updated_at": "2018-05-01T11:26:00Z",
      "payment_fields": [
        {
          "id": "10",
          "payment_template_id": "1",
          "name": "iban_from",
          "localized_name": "IBAN from",
          "nature": "text",
          "position": 1,
          "english_name": "IBAN from",
          "extra": {
            "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
          },
          "optional": false,
          "created_at": "2018-05-02T12:35:08Z",
          "updated_at": "2018-05-02T12:35:08Z"
        },
        {
          "id": "11",
          "payment_template_id": "1",
          "name": "iban_to",
          "localized_name": "IBAN to",
          "nature": "text",
          "position": 2,
          "english_name": "IBAN to",
          "extra": {
            "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
          },
          "optional": false,
          "created_at": "2018-05-02T12:35:08Z",
          "updated_at": "2018-05-02T12:35:08Z"
        },
        {
          "id": "12",
          "payment_template_id": "1",
          "name": "amount",
          "localized_name": "Amount",
          "nature": "text",
          "position": 3,
          "english_name": "Amount",
          "extra": {
            "validation_regexp": "^[-+]?[0-9]*\\.?[0-9]+$"
          },
          "optional": false,
          "created_at": "2018-05-02T12:35:08Z",
          "updated_at": "2018-05-02T12:35:08Z"
        },
        {
          "id": "13",
          "payment_template_id": "1",
          "name": "description",
          "localized_name": "Description",
          "nature": "text",
          "position": 4,
          "english_name": "Description",
          "extra": {
            "validation_regexp": "^.{2,1000}$"
          },
          "optional": false,
          "created_at": "2018-05-02T12:35:08Z",
          "updated_at": "2018-05-02T12:35:08Z"
        },
        {
          "id": "14",
          "payment_template_id": "1",
          "name": "currency_code",
          "localized_name": "Currency",
          "nature": "select",
          "position": 5,
          "english_name": "Currency",
          "extra": {},
          "optional": false,
          "created_at": "2018-05-02T12:35:08Z",
          "updated_at": "2018-05-02T12:35:08Z"
        }
      ]
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Payment fields

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

id: string
payment_template_id: string
the ID of the payment template
name: string
the field’s name that should be used as a key in the credentials object
english_name: string
the field’s name in US English
localized_name: string
the field’s name in the provider’s main language
nature: string
possible values are: text, password, select, file, number, dynamic_select
position: integer
field’s position in the public user interface
extra: object, extra object
extra data associated with the payment field
optional: boolean
whether the input for this field is optional or not
field_options: object
only for the select field type. Contains the options for the select
created_at: datetime
updated_at: datetime

Sample object

{
  "id": "10",
  "payment_template_id": "2",
  "name": "iban_from",
  "english_name": "IBAN from",
  "localized_name": "IBAN from",
  "nature": "text",
  "position": 1,
  "extra": {
    "validation_regexp": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[A-Z0-9]{7}([a-zA-Z0-9]?){0,16}$"
  },
  "optional": false,
  "created_at": "2018-05-02T12:35:08Z",
  "updated_at": "2018-05-02T12:35:08Z"
}

Payment fields extra

The following represents the object you get in the `extra` field of the payment field object. Note: You may or may not have all of the fields listed below.

validation_regexp: string
the regexp used for payment field validation

Faster Payment

end_to_end_id: string, required
Identifier
customer_last_logged_at: datetime, required
Time when the customer was last logged
customer_ip_address: string, required
IP address of the customer
customer_ip_port: string, optional
port of the customer
customer_device_os: string, required
OS of the customer
customer_user_agent: string, optional
User Agent of the customer
customer_latitude: string, optional
(must laso have customer_longitude if present)
customer_longitude: string, optional
(must laso have customer_latitude if present)
debtor_name: string, optional
Full Name of the debtor (payer)
debtor_address: string, optional
Full address of the debtor
debtor_street_name: string, optional
Street name of the debtor
debtor_building_number: string, optional
Building number of the debtor
debtor_post_code: string, optional
Post code of the debtor
debtor_town: string, optional
The name of the town/city of the debtor
debtor_region: string, optional
The name of the country/region of the debtor
debtor_country_code: string, optional
The ISO code of the debtor’s country
creditor_name: string, required
Full Name of the creditor (payee)
creditor_agent: string, optional
ID of the creditor’s agent
creditor_agent_name: string, optional
Name of the creditor’s agent
creditor_address: string, optional
Full address of the creditor
creditor_street_name: string, required
Street name of the creditor
creditor_building_number: string, required
Building number of the creditor
creditor_post_code: string, required
Post code of the creditor
creditor_town: string, required
The name of the town/city of the creditor
creditor_region: string, optional
The name of the country/region of the creditor
creditor_country_code: string, required
The ISO code of the creditor’s country
currency_code: string, required
Payment currency
amount: string, required
Payment amount in the specified currency
description: string, required
Unstructured description of the payment
purpose_code: string, optional
ISO 18245 purpose code
date: date, optional
Date to execute payment (defaults to current date)
time: time, optional
Time to execute payment (defaults to current time)
debtor_sort_code: string, optional
Debtor’s bank sort code
debtor_account_number: string, optional
Debtor’s bank account number
creditor_sort_code: string, required
Creditor’s bank sort code
creditor_account_number: string, required
Creditor’s bank account number

Sample payment attributes

{
  "end_to_end_id": "#123123123",
  "customer_last_logged_at": "2018-11-21T13:48:40Z",
  "customer_ip_address": "10.0.0.1",
  "customer_ip_port": "3456",
  "customer_device_os": "iOS 11",
  "customer_user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36",
  "customer_latitude": "51.5074",
  "customer_longitude": "0.1278",
  "debtor_name": "Riley Atkins",
  "debtor_address": "2 Irving Grove, London SW9 9HL, UK",
  "debtor_street_name": "Irving Grove",
  "debtor_building_number": "2",
  "debtor_post_code": "SW9 9HL",
  "debtor_town": "London",
  "debtor_region": "England",
  "debtor_country_code": "UK",
  "creditor_name": "Jay Dawson",
  "creditor_agent": "123456",
  "creditor_agent_name": "Treasury Devision",
  "creditor_address": "Level 39, One Canada Square, Canary Wharf, London E14 5AB, UK",
  "creditor_street_name": "One Canada Square",
  "creditor_building_number": "One",
  "creditor_post_code": "E14 5AB",
  "creditor_town": "London",
  "creditor_region": "England",
  "creditor_country_code": "UK",
  "amount": "199000.00",
  "currency_code": "GBP",
  "description": "Stocks purchase",
  "purpose_code": "3456",
  "date": "2018-11-20",
  "time": "10:20:30",
  "debtor_sort_code": "40-47-84",
  "debtor_account_number": "70872490",
  "creditor_sort_code": "56-00-03",
  "creditor_account_number": "13354647"
}

SEPA

end_to_end_id: string, required
Identifier
customer_last_logged_at: datetime, required
Time when the customer was last logged
customer_ip_address: string, required
IP address of the customer
customer_ip_port: string, optional
port of the customer
customer_device_os: string, required
OS of the customer
customer_user_agent: string, optional
User Agent of the customer
customer_latitude: string, optional
(must laso have customer_longitude if present)
customer_longitude: string, optional
(must laso have customer_latitude if present)
debtor_name: string, optional
Full Name of the debtor (payer)
debtor_address: string, optional
Full address of the debtor
debtor_street_name: string, optional
Street name of the debtor
debtor_building_number: string, optional
Building number of the debtor
debtor_post_code: string, optional
Post code of the debtor
debtor_town: string, optional
The name of the town/city of the debtor
debtor_region: string, optional
The name of the country/region of the debtor
debtor_country_code: string, optional
The ISO code of the debtor’s country
creditor_name: string, required
Full Name of the creditor (payee)
creditor_agent: string, optional
ID of the creditor’s agent
creditor_agent_name: string, optional
Name of the creditor’s agent
creditor_address: string, optional
Full address of the creditor
creditor_street_name: string, required
Street name of the creditor
creditor_building_number: string, required
Building number of the creditor
creditor_post_code: string, required
Post code of the creditor
creditor_town: string, required
The name of the town/city of the creditor
creditor_region: string, optional
The name of the country/region of the creditor
creditor_country_code: string, required
The ISO code of the creditor’s country
currency_code: string, required
Payment currency
amount: string, required
Payment amount in the specified currency
description: string, required
Unstructured description of the payment
purpose_code: string, optional
ISO 18245 purpose code
date: date, optional
Date to execute payment (defaults to current date)
time: time, optional
Time to execute payment (defaults to current time)
debtor_iban: string, optional
Debtor’s IBAN
creditor_iban: string, required
Creditor’s IBAN
mode: string, optional
NORMAL or INSTANT

Sample payment attributes

{
  "end_to_end_id": "#123123123",
  "customer_last_logged_at": "2018-11-21T13:48:40Z",
  "customer_ip_address": "10.0.0.1",
  "customer_ip_port": "3456",
  "customer_device_os": "iOS 11",
  "customer_user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36",
  "customer_latitude": "51.5074",
  "customer_longitude": "0.1278",
  "debtor_name": "Lucas Hahn",
  "debtor_address": "Fehrbelliner Str. 95, 10119 Berlin, Germany",
  "debtor_street_name": "Fehrbelliner Str.",
  "debtor_building_number": "95",
  "debtor_post_code": "10119",
  "debtor_town": "Berlin",
  "debtor_region": "Germany",
  "debtor_country_code": "DE",
  "creditor_name": "Jay Dawson",
  "creditor_agent": "123456",
  "creditor_agent_name": "Treasury Devision",
  "creditor_address": "Level 39, One Canada Square, Canary Wharf, London E14 5AB, UK",
  "creditor_street_name": "One Canada Square",
  "creditor_building_number": "One",
  "creditor_post_code": "E14 5AB",
  "creditor_town": "London",
  "creditor_region": "England",
  "creditor_country_code": "UK",
  "amount": "199000.00",
  "currency_code": "EUR",
  "description": "Stocks purchase",
  "purpose_code": "3456",
  "date": "2018-11-20",
  "time": "10:20:30",
  "debtor_iban": "DE75512108001245126199",
  "creditor_iban": "GB33BUKB20201555555555",
  "mode": "INSTANT"
}

SWIFT

end_to_end_id: string, required
Identifier
customer_last_logged_at: datetime, required
Time when the customer was last logged
customer_ip_address: string, required
IP address of the customer
customer_ip_port: string, optional
port of the customer
customer_device_os: string, required
OS of the customer
customer_user_agent: string, optional
User Agent of the customer
customer_latitude: string, optional
(must laso have customer_longitude if present)
customer_longitude: string, optional
(must laso have customer_latitude if present)
debtor_name: string, optional
Full Name of the debtor (payer)
debtor_address: string, optional
Full address of the debtor
debtor_street_name: string, optional
Street name of the debtor
debtor_building_number: string, optional
Building number of the debtor
debtor_post_code: string, optional
Post code of the debtor
debtor_town: string, optional
The name of the town/city of the debtor
debtor_region: string, optional
The name of the country/region of the debtor
debtor_country_code: string, optional
The ISO code of the debtor’s country
creditor_name: string, required
Full Name of the creditor (payee)
creditor_agent: string, optional
ID of the creditor’s agent
creditor_agent_name: string, optional
Name of the creditor’s agent
creditor_address: string, optional
Full address of the creditor
creditor_street_name: string, required
Street name of the creditor
creditor_building_number: string, required
Building number of the creditor
creditor_post_code: string, required
Post code of the creditor
creditor_town: string, required
The name of the town/city of the creditor
creditor_region: string, optional
The name of the country/region of the creditor
creditor_country_code: string, required
The ISO code of the creditor’s country
currency_code: string, required
Payment currency
amount: string, required
Payment amount in the specified currency
description: string, required
Unstructured description of the payment
purpose_code: string, optional
ISO 18245 purpose code
date: date, optional
Date to execute payment (defaults to current date)
time: time, optional
Time to execute payment (defaults to current time)
debtor_account_number: string, optional
Debtor’s account Number
creditor_account_number: string, required
Creditor’s account number
creditor_bank_swift_code: string, required
Credtior’s bank SWIFT code
creditor_bank_name: string, required
Credtior’s bank name
creditor_bank_address: string, optional
Credtior’s bank full address
creditor_bank_street_name: string, required
Credtior’s bank street name
creditor_bank_building_number: string, required
Credtior’s bank building number
creditor_bank_post_code: string, required
Credtior’s bank post code
creditor_bank_town: string, required
Credtior’s bank town/city
creditor_bank_region: string, optional
Credtior’s bank country/region
creditor_bank_country_code: string, required
Credtior’s bank ISO country code
correspondent_account_number: string, optional
Correspondent account number
correspondent_bank_name: string, optional
Correspondent bank name
correspondent_bank_address: string, optional
Correspondent bank full address
correspondent_bank_swift_code: string, optional
Correspondent bank SWIFT code
charge_bearer: string, optional
CREDITOR, DEBTOR or SHARED
priority: string, optional
NORMAL, URGENT or SYSTEM

Sample payment attributes

{
  "end_to_end_id": "#123123123",
  "customer_last_logged_at": "2018-11-21T13:48:40Z",
  "customer_ip_address": "10.0.0.1",
  "customer_ip_port": "3456",
  "customer_device_os": "iOS 11",
  "customer_user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36",
  "customer_latitude": "51.5074",
  "customer_longitude": "0.1278",
  "debtor_name": "Lewis Begum",
  "debtor_address": "Level 39, One Canada Square, Canary Wharf, London E14 5AB, UK",
  "debtor_street_name": "One Canada Square",
  "debtor_building_number": "One",
  "debtor_post_code": "E14 5AB",
  "debtor_town": "London",
  "debtor_region": "England",
  "debtor_country_code": "UK",
  "creditor_name": "George Clayton",
  "creditor_agent": "123456",
  "creditor_agent_name": "Treasury Devision",
  "creditor_address": "40 King Street West, Suite 2100, Toronto, Ontario M5H3C2, Canada",
  "creditor_street_name": "King Street West",
  "creditor_building_number": "40",
  "creditor_post_code": "M5H3C2",
  "creditor_town": "Toronto",
  "creditor_region": "Canada",
  "creditor_country_code": "CA",
  "amount": "199000.99",
  "currency_code": "USD",
  "description": "Stocks purchase",
  "purpose_code": "3456",
  "date": "2018-11-20",
  "time": "10:20:30",
  "debtor_account_number": "70872490",
  "creditor_account_number": "12345678",
  "creditor_bank_swift_code": "TDOMCATTTOR",
  "creditor_bank_name": "Toronto Dominion Bank",
  "creditor_bank_address": "1547 Merivale Road, Nepean, Ontario, K2G 4V3, Canada"
  "creditor_bank_street_name": "Merivale Road",
  "creditor_bank_building_number": "1547",
  "creditor_bank_post_code": "K2G 4V3",
  "creditor_bank_town": "Nepean",
  "creditor_bank_region": "Ontario",
  "creditor_bank_country_code": "CA",
  "correspondent_account_number": "026-009-593",
  "correspondent_bank_name": "Bank of America",
  "correspondent_bank_address": "New York",
  "correspondent_bank_swift_code": "BOFAUS3NXXX",
  "charge_bearer": "CREDITOR",
  "priority": "NORMAL"
}

General

API Reference

Overview

Integrations

Formats

Glossary

Quick Start

Create customer

Sample Request

Sample Response

Choose provider

Sample Request

Sample Response

Choose payment template

Sample Request

Sample Response

Initiate payment

Sample Request

Sample Response

Visit connect url

Salt Edge Connect

Embeding connect in your appication

Sample Request

Sample Response

Callbacks

Signature

Success

Failure

Notify

Interactive

Interactive redirect

Errors

Error attributes

Error codes

Sample response

Errors list

Pay with Connect

Parameters

Possible Errors

URL

Method

Sample request

Sample response

Pay with Direct API

Parameters

Possible Errors

URL

Method

Sample request

Sample response

OAuth

Parameters

Possible Errors

URL

Method

Sample request

Sample response

Authorize

Parameters

Possible Errors

URL

Method

Sample request

Sample response

Confirm

Parameters

Possible Errors

URL

Method

Sample request (interactive confirmation)

Sample request (interactive redirect)

Sample response

Cancel

Possible Errors

URL

Method

Sample request

Sample response

Providers

Attributes