Data types

All of the responses returned by Payment Initiation API are in the JSON format. The description of the data types encoded in a JSON response is below.

boolean
true or false

a boolean value

date

a date in the YYYY-MM-DD format

datetime

a date in the ISO-8601 format

float

a value corresponding to a real number using the double-precision representation

integer

a value corresponding to a 64-bit unsigned integer number

object

a string representing a JSON object (please refer to the RFC 4627 for more information)

string

a UTF-8 compatible sequence of characters

Pagination

Most Payment Initiation API routes return lists of paginated objects instead of the whole amount. The data you receive is divided into smaller chunks of data called pages.

By default, when you request a list of paginated resources, you will get a next_id in the meta object response. The value of the next_id equals to the resource_id next page will start with.

If you wish to customize the number of items you get per page, you should send the per_page attribute ranging between 100 and 1000 items in the request, which shows how many items you will receive per page. If no per_page parameter is sent, 100 items will be received by default.

In order to get all the data, you should send an additional from_id parameter with the corresponding id, or use the next_page attribute to query the next page.

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?per_page=10

Sample Response

{
  "data": [
    {
      "id": "1",
      "identifier": "sepa_instant_payment",
      "description": "SEPA Instant",
      "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,
          "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"
        }
      ]
    },
    ...
  ],
  "meta": {
    "next_id":"11",
    "next_page":"/api/payments/v1/templates?from_id=11&per_page=10"
  }
}

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

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

Possible Errors

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 below) 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

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

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": "2018-12-05T10:15:53Z",
    "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

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 POST \
        -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": {} } }

Parameters

interactive_fields
object, required

the credentials object based on the provider’s interactive fields

Possible Errors

URL

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

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\": { \
                \"interactive_fields\": { \
                  \"confirmation_code\": \"123456\" \
                } \
              } \
            }" \
        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

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": "2018-11-25T09:15:53Z",
  "updated_at": "2018-11-30T09:15:53Z"
}

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

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

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": "2018-11-25T09:15:53Z",
      "updated_at": "2018-11-30T09:15:53Z"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

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

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

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

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

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

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

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

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

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,
      "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": "number",
      "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"
    }
  ]
}

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,
        "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"
      }
    ]
  }
}

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

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,
          "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"
        }
      ]
    }
  ],
  "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

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,
  "checksummable": false,
  "extra": {},
  "optional": false,
  "created_at": "2018-05-02T12:35:08Z",
  "updated_at": "2018-05-02T12:35:08Z"
}