Equals Corporate APIs v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Onboarding

Direct API Access

Consumer of the API (CLIENT) will need to generate a private/public RS256 key pair

ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Only the public key needs to be shared with Equals, while the private keys needs to be kept secure by the CLIENT. The private key will be used to sign JWT Authentication tokens (TOKEN). In return, the CLIENT will receive a Company ID that is a required parameter for the TOKEN.

As part of our security strategy, we also do IP whitelisting, so the CLIENT will need to share all the necessary IP addresses that the API will be called from.

OAuth2 API Access

If you would like to use our APIs to access the data of our customers, with their consent, you will need to get in touch with us by sending an email to openbanking@equalsmoney.com It's a manual on-boarding process, but to speed things up, please have the following information ready

Company Details

• Contact Email
• Company Name
• Company Registration Number
• Company Address - Street
• Company Address - City
• Company Address - Postcode
• Company Address - Country
• Technical Point of Contact - First Name
• Technical Point of Contact - Last Name
• Technical Point of Contact - Phone Number
• Type of Access - AISP and/or PISP
• National Competent Authority
• (OPTIONAL) eIDAS Certificate

OAuth2 Application Details - most of these will be displayed to the user when asking for consent

• Application Name
• Redirect URL
• Privacy Policy URL
• Terms of Service URL
• Client Website URL
• Logo URL
• Contact Email Address
• RS256 Public Key

Security

Direct API Access

CLIENT generates and signs the TOKEN on every API request they make, see below for a NodeJS example

const jwt = require('jsonwebtoken');

const privateKey = fs.readFileSync('private.key');

const token = jwt.sign({ companyId: '1234', iss: 'Company Name', iat: 1578649824 }, privateKey, { algorithm: 'RS256' });

The TOKEN MUST be passed in the Authorization header as Bearer jwt_token_here

The TOKEN MUST have these properties:

• companyId - ID of the CLIENT Company (will be shared with the CLIENT when onboarding)
• iss - the name of the issuer, freeform text. This is so we can easily identify the CLIENT in our logs.
• iat - the time the token was issued, in seconds.

The TOKEN MUST be signed using the RS256 algorithm

Each token will be valid for only 30 seconds after it was created. In practice, this means that each individual API request will most likely need a fresh token.

A request without a proper Authorization header or an invalid one will return a 403 HTTP status code

OAuth2 Authorization Code Flow

The authorization code flow begins with the client directing the user to the /auth endpoint. In this request, the client requests the offline and accounts access. Without offline, the resulting response would not contain the refresh_token

https://oauth.fairfx.io/oauth2/auth?
client_id=f0d39020-6793-4d8c-8b40-498f9cb62adb&
response_type=code&
state=1234567890&
scope=offline+accounts

At this point, the user will be asked to enter their credentials and complete the authentication. After that, we will ask the user to consent to the required permissions.

Once the user authenticates and grants consent, we will return a response to your app at the indicated redirect_uri.

Now that you've acquired an authorization_code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. Do this by sending a POST request to the /token endpoint:

POST /oauth2/auth HTTP/1.1
Host: https://oauth.fairfx.io
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code={AUTHORIZATION_CODE}&
redirect_uri={REDIRECT_URI}&
client_id={CLIENT_ID}&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={CLIENT_ASSERTION}

For client_assertion see https://tools.ietf.org/html/rfc7523#section-2.2

After a successful request, you should now get an access_token and a refresh_token that you can use to make API calls and get back the data of the consenting user.

Base URLs:

• https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp

Email: Support License: UNLICENCED

Authentication

• HTTP Authentication, scheme: bearer

Accounts

Get Accounts

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /accounts

Get Accounts

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Account": [
      {
        "AccountId": "123",
        "Currency": "EUR",
        "AccountType": "Business",
        "AccountSubType": "PrePaidCard",
        "Description": "Euro card",
        "Account": {
          "SchemeName": [
            "UK.OBIE.BBAN",
            "UK.OBIE.IBAN",
            "UK.OBIE.PAN",
            "UK.OBIE.Paym",
            "UK.OBIE.SortCodeAccountNumber"
          ],
          "Identification": "1222333344441113",
          "Name": "John Johnson",
          "SecondaryIdentification": "1234"
        }
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Get Single Account

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId} HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /accounts/{accountId}

Get Single Account

Parameters

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Account": [
      {
        "AccountId": "123",
        "Currency": "EUR",
        "AccountType": "Business",
        "AccountSubType": "PrePaidCard",
        "Description": "Euro card",
        "Account": {
          "SchemeName": [
            "UK.OBIE.BBAN",
            "UK.OBIE.IBAN",
            "UK.OBIE.PAN",
            "UK.OBIE.Paym",
            "UK.OBIE.SortCodeAccountNumber"
          ],
          "Identification": "1222333344441113",
          "Name": "John Johnson",
          "SecondaryIdentification": "1234"
        }
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Balances

Get Balances

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/balances \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/balances HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/balances',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/balances',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /balances

Get Balances

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Balance": [
      {
        "AccountId": "123",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "ClosingAvailable",
        "DateTime": "2020-10-23T10:23:54Z"
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Get Account Balances

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/balances \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/balances HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/balances',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/balances',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /accounts/{accountId}/balances

Get Account Balances

Parameters

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Balance": [
      {
        "AccountId": "123",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "ClosingAvailable",
        "DateTime": "2020-10-23T10:23:54Z"
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Transactions

Get Transactions

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/transactions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/transactions HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/transactions',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/transactions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /transactions

Get Transactions

Parameters

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Transaction": [
      {
        "TransactionId": "784527",
        "AccountId": "123",
        "CreditDebitIndicator": "Credit",
        "Status": "Booked",
        "BookingDateTime": "2020-10-23T10:23:54Z",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "MerchantDetails": {
          "MerchantName": "Paypal",
          "MerchantCategoryCode": "5932"
        },
        "TransactionInformation": "UNQD497",
        "SupplementaryData": {
          "MerchantId": "Merchant1",
          "MerchantCity": "London",
          "OrderPurpose": "Travel Expenses"
        }
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Get Account Transactions

Code samples

# You can also use wget
curl -X GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/transactions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/transactions HTTP/1.1
Host: api.fairfx.io
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/transactions',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.fairfx.io/open-banking/jwt-proxy/corporate/v3.1/aisp/accounts/{accountId}/transactions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /accounts/{accountId}/transactions

Get Account Transactions

Parameters

Example responses

200 Response

{
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
    "LastAvailableDateTime": "2020-10-23T10:23:54Z"
  },
  "Data": {
    "Transaction": [
      {
        "TransactionId": "784527",
        "AccountId": "123",
        "CreditDebitIndicator": "Credit",
        "Status": "Booked",
        "BookingDateTime": "2020-10-23T10:23:54Z",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "MerchantDetails": {
          "MerchantName": "Paypal",
          "MerchantCategoryCode": "5932"
        },
        "TransactionInformation": "UNQD497",
        "SupplementaryData": {
          "MerchantId": "Merchant1",
          "MerchantCity": "London",
          "OrderPurpose": "Travel Expenses"
        }
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Schemas

Error

{
  "error": {
    "title": "string"
  }
}

Properties

Errors

{
  "errors": [
    {
      "error": {
        "title": "string"
      }
    }
  ]
}

Properties

ISODateTime

"2020-10-23T10:23:54Z"

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00

Properties

Meta

{
  "TotalPages": 1,
  "FirstAvailableDateTime": "2020-10-23T10:23:54Z",
  "LastAvailableDateTime": "2020-10-23T10:23:54Z"
}

MetaData

Properties

AccountsResponse

{
  "AccountId": "123",
  "Currency": "EUR",
  "AccountType": "Business",
  "AccountSubType": "PrePaidCard",
  "Description": "Euro card",
  "Account": {
    "SchemeName": [
      "UK.OBIE.BBAN",
      "UK.OBIE.IBAN",
      "UK.OBIE.PAN",
      "UK.OBIE.Paym",
      "UK.OBIE.SortCodeAccountNumber"
    ],
    "Identification": "1222333344441113",
    "Name": "John Johnson",
    "SecondaryIdentification": "1234"
  }
}

Properties

TransactionsResponse

{
  "TransactionId": "784527",
  "AccountId": "123",
  "CreditDebitIndicator": "Credit",
  "Status": "Booked",
  "BookingDateTime": "2020-10-23T10:23:54Z",
  "Amount": {
    "Amount": "1230.00",
    "Currency": "GBP"
  },
  "MerchantDetails": {
    "MerchantName": "Paypal",
    "MerchantCategoryCode": "5932"
  },
  "TransactionInformation": "UNQD497",
  "SupplementaryData": {
    "MerchantId": "Merchant1",
    "MerchantCity": "London",
    "OrderPurpose": "Travel Expenses"
  }
}

Properties

Enumerated Values

BalancesResponse

{
  "AccountId": "123",
  "Amount": {
    "Amount": "1230.00",
    "Currency": "GBP"
  },
  "CreditDebitIndicator": "Credit",
  "Type": "ClosingAvailable",
  "DateTime": "2020-10-23T10:23:54Z"
}

Properties

Enumerated Values