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

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

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/

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

$ 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/payments/v1/providers

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

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.

3. Choose a 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:

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

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

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

From the response above, 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.

4. Initiate a payment

To initiate a payment in Salt Edge Connect, we need to execute a request to create payment using connect 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\", \
                \"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

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