Payments 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 Spectre 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

1. Create customer

Before we can create any connections using Spectre API, we need to create a Customer. A Customer in Spectre API is the end-user of your application.

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/v4/customers/

This request returns a response of the following structure:

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

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

$ export CUSTOMER_ID=111

See customers reference for Customer related API endpoints.

2. Choose a provider

First we need to choose provider that supports payments and has client provider keys. We need to execute a 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/v4/providers?supports_payments=true

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

{
  "data": [
    {
      "id": "1063518971",
      "code": "fake_client_xf",
      "name": "Fake Bank with Client Keys",
      "mode": "api",
      "status": "active",
      "automatic_fetch": false,
      "interactive": true,
      "instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\"\n",
      "home_url": "https://example.com",
      "customer_notified_on_sign_in": false,
      "login_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",
      "refresh_timeout": 15,
      "holder_info": [],
      "identification_mode": "client"
    },
    ...
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

We need to save the Provider code (in this case fake_client_xf), because we will use it later.

$ export PROVIDER_CODE=fake_client_xf

3. Choose a payment template

Each payments provider can support multiple ways of initiating a payment. Each of this method is called a payment_template. Each payment template has a number of fields.

To get the provider’s payment_templates and fields we need to execute the following 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/v4/providers/$PROVIDER_CODE/templates

The response will be a list of payment templates and payment fields:

{
  "data": [
    {
      "id": 488721099,
      "identifier": "sepa_instant_payment",
      "payment_type": "one_time",
      "description": "SEPA Instant",
      "provider_id": 1063518971,
      "created_at": "2018-07-02T11:53:11Z",
      "updated_at": "2018-07-02T11:53:11Z",
      "payment_fields": [
        {
          "id": 958761940,
          "payment_template_id": 488721099,
          "name": "iban_from",
          "localized_name": "IBAN from",
          "nature": "text",
          "position": 1,
          "checksummable": false,
          "english_name": "IBAN from",
          "extra": {},
          "optional": false,
          "created_at": "2018-07-02T11:53:11Z",
          "updated_at": "2018-07-02T11:53:11Z"
        },
        {
          "id": 958761941,
          "payment_template_id": 488721099,
          "name": "iban_to",
          "localized_name": "IBAN to",
          "nature": "text",
          "position": 2,
          "checksummable": false,
          "english_name": "IBAN to",
          "extra": {},
          "optional": false,
          "created_at": "2018-07-02T11:53:11Z",
          "updated_at": "2018-07-02T11:53:11Z"
        },
        {
          "id": 958761942,
          "payment_template_id": 488721099,
          "name": "amount",
          "localized_name": "Amount",
          "nature": "text",
          "position": 3,
          "checksummable": false,
          "english_name": "Amount",
          "extra": {},
          "optional": false,
          "created_at": "2018-07-02T11:53:11Z",
          "updated_at": "2018-07-02T11:53:11Z"
        },
        {
          "id": 958761943,
          "payment_template_id": 488721099,
          "name": "description",
          "localized_name": "Description",
          "nature": "text",
          "position": 4,
          "checksummable": false,
          "english_name": "Description",
          "extra": {},
          "optional": false,
          "created_at": "2018-07-02T11:53:11Z",
          "updated_at": "2018-07-02T11:53:11Z"
        },
        {
          "id": 958761944,
          "payment_template_id": 488721099,
          "name": "currency_code",
          "localized_name": "Currency",
          "nature": "select",
          "position": 5,
          "checksummable": false,
          "english_name": "Currency",
          "extra": {},
          "optional": false,
          "created_at": "2018-07-02T11:53:11Z",
          "updated_at": "2018-07-02T11:53:11Z"
        }
      ]
    }
  ]
}

From the response above, we can see that payment template sepa_instant_transfer requires the following fields (because each of them has optional flag set to false):

iban_from iban_to amount currency_code description

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

We need to save the payment template identifier (in this case sepa_instant_transfer), because we will use it later.

$ export PAYMENT_TEMPLATE=sepa_instant_transfer

4. Initiate a payment

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

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\", \
                \"country_code\": \"XF\", \
                \"provider_code\": \"$PROVIDER_CODE\", \
                \"payment_attributes\": { \
                  \"iban_to\": \"XF12345678123456781231\", \
                  \"iban_from\": \"XF123456789012345678\", \
                  \"currency_code\": \"EUR\", \
                  \"description\": \"One Pay for services\", \
                  \"amount\": \"100\" \
                }, \
                \"template_identifier\": \"$PAYMENT_TEMPLATE\", \
                \"payee_description\": \"Amazon\" \
              } \
            }" \
        https://www.saltedge.com/api/v4/payments/tokens

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

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

5. Visit connect_url

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

After that, we will see the consent window.

After confirming, it will try connect to the provider.

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 connection process to finish.