Enable Banking API

This API, formerly known as Tilisy API, provides the possibility to initiate end-user (aka PSU) authentication and access account information in a large number of banks and similar institutions (aka ASPSPs).

API flow diagram

1. Application makes a call to /aspsps endpoint to obtain a list of available ASPSPs along with necessary meta data.
2. List of available ASPSPs is returned and displayed to a PSU.
3. The PSU selects desired ASPSP and an application makes a call to /auth endpoint, specifying desired ASPSP and providing information about needed access rights.
4. Enable Banking starts authorization in a desired ASPSP.
5. Enable Banking responds to the client with a redirect url to a Enable Banking page, where PSU needs to be redirected.
6. The PSU is redirected to the Enable Banking page.
7. After the PSU is redirected, Enable Banking does interactions with an ASPSP necessary to get authorized access to the PSU's account. These actions are bank-specific and may be different for every bank and for every authentication method (which may be specified at step 1).
8. The PSU is rediected back to the client's website with additional parameters added in a http query string.
9. If the authorization went successfully then query string from step 8 will contain code parameter, which needs to be sent in the POST request to /sessions.
10. The Enable Banking API will respond with created session_id along with a list of accessible accounts.
    Note that some of the information returned in that call is shown only once.
    After successfull response from the POST /sessions the Client can start making calls to the Enable Banking API to fetch information about session, account balances and transactions.

Possible query parameters returned in the step 7 (parameters follow The OAuth 2.0 Authorization Framework):

1. code — authorization code.
2. state — same as state, provided in the step 1.
3. error — error code
4. error_description — human-readable error description

Possible error descriptions:

• Denied data sharing consent — user cancelled authentication before accepting data sharing consent (error code is access_denied)
• Cancelled by user — user cancelled authentication (error code is access_denied)
  There are also arbitrary error descriptions possible, which are coming from ASPSPs

API reference

Scroll down for code samples, example requests and responses.

Base URLs:

• https://api.enablebanking.com

• https://api.tilisy.com (deprecated)

Authentication

In order to get access to this API you need to:

• Generate a private RSA key and a self-signed certificate;
• Upload the certificate to enablebanking.com and get application ID;
• Construct JWT with the data described below and signed with your private key;
• Send the JWT in the Authorization header.

Private key and certificate generation

Generating private RSA key

openssl genrsa -out private.key 4096

OpenSSL CLI can be used for generation of a private key and self-signed certificate.

Make sure you keep the private key in secret (e.g. don't expose it to client, share with anyone nor embed into mobile or other apps intalled to user devices).

Generating self-signed certificate

openssl req -new -x509 -days 365 -key private.key -out public.crt -subj "/C=FI/ST=Uusima/L=Helsinki/O=ExampleOrganisation/CN=www.bigorg.com"

You should replace values under -subj with appropriate values.

Alternatively you can use the private key generated in your browser when registering a new application. Just choose Generate in the browser (using SubtleCrypto) and export private key option when registering an application, and the private key will be exported after the application has been registered (the corresponding certificate will be used for the app registration).

Certificate upload and application registration

In order to register a new application you need to have an account on enablebanking.com website. You can create one by going to https://enablebanking.com/sign-in/ and entering your email address (one-time authentication link will be sent to your email address).

In the app registration form (https://enablebanking.com/cp/applications) you will be asked to upload public certificate that you created for the application being registered.

An application can be registered to either PRODUCTION (aka "live") or SANDBOX (aka "simulation") environment. Applications can not be transferred from the sandbox to the production environment and vice-versa.

Applications registered into the sandbox environment are activated automatically, while applications registered to the production environment at first appear as pending and will be either activated automatically when a first account is linked or manually when contractual formalities for the use of the API are cleared. For more information please contact us at info@enablebanking.com.

App registration

curl -X POST -H "Authorization: Bearer YOUR-JWT-ON-ENABLEBANKING-COM" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"My app\",\"certificate\":\"$(cat public.crt | tr '\n' '|' | sed 's/|/\\n/g')\",\"environment\":\"SANDBOX\",\"redirect_urls\":[\"https://example.org/\"]}" \
  https://enablebanking.com/api/applications

You can also register an application sending POST request containing JSON with the application details and public certificate to https://enablebanking.com/api/applications endpoint.

After the registration is complete, you would receive application id to be used when forming JTW token.

JWT format and signature

JWT example

eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJSUzI1NiIsICJraWQiOiAiY2Y1ODliZTMtMzc1NS00NjViLWE4ZGYtYTkwYTE2YTMxNDAzIn0.eyJpc3MiOiAiZW5hYmxlYmFua2luZy5jb20iLCAiYXVkIjogImFwaS50aWxpc3kuY29tIiwgImlhdCI6IDE2MDE0NTY3NjgsICJleHAiOiAxNjAxNTQzMTY4fQ.daO3ENSYIA3ud7Ay7uGQ0xxqq9r4_WLcM5SbrN_6_fqsFZXFdoGQA5nKiyP8Ot4nWdYcZvaNWxEAOIodUFndOP8pjihF9-rMXuNGEjde1cq2WjYzKwiIeodUej8okDWdB--szcgurzGMd8RRMjqr951PWqnXS-PbrRsavDHp8l2q4YBjh2m80nRruKnQCAn0dtm4A5G9rZaEowo9z-c8HJU101jKddyOpHhl9UvxVrERzHtyO4LdidiP4rP1hmaVMWybSbcIMI_h30qjqWP21kYRH9ENITTttbf0uZIa8s74jKYxNIdiiDyRaq9WjoPolrHI_ZxcMjp8mmCKX-N-1w

You can read more about JWT here: https://jwt.io/introduction/

JWT header must contain following fields:

• "typ": "JWT" (always the same)
• "alg": "RS256" (always the same, only RS256 is supported)
• "kid": "<application_id>" (application id obtained after certificate upload)

JWT body must contain following fields:

• "iss": "enablebanking.com" (always the same)
• "aud": "api.enablebanking.com" (always the same, formerly had to be "api.tilisy.com", which is now depricated)
• "iat": 1601456603 (timestamp when the token is being created)
• "exp": 1601460262 (timestamp when the token expires)

Maximum allowed time-to-live for token is 86400 seconds (24 hours). Tokens created with longer TTL are not accepted by the API.

Check code samples in C#, Node.js, PHP, Python and Ruby in our Github repository

https://github.com/enablebanking/enablebanking-api-samples

Send request with JWT provided

Example request

GET https://api.enablebanking.com/application HTTP/1.1
Host: api.enablebanking.com
Authorization: Bearer eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJSUzI1NiIsICJraWQiOiAiY2Y1ODliZTMtMzc1NS00NjViLWE4ZGYtYTkwYTE2YTMxNDAzIn0.eyJpc3MiOiAiZW5hYmxlYmFua2luZy5jb20iLCAiYXVkIjogImFwaS5lbmFibGViYW5raW5nLmNvbSIsICJpYXQiOiAxNjAxNDU2NzY4LCAiZXhwIjogMTYwMTU0MzE2OH0.daO3ENSYIA3ud7Ay7uGQ0xxqq9r4_WLcM5SbrN_6_fqsFZXFdoGQA5nKiyP8Ot4nWdYcZvaNWxEAOIodUFndOP8pjihF9-rMXuNGEjde1cq2WjYzKwiIeodUej8okDWdB--szcgurzGMd8RRMjqr951PWqnXS-PbrRsavDHp8l2q4YBjh2m80nRruKnQCAn0dtm4A5G9rZaEowo9z-c8HJU101jKddyOpHhl9UvxVrERzHtyO4LdidiP4rP1hmaVMWybSbcIMI_h30qjqWP21kYRH9ENITTttbf0uZIa8s74jKYxNIdiiDyRaq9WjoPolrHI_ZxcMjp8mmCKX-N-1w

In order to authenticate your application, you need to provide JWT in the "Authorization" header of your request.

User sessions

Start user authorization

Code samples

POST https://api.enablebanking.com/auth HTTP/1.1
Host: api.enablebanking.com
Content-Type: application/json
Accept: application/json

POST /auth

Start authorization by getting a redirect link and redirecting a PSU to that link

Body parameter

{
  "access": {
    "valid_until": "2020-12-01T12:00:00.000000+00:00"
  },
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "state": "3a57e2d3-2e0c-4336-af9b-7fa94f0606a3",
  "redirect_url": "http://example.com",
  "psu_type": "business",
  "auth_method": "methodName",
  "credentials": {
    "userId": "MyUsername"
  },
  "credentials_autosubmit": true,
  "language": "fi",
  "psu_id": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	StartAuthorizationRequest	true	none

Example responses

200 Response

{
  "url": "https://tilisy.enablebanking.com/welcome?sessionid=73100c65-c54d-46a1-87d1-aa3effde435a",
  "authorization_id": "73100c65-c54d-46a1-87d1-aa3effde435a",
  "psu_id_hash": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	StartAuthorizationResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Authorize user session

Code samples

POST https://api.enablebanking.com/sessions HTTP/1.1
Host: api.enablebanking.com
Content-Type: application/json
Accept: application/json

POST /sessions

Authorize user session by provided authorization code

Body parameter

{
  "code": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	AuthorizeSessionRequest	true	none

Example responses

200 Response

{
  "session_id": "string",
  "accounts": [
    {
      "account_id": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "all_account_ids": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "account_servicer": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "name": "string",
      "details": "string",
      "linked_account": "string",
      "usage": "PRIV",
      "cash_account_type": "CACC",
      "product": "string",
      "currency": "string",
      "psu_status": "string",
      "credit_limit": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc="
    }
  ],
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "psu_type": "business",
  "access": {
    "valid_until": "2021-01-01T00:00:00Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	AuthorizeSessionResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Get session data

Code samples

GET https://api.enablebanking.com/sessions/{session_id} HTTP/1.1
Host: api.enablebanking.com
Accept: application/json

GET /sessions/{session_id}

Get session data by session id

Parameters

Name	In	Type	Required	Description
session_id	path	string(uuid)	true	Previously authorized session id

Example responses

200 Response

{
  "access": {
    "valid_until": "2020-12-01T12:00:00.000000+00:00"
  },
  "accounts": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accounts_data": [
    {
      "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc=",
      "uid": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "aspsp": {
    "country": "FI",
    "name": "Nordea"
  },
  "authorized": "2020-12-01T12:00:00.000000+00:00",
  "created": "2020-12-01T12:00:00.000000+00:00",
  "psu_type": "business",
  "status": "AUTHORIZED"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	GetSessionResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Delete session

Code samples

DELETE https://api.enablebanking.com/sessions/{session_id} HTTP/1.1
Host: api.enablebanking.com
Accept: application/json
Psu-Ip-Address: string
Psu-User-Agent: string
Psu-Referer: string
Psu-Accept: string
Psu-Accept-Charset: string
Psu-Accept-Encoding: string
Psu-Accept-language: string
Psu-Geo-Location: -1.2345,6.789

DELETE /sessions/{session_id}

Delete session by session id. PSU's bank consent will be closed automatically if possible

Parameters

Name	In	Type	Required	Description
session_id	path	string(uuid)	true	Previously authorized session id
Psu-Ip-Address	header	string	false	PSU IP address
Psu-User-Agent	header	string	false	PSU browser User Agent
Psu-Referer	header	string	false	PSU Referer
Psu-Accept	header	string	false	PSU accept header
Psu-Accept-Charset	header	string	false	PSU charset
Psu-Accept-Encoding	header	string	false	PSU accept encoding
Psu-Accept-language	header	string	false	PSU accept language
Psu-Geo-Location	header	string	false	Comma separated latitude and longitude coordinates without spaces

Example responses

200 Response

{
  "message": "OK"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	SuccessResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Accounts data

Get account details

Code samples

GET https://api.enablebanking.com/accounts/{account_id}/details HTTP/1.1
Host: api.enablebanking.com
Accept: application/json
Psu-Ip-Address: string
Psu-User-Agent: string
Psu-Referer: string
Psu-Accept: string
Psu-Accept-Charset: string
Psu-Accept-Encoding: string
Psu-Accept-language: string
Psu-Geo-Location: -1.2345,6.789

GET /accounts/{account_id}/details

Fetching account details from ASPSP for an account by its ID

Parameters

Name	In	Type	Required	Description
account_id	path	string(uuid)	true	Account id
Psu-Ip-Address	header	string	false	PSU IP address
Psu-User-Agent	header	string	false	PSU browser User Agent
Psu-Referer	header	string	false	PSU Referer
Psu-Accept	header	string	false	PSU accept header
Psu-Accept-Charset	header	string	false	PSU charset
Psu-Accept-Encoding	header	string	false	PSU accept encoding
Psu-Accept-language	header	string	false	PSU accept language
Psu-Geo-Location	header	string	false	Comma separated latitude and longitude coordinates without spaces

Example responses

200 Response

{
  "account_id": {
    "iban": "FI8821291587733472",
    "other": {
      "identification": "123456",
      "scheme_name": "BBAN"
    }
  },
  "all_account_ids": [
    {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  ],
  "account_servicer": {
    "bic_fi": "string",
    "clearing_system_member_id": {
      "clearing_system_id": "NZNCC",
      "member_id": "020368"
    },
    "name": "string"
  },
  "name": "string",
  "details": "string",
  "linked_account": "string",
  "usage": "PRIV",
  "cash_account_type": "CACC",
  "product": "string",
  "currency": "string",
  "psu_status": "string",
  "credit_limit": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
  "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc="
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	AccountResource
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Get account balances

Code samples

GET https://api.enablebanking.com/accounts/{account_id}/balances HTTP/1.1
Host: api.enablebanking.com
Accept: application/json
Psu-Ip-Address: string
Psu-User-Agent: string
Psu-Referer: string
Psu-Accept: string
Psu-Accept-Charset: string
Psu-Accept-Encoding: string
Psu-Accept-language: string
Psu-Geo-Location: -1.2345,6.789

GET /accounts/{account_id}/balances

Fetching account balances from ASPSP for an account by its ID

Parameters

Name	In	Type	Required	Description
account_id	path	string(uuid)	true	PSU account ID accessible in the provided session
Psu-Ip-Address	header	string	false	PSU IP address
Psu-User-Agent	header	string	false	PSU browser User Agent
Psu-Referer	header	string	false	PSU Referer
Psu-Accept	header	string	false	PSU accept header
Psu-Accept-Charset	header	string	false	PSU charset
Psu-Accept-Encoding	header	string	false	PSU accept encoding
Psu-Accept-language	header	string	false	PSU accept language
Psu-Geo-Location	header	string	false	Comma separated latitude and longitude coordinates without spaces

Example responses

200 Response

{
  "balances": [
    {
      "name": "Booked balance",
      "balance_amount": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "balance_type": "(ISO20022 ClosingBooked) Accounting Balance",
      "last_change_date_time": "2019-08-24T14:15:22Z",
      "reference_date": "2019-08-24",
      "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	HalBalances
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Get account transactions

Code samples

GET https://api.enablebanking.com/accounts/{account_id}/transactions HTTP/1.1
Host: api.enablebanking.com
Accept: application/json
Psu-Ip-Address: string
Psu-User-Agent: string
Psu-Referer: string
Psu-Accept: string
Psu-Accept-Charset: string
Psu-Accept-Encoding: string
Psu-Accept-language: string
Psu-Geo-Location: -1.2345,6.789

GET /accounts/{account_id}/transactions

Fetching account transactions from ASPSP for an account by its ID

Parameters

Name	In	Type	Required	Description
account_id	path	string(uuid)	true	PSU account ID accessible in the provided session
date_from	query	string(date)	false	Date to fetch transactions from (including the date, UTC timezone is assumed)
date_to	query	string(date)	false	Date to fetch transactions to (including the date, UTC timezone is assumed)
continuation_key	query	string	false	Key, allowing iterate over multiple API pages of transactions
transaction_status	query	TransactionStatus	false	Filter transactions by provided status
Psu-Ip-Address	header	string	false	PSU IP address
Psu-User-Agent	header	string	false	PSU browser User Agent
Psu-Referer	header	string	false	PSU Referer
Psu-Accept	header	string	false	PSU accept header
Psu-Accept-Charset	header	string	false	PSU charset
Psu-Accept-Encoding	header	string	false	PSU accept encoding
Psu-Accept-language	header	string	false	PSU accept language
Psu-Geo-Location	header	string	false	Comma separated latitude and longitude coordinates without spaces

Example responses

200 Response

{
  "transactions": [
    {
      "entry_reference": "5561990681",
      "merchant_category_code": "5511",
      "transaction_amount": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "creditor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_number": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": [
            "Mr Asko Teirila PO Box 511",
            "39140 AKDENMAA FINLAND"
          ]
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "creditor_account": {
        "iban": "FI1737631867613465"
      },
      "creditor_agent": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "debtor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_number": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": [
            "Mr Asko Teirila PO Box 511",
            "39140 AKDENMAA FINLAND"
          ]
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "debtor_account": {
        "iban": "FI8638798819867751"
      },
      "debtor_agent": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "bank_transaction_code": {
        "description": "Utlandsbetalning",
        "code": "12",
        "sub_code": "32"
      },
      "credit_debit_indicator": "CRDT",
      "status": "BOOK",
      "booking_date": "2020-01-01",
      "value_date": "2020-01-01",
      "transaction_date": "2020-01-01",
      "balance_after_transaction": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "reference_number": "RF07850352502356628678117",
      "remittance_information": [
        "RF07850352502356628678117",
        "Gift for Alex"
      ],
      "debtor_account_additional_identification": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "creditor_account_additional_identification": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "exchange_rate": {
        "unit_currency": {
          "iban": "FI8821291587733472",
          "other": {
            "identification": "123456",
            "scheme_name": "BBAN"
          }
        },
        "exchange_rate": "string",
        "rate_type": "SPOT",
        "contract_identification": "string",
        "instructed_amount": {
          "currency": "EUR",
          "amount": "1.23"
        }
      },
      "note": "string"
    }
  ],
  "continuation_key": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	HalTransactions
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Misc

Get list of ASPSPs

Code samples

GET https://api.enablebanking.com/aspsps HTTP/1.1
Host: api.enablebanking.com
Accept: application/json

GET /aspsps

Get list of ASPSPs with their meta information

Parameters

Name	In	Type	Required	Description
country	query	string	false	Display only ASPSPs from specified country
psu_type	query	PSUType	false	Display only ASPSPs which support specified psu type

Example responses

200 Response

{
  "aspsps": [
    {
      "name": "Nordea",
      "country": "FI",
      "logo": "https://enablebanking.com/brands/FI/Nordea/",
      "psu_types": [
        "personal",
        "business"
      ],
      "auth_methods": [
        {
          "name": "string",
          "title": "string",
          "psu_type": "business",
          "credentials": [
            {
              "name": "userId",
              "title": "User ID",
              "required": true,
              "description": "Your identifier used for logging in to online banking",
              "template": "^\\d{8}$"
            }
          ],
          "approach": "REDIRECT",
          "hidden_method": true
        }
      ],
      "sandbox": {
        "users": [
          {
            "username": "MyUsername",
            "password": "MySecretPassowrd",
            "otp": "123456"
          }
        ]
      },
      "beta": true,
      "bic": "string",
      "required_psu_headers": [
        "string"
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	GetAspspsResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Get application

Code samples

GET https://api.enablebanking.com/application HTTP/1.1
Host: api.enablebanking.com
Accept: application/json

GET /application

Get application associated with provided JWT key id

Example responses

200 Response

{
  "name": "string",
  "description": "string",
  "kid": "string",
  "environment": "SANDBOX",
  "redirect_urls": [
    "http://example.com"
  ],
  "active": true,
  "countries": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	GetApplicationResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	ErrorResponse
408	Request Timeout	Request Timeout	ErrorResponse
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Schemas

ASPSP

{
  "name": "Nordea",
  "country": "FI"
}

Properties

Name	Type	Required	Description
name	string	true	ASPSP name
country	string	true	Two-letter ASPSP country code

ASPSPData

{
  "name": "Nordea",
  "country": "FI",
  "logo": "https://enablebanking.com/brands/FI/Nordea/",
  "psu_types": [
    "personal",
    "business"
  ],
  "auth_methods": [
    {
      "name": "string",
      "title": "string",
      "psu_type": "business",
      "credentials": [
        {
          "name": "userId",
          "title": "User ID",
          "required": true,
          "description": "Your identifier used for logging in to online banking",
          "template": "^\\d{8}$"
        }
      ],
      "approach": "REDIRECT",
      "hidden_method": true
    }
  ],
  "sandbox": {
    "users": [
      {
        "username": "MyUsername",
        "password": "MySecretPassowrd",
        "otp": "123456"
      }
    ]
  },
  "beta": true,
  "bic": "string",
  "required_psu_headers": [
    "string"
  ]
}

Properties

Name	Type	Required	Description
name	string	true	ASPSP name
country	string	true	Two-letter ASPSP country code
logo	string(uri)	true	ASPSP logo URL. It is possible to transform (e.g. resize) the logo by adding special suffixes at the end of the URL. For example, -/resize/500x/. For full list of possible transformations, please refer to https://uploadcare.com/docs/transformations/image_transformations/
psu_types	[PSUType]	true	List of PSU types supported by ASPSP
auth_methods	[AuthMethod]	true	List of available authentication methods. Provided in case multiple methods are available or it is possible to supply authentication credentials while initiating authorization.
sandbox	SandboxInfo	false	Applicable only to sandbox environment. Additional information necessary to use sandbox environment.
beta	boolean	true	Flag showing whether implementation is in beta mode
bic	string	false	BIC of the ASPSP
required_psu_headers	[string]	false	List of required PSU headers

Access

{
  "accounts": [
    {
      "iban": "FI8821291587733472",
      "other": {
        "identification": "123456",
        "scheme_name": "BBAN"
      }
    }
  ],
  "balances": true,
  "transactions": true,
  "valid_until": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Description
accounts	[AccountIdentification]	false	List of accounts access to which is requested. If not set behaviour depends on the bank: some banks allow users to choose list of accessible accounts through their access consent UI, while other may provide access to all accounts or just access to the list of accounts.
balances	boolean	false	Request consent with balances access
transactions	boolean	false	Request consent with transactions access
valid_until	string(date-time)	true	This parameter is requesting a valid until date for the requested consent. The value shall be in RFC3339 date and time format with timezone specified, e.g. 2020-12-01T12:00:00.000000+00:00. The value might get adjusted to fullfil ASPSP requirements.

AccountIdentification

{
  "iban": "FI8821291587733472",
  "other": {
    "identification": "123456",
    "scheme_name": "BBAN"
  }
}

Properties

Name	Type	Required	Description
iban	string	false	International Bank Account Number (IBAN) - identification used internationally by financial institutions to uniquely identify the account of a customer. Further specifications of the format and content of the IBAN can be found in the standard ISO 13616 "Banking and related financial services - International Bank Account Number (IBAN)" version 1997-10-01, or later revisions.
other	GenericIdentification	false	Other identification if iban is not provided

AccountResource

{
  "account_id": {
    "iban": "FI8821291587733472",
    "other": {
      "identification": "123456",
      "scheme_name": "BBAN"
    }
  },
  "all_account_ids": [
    {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  ],
  "account_servicer": {
    "bic_fi": "string",
    "clearing_system_member_id": {
      "clearing_system_id": "NZNCC",
      "member_id": "020368"
    },
    "name": "string"
  },
  "name": "string",
  "details": "string",
  "linked_account": "string",
  "usage": "PRIV",
  "cash_account_type": "CACC",
  "product": "string",
  "currency": "string",
  "psu_status": "string",
  "credit_limit": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
  "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc="
}

Properties

Name	Type	Required	Description
account_id	AccountIdentification	false	none
all_account_ids	[GenericIdentification]	false	All account identifiers provided by ASPSPs (including primary identifier available in the accountId field)
account_servicer	FinancialInstitutionIdentification	false	Information about the financial institution servicing the account
name	string	false	Account holder(s) name
details	string	false	Account description set by PSU or provided by ASPSP
linked_account	string	false	Case of a set of pending card transactions, the APSP will provide the relevant cash account the card is set up on.
usage	Usage	false	Specifies the usage of the account
cash_account_type	CashAccountType	true	Specifies the type of the account
product	string	false	Product Name of the Bank for this account, proprietary definition
currency	string	true	none
psu_status	string	false	Relationship between the PSU and the account - Account Holder - Co-account Holder - Attorney
credit_limit	AmountType	false	Specifies credit limit of the account
uid	string(uuid)	false	Unique account identificator used for fetching account balances and transactions. It is valid only until the session to which the account belongs is in the AUTHORIZED status. It can be not set in case it is know that it is not possible to fetch balances and transactions for the account (for example, in case the account is blocked or closed at the ASPSP side).
identification_hash	string	true	Account identification hash. It can be used for matching accounts between multiple sessions (even in case the sessions are authorized by different PSUs).

AddressType

"Business"

Enumerated Values

Value	Description
Business	Business
Correspondence	Correspondence
DeliveryTo	DeliveryTo
MailTo	MailTo
POBox	POBox
Postal	Postal
Residential	Residential
Statement	Statement

AmountType

{
  "currency": "EUR",
  "amount": "1.23"
}

Properties

Name	Type	Required	Description
currency	string	true	Currency code of the amount
amount	string	true	Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

AuthMethod

{
  "name": "string",
  "title": "string",
  "psu_type": "business",
  "credentials": [
    {
      "name": "userId",
      "title": "User ID",
      "required": true,
      "description": "Your identifier used for logging in to online banking",
      "template": "^\\d{8}$"
    }
  ],
  "approach": "REDIRECT",
  "hidden_method": true
}

Properties

Name	Type	Required	Description
name	string	false	Internal name of the authentication method
title	string	false	Human-readable title of the authentication method
psu_type	PSUType	true	PSU type to which the authentication method is applicable
credentials	[Credential]	true	List of credentials which are possible to supply while initiating authorization.
approach	AuthenticationApproach	true	Authentication approach used in the current authentication method
hidden_method	boolean	true	Flag showing whether the current authentication method is hidden from the user. If true then the user will not be able to select this authentication method. It is inly possible to select this authentication method via API.

AuthenticationApproach

"REDIRECT"

Enumerated Values

Value	Description
REDIRECT	REDIRECT
DECOUPLED	DECOUPLED
EMBEDDED	EMBEDDED

AuthorizeSessionRequest

{
  "code": "string"
}

Properties

Name	Type	Required	Description
code	string	true	Authorization code returned when redirecting PSU

AuthorizeSessionResponse

{
  "session_id": "string",
  "accounts": [
    {
      "account_id": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "all_account_ids": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "account_servicer": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "name": "string",
      "details": "string",
      "linked_account": "string",
      "usage": "PRIV",
      "cash_account_type": "CACC",
      "product": "string",
      "currency": "string",
      "psu_status": "string",
      "credit_limit": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc="
    }
  ],
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "psu_type": "business",
  "access": {
    "valid_until": "2021-01-01T00:00:00Z"
  }
}

Properties

Name	Type	Required	Description
session_id	string(uuid4)	true	ID of the PSU session
accounts	[AccountResource]	true	none
aspsp	ASPSP	true	ASPSP used with the session
psu_type	PSUType	true	PSU type used with the session
access	Access	true	Scope of access requested from ASPSP and confirmed by PSU

BalanceResource

{
  "name": "Booked balance",
  "balance_amount": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "balance_type": "(ISO20022 ClosingBooked) Accounting Balance",
  "last_change_date_time": "2019-08-24T14:15:22Z",
  "reference_date": "2019-08-24",
  "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a"
}

Properties

Name	Type	Required	Description
name	string	true	Label of the balance
balance_amount	AmountType	true	none
balance_type	BalanceStatus	true	Available balance type values
last_change_date_time	string(date-time)	false	Timestamp of the last change of the balance amount
reference_date	string(date)	false	Reference date for the balance
last_committed_transaction	string	false	Identification of the last committed transaction. This is actually useful for instant balance.

BalanceStatus

"CLAV"

Enumerated Values

Value	Description
CLAV	(ISO20022 Closing Available) Closing available balance
CLBD	(ISO20022 ClosingBooked) Accounting Balance
FWAV	(ISO20022 ForwardAvailable) Balance of money that is at the disposal of the account owner on the date specified
INFO	(ISO20022 Information) Balance for informational purposes
ITAV	(ISO20022 InterimAvailable) Available balance calculated in the course of the day
ITBD	(ISO20022 InterimBooked) Booked balance calculated in the course of the day
OPAV	(ISO20022 OpeningAvailable) Opening balance of amount of money that is at the disposal of the account owner on the date specified
OPBD	(ISO20022 OpeningBooked) Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report
PRCD	(ISO20022 PreviouslyClosedBooked) Balance of the account at the end of the previous reporting period
OTHR	Other Balance
VALU	Value-date balance
XPCD	(ISO20022 Expected) Instant Balance

BankTransactionCode

{
  "description": "Utlandsbetalning",
  "code": "12",
  "sub_code": "32"
}

Properties

Name	Type	Required	Description
description	string	true	Arbitrary transaction categorization description
code	string	false	Specifies the family of a transaction within the domain
sub_code	string	false	Specifies the sub-product family of a transaction within a specific family

CashAccountType

"CACC"

Enumerated Values

Value	Description
CACC	Account used to post debits and credits when no specific account has been nominated
CASH	Account used for the payment of cash
CARD	Account used for card payments only
LOAN	Account used for loans
SVGS	Account used for savings
OTHR	Account not otherwise specified

ClearingSystemMemberIdentification

{
  "clearing_system_id": "NZNCC",
  "member_id": "020368"
}

Properties

Name	Type	Required	Description
clearing_system_id	string	false	ISO20022: Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed.
member_id	string	false	ISO20022: Identification of a member of a clearing system.

Credential

{
  "name": "userId",
  "title": "User ID",
  "required": true,
  "description": "Your identifier used for logging in to online banking",
  "template": "^\\d{8}$"
}

Properties

Name	Type	Required	Description
name	string	true	Internal name of the credential. The name is to be used when passing credentials to the "start user authorization" request
title	string	true	Title for the credential to be displayed to PSU
required	boolean	true	Indication whether the credential is required
description	string	false	Description of the credential to be displayed to PSU
template	string	false	Perl compatible regular expression used for check of the credential format

CreditDebitIndicator

"CRDT"

Enumerated Values

Value	Description
CRDT	Credit type transaction
DBIT	Debit type transaction

Environment

"SANDBOX"

Enumerated Values

Value	Description
SANDBOX	SANDBOX
PRODUCTION	PRODUCTION

ErrorCode

"ACCESS_DENIED"

Enumerated Values

Value	Description
ACCESS_DENIED	Access to this resource is denied. Check you access scope.
ACCOUNT_DOES_NOT_EXIST	No account found matching provided id
ALREADY_AUTHORIZED	Session is already authorized
ASPSP_ERROR	Error interacting with ASPSP
ASPSP_TIMEOUT	Timeout interacting with ASPSP
ASPSP_RATE_LIMIT_EXCEEDED	ASPPS Rate limit exceeded
ASPSP_UNAUTHORIZED_ACCESS	PSU is unauthorized to interact with ASPSP
AUTHORIZATION_NOT_PROVIDED	Authorization header is not provided
CLOSED_SESSION	Session is closed
DATE_TO_WITHOUT_DATE_FROM	date_from must be provided if date_to provided
DATE_FROM_IN_FUTURE	date_from can not be in the future
EXPIRED_AUTHORIZATION_CODE	Authorization code is expired
EXPIRED_SESSION	Session is expired
INVALID_ACCOUNT_ID	Either iban or other account identification is required
INVALID_HOST	Invalid host
NO_ACCOUNTS_ADDED	No allowed accounts added to the application
PSU_HEADER_NOT_PROVIDED	Required PSU header not provided
REDIRECT_URI_NOT_ALLOWED	Redirect URI not allowed
REVOKED_SESSION	Session is revoked
SESSION_DOES_NOT_EXIST	No session found matching provided id
UNAUTHORIZED_ACCESS	Unauthorized access
WRONG_ASPSP_PROVIDED	Wrong ASPSP name provided
WRONG_AUTHORIZATION_CODE	Wrong authorization code provided
WRONG_DATE_INTERVAL	date_from should be less than or equal date_to
WRONG_CREDENTIALS_PROVIDED	Wrong credentuals provided
WRONG_REQUEST_PARAMETERS	Wrong request parameters provided
WRONG_SESSION_STATUS	Wrong session status
WRONG_TRANSACTIONS_PERIOD	Wrong transactions period requested

ErrorResponse

{
  "message": "Required PSU header not provided",
  "code": 422,
  "error": "PSU_HEADER_NOT_PROVIDED",
  "detail": "PSU header psuIpAddress is not provided"
}

Properties

Name	Type	Required	Description
message	string	true	Error message
code	integer	false	Error code, identical to the http response code
error	ErrorCode	false	Text error code
detail	any	false	Detailed explanation of an error

ExchangeRate

{
  "unit_currency": {
    "iban": "FI8821291587733472",
    "other": {
      "identification": "123456",
      "scheme_name": "BBAN"
    }
  },
  "exchange_rate": "string",
  "rate_type": "SPOT",
  "contract_identification": "string",
  "instructed_amount": {
    "currency": "EUR",
    "amount": "1.23"
  }
}

Properties

Name	Type	Required	Description
unit_currency	AccountIdentification	false	Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP.
exchange_rate	string	false	The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency.
rate_type	RateType	false	An enumeration.
contract_identification	string	false	Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent.
instructed_amount	AmountType	false	none

FinancialInstitutionIdentification

{
  "bic_fi": "string",
  "clearing_system_member_id": {
    "clearing_system_id": "NZNCC",
    "member_id": "020368"
  },
  "name": "string"
}

Properties

Name	Type	Required	Description
bic_fi	string	false	Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 "Banking - Banking telecommunication messages - Business identification code (BIC)".
clearing_system_member_id	ClearingSystemMemberIdentification	false	Information used to identify a member within a clearing system.
name	string	false	Name of the financial institution

GenericIdentification

{
  "identification": "12FR5",
  "scheme_name": "COID",
  "issuer": "FR"
}

Properties

Name	Type	Required	Description
identification	string	true	An identifier
scheme_name	SchemeName	true	Name of the identification scheme. Partially based on ISO20022 external code list
issuer	string	false	Entity that assigns the identification. this could a country code or any organisation name or identifier that can be recognized by both parties

GetApplicationResponse

{
  "name": "string",
  "description": "string",
  "kid": "string",
  "environment": "SANDBOX",
  "redirect_urls": [
    "http://example.com"
  ],
  "active": true,
  "countries": [
    "string"
  ]
}

Properties

Name	Type	Required	Description
name	string	true	Application name
description	string	false	Application description
kid	string(uuid4)	true	Application key id
environment	Environment	true	Application environment
redirect_urls	[string]	true	List of allowed redirect urls
active	boolean	true	Indication whether the application is active
countries	[string]	true	List of supported countries

GetAspspsResponse

{
  "aspsps": [
    {
      "name": "Nordea",
      "country": "FI",
      "logo": "https://enablebanking.com/brands/FI/Nordea/",
      "psu_types": [
        "personal",
        "business"
      ],
      "auth_methods": [
        {
          "name": "string",
          "title": "string",
          "psu_type": "business",
          "credentials": [
            {
              "name": "userId",
              "title": "User ID",
              "required": true,
              "description": "Your identifier used for logging in to online banking",
              "template": "^\\d{8}$"
            }
          ],
          "approach": "REDIRECT",
          "hidden_method": true
        }
      ],
      "sandbox": {
        "users": [
          {
            "username": "MyUsername",
            "password": "MySecretPassowrd",
            "otp": "123456"
          }
        ]
      },
      "beta": true,
      "bic": "string",
      "required_psu_headers": [
        "string"
      ]
    }
  ]
}

Properties

Name	Type	Required	Description
aspsps	[ASPSPData]	true	List of available ASPSPs and countries

GetSessionResponse

{
  "access": {
    "valid_until": "2020-12-01T12:00:00.000000+00:00"
  },
  "accounts": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accounts_data": [
    {
      "identification_hash": "WwpbCiJhY2NvdW50IiwKImFjY291bnRfaWQiLAoiaWJhbiIKXQpd.E8GzhnnsFC7K+4e3YMYYKpyM83Zx6toXrjgcvPP/Lqc=",
      "uid": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "aspsp": {
    "country": "FI",
    "name": "Nordea"
  },
  "authorized": "2020-12-01T12:00:00.000000+00:00",
  "created": "2020-12-01T12:00:00.000000+00:00",
  "psu_type": "business",
  "status": "AUTHORIZED"
}

Properties

Name	Type	Required	Description
status	SessionStatus	true	Session status
accounts	[string]	true	List of account ids available in the session
accounts_data	[SessionAccount]	true	Accounts data stored in the session
aspsp	ASPSP	true	ASPSP used with the session
psu_type	PSUType	true	PSU type used with the session
access	Access	true	Scope of access requested from ASPSP and confirmed by PSU
created	string(date-time)	true	Date and time when the session was created
authorized	string(date-time)	false	Date and time when the session was authorized
closed	string(date-time)	false	Date and time when the session was closed

HalBalances

{
  "balances": [
    {
      "name": "Booked balance",
      "balance_amount": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "balance_type": "(ISO20022 ClosingBooked) Accounting Balance",
      "last_change_date_time": "2019-08-24T14:15:22Z",
      "reference_date": "2019-08-24",
      "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a"
    }
  ]
}

Properties

Name	Type	Required	Description
balances	[BalanceResource]	true	List of account balances

HalTransactions

{
  "transactions": [
    {
      "entry_reference": "5561990681",
      "merchant_category_code": "5511",
      "transaction_amount": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "creditor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_number": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": [
            "Mr Asko Teirila PO Box 511",
            "39140 AKDENMAA FINLAND"
          ]
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "creditor_account": {
        "iban": "FI1737631867613465"
      },
      "creditor_agent": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "debtor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_number": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": [
            "Mr Asko Teirila PO Box 511",
            "39140 AKDENMAA FINLAND"
          ]
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "debtor_account": {
        "iban": "FI8638798819867751"
      },
      "debtor_agent": {
        "bic_fi": "string",
        "clearing_system_member_id": {
          "clearing_system_id": "NZNCC",
          "member_id": "020368"
        },
        "name": "string"
      },
      "bank_transaction_code": {
        "description": "Utlandsbetalning",
        "code": "12",
        "sub_code": "32"
      },
      "credit_debit_indicator": "CRDT",
      "status": "BOOK",
      "booking_date": "2020-01-01",
      "value_date": "2020-01-01",
      "transaction_date": "2020-01-01",
      "balance_after_transaction": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "reference_number": "RF07850352502356628678117",
      "remittance_information": [
        "RF07850352502356628678117",
        "Gift for Alex"
      ],
      "debtor_account_additional_identification": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "creditor_account_additional_identification": [
        {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      ],
      "exchange_rate": {
        "unit_currency": {
          "iban": "FI8821291587733472",
          "other": {
            "identification": "123456",
            "scheme_name": "BBAN"
          }
        },
        "exchange_rate": "string",
        "rate_type": "SPOT",
        "contract_identification": "string",
        "instructed_amount": {
          "currency": "EUR",
          "amount": "1.23"
        }
      },
      "note": "string"
    }
  ],
  "continuation_key": "string"
}

Properties

Name	Type	Required	Description
transactions	[Transaction]	true	List of transactions
continuation_key	string	true	Value to retrieve next page of transactions. Null if there are no more pages. Only valid in current session.

PSUType

"business"

Enumerated Values

Value	Description
business	business
personal	personal

PartyIdentification

{
  "name": "MyPreferedAisp",
  "postal_address": {
    "address_type": "DeliveryTo",
    "department": "Department of resources",
    "sub_department": "Sub Department of resources",
    "street_name": "Vasavagen",
    "building_number": "4",
    "post_code": "00123",
    "town_name": "Helsinki",
    "country_sub_division": "Uusima",
    "country": "Finland",
    "address_line": [
      "Mr Asko Teirila PO Box 511",
      "39140 AKDENMAA FINLAND"
    ]
  },
  "organisation_id": {
    "identification": "12FR5",
    "scheme_name": "COID",
    "issuer": "FR"
  },
  "private_id": {
    "identification": "12FR5",
    "scheme_name": "COID",
    "issuer": "FR"
  }
}

Properties

Name	Type	Required	Description
name	string	false	Name by which a party is known and which is usually used to identify that party.
postal_address	PostalAddress	false	none
organisation_id	GenericIdentification	false	none
private_id	GenericIdentification	false	none

PostalAddress

{
  "address_type": "DeliveryTo",
  "department": "Department of resources",
  "sub_department": "Sub Department of resources",
  "street_name": "Vasavagen",
  "building_number": "4",
  "post_code": "00123",
  "town_name": "Helsinki",
  "country_sub_division": "Uusima",
  "country": "Finland",
  "address_line": [
    "Mr Asko Teirila PO Box 511",
    "39140 AKDENMAA FINLAND"
  ]
}

Properties

Name	Type	Required	Description
address_type	AddressType	false	Available address type values
department	string	false	Identification of a division of a large organisation or building.
sub_department	string	false	Identification of a sub-division of a large organisation or building.
street_name	string	false	Name of a street or thoroughfare.
building_number	string	false	Number that identifies the position of a building on a street.
post_code	string	false	Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
town_name	string	false	Name of a built-up area, with defined boundaries, and a local government.
country_sub_division	string	false	Identifies a subdivision of a country such as state, region, county.
country	string	false	Country in which a person resides (the place of a person's home). In the case of a company, it is the country from which the affairs of that company are directed.
address_line	[string]	false	Unstructured address. The two lines must embed zip code and town name

RateType

"SPOT"

Enumerated Values

Value	Description
SPOT	Exchange rate applied is the spot rate.
SALE	Exchange rate applied is the market rate at the time of the sale.
AGRD	Exchange rate applied is the rate agreed between the parties

SandboxInfo

{
  "users": [
    {
      "username": "MyUsername",
      "password": "MySecretPassowrd",
      "otp": "123456"
    }
  ]
}

Properties

Name	Type	Required	Description
users	[SandboxUser]	false	List of sandbox users which can be used to test sandbox environment

SandboxUser

{
  "username": "MyUsername",
  "password": "MySecretPassowrd",
  "otp": "123456"
}

Properties

Name	Type	Required	Description
username	string	false	Username
password	string	false	Password
otp	string	false	One time password

SchemeName

"CHID"

Enumerated Values

Value	Description
CHID	Clearing Identification Number
GS1G	GS1GLNIdentifier
DUNS	Data Universal Numbering System
BANK	BankPartyIdentification. Unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client.
TXID	TaxIdentificationNumber
CUST	CorporateCustomerNumber
EMPL	EmployerIdentificationNumber
OTHC	OtherCorporate. Handelsbanken-specific code
DRLC	DriversLicenseNumber
CUSI	CustomerIdentificationNumberIndividual. Handelsbanken-specific code
SOSE	SocialSecurityNumber
ARNU	AlienRegistrationNumber
CCPT	PassportNumber
OTHI	OtherIndividual. Handelsbanken-specific code
COID	CountryIdentificationCode. Country authority given organisation identification (e.g., corporate registration number)
SREN	The SIREN number is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France.
SRET	The SIRET number is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity.
NIDN	NationalIdentityNumber. Number assigned by an authority to identify the national identity number of a person.
OAUT	OAUTH2 access token that is owned by the PISP being also an AISP and that can be used in order to identify the PSU
CPAN	Card PAN (masked or plain)
BBAN	Basic Bank Account Number. Represents a country-specific bank account number.
IBAN	International Bank Account Number (IBAN) - identification used internationally by financial institutions to uniquely identify the account of a customer.
MIBN	Masked IBAN
BGNR	Swedish BankGiro account number. Used in domestic swedish giro payments
PGNR	Swedish PlusGiro account number. Used in domestic swedish giro payments

SessionAccount

{
  "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
  "identification_hash": "string"
}

Properties

Name	Type	Required	Description
uid	string(uuid)	true	Account identificator within the session
identification_hash	string	true	Global account identification hash

SessionStatus

"INVALID"

Enumerated Values

Value	Description
INVALID	INVALID
PENDING_AUTHORIZATION	PENDING_AUTHORIZATION
RETURNED_FROM_BANK	RETURNED_FROM_BANK
AUTHORIZED	AUTHORIZED
EXPIRED	EXPIRED
CLOSED	CLOSED
REVOKED	REVOKED

StartAuthorizationRequest

{
  "access": {
    "valid_until": "2020-12-01T12:00:00.000000+00:00"
  },
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "state": "3a57e2d3-2e0c-4336-af9b-7fa94f0606a3",
  "redirect_url": "http://example.com",
  "psu_type": "business",
  "auth_method": "methodName",
  "credentials": {
    "userId": "MyUsername"
  },
  "credentials_autosubmit": true,
  "language": "fi",
  "psu_id": "string"
}

Properties

Name	Type	Required	Description
access	Access	true	Scope of access to be request from ASPSP and to be confirmed by PSU
aspsp	ASPSP	true	ASPSP that PSU is going to be authenticated to
state	string	true	Arbitrary string. Same string will be returned in query parameter when redirecting to the URL passed via redirect_url parameter
redirect_url	string(uri)	true	URL that PSU will be redirected to after authorization
psu_type	PSUType	false	PSU type which consent is created for
auth_method	string	false	Desired authorization method (in case ASPSP supports multiple). Supported methods can be obtained from ASPSP auth_methods
credentials	object	false	PSU credentials (User ID, company ID etc.) If not provided, then those are going to be asked from a PSU during authorization
credentials_autosubmit	boolean	false	Controls wether user credentials will be autosubmitted (if passed). If set to false then credentials form will be prefilled with passed credentials
language	string	false	Preferred PSU language. Two-letter lowercase language code
psu_id	string	false	Unique identification of a PSU used in the client's application. It can be used to match sessions of the same user. Although only hashed value is stored, it is recommended to use anonymised identifiers (i.e. digital ID instead of email or social security number).

StartAuthorizationResponse

{
  "url": "https://tilisy.enablebanking.com/welcome?sessionid=73100c65-c54d-46a1-87d1-aa3effde435a",
  "authorization_id": "73100c65-c54d-46a1-87d1-aa3effde435a",
  "psu_id_hash": "string"
}

Properties

Name	Type	Required	Description
url	string(uri)	true	URL to redirect PSU to
authorization_id	string(uuid)	true	PSU authorisation ID, a value used to identify an authorisation session. Please note that another session ID will used to fetch account data.
psu_id_hash	string	false	Hashed unique identification of a PSU used in the client's application.

SuccessResponse

{
  "message": "OK"
}

Properties

Name	Type	Required	Description
message	string	false	Returns "OK" in case of successfull request

Transaction

{
  "entry_reference": "5561990681",
  "merchant_category_code": "5511",
  "transaction_amount": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "creditor": {
    "name": "MyPreferedAisp",
    "postal_address": {
      "address_type": "DeliveryTo",
      "department": "Department of resources",
      "sub_department": "Sub Department of resources",
      "street_name": "Vasavagen",
      "building_number": "4",
      "post_code": "00123",
      "town_name": "Helsinki",
      "country_sub_division": "Uusima",
      "country": "Finland",
      "address_line": [
        "Mr Asko Teirila PO Box 511",
        "39140 AKDENMAA FINLAND"
      ]
    },
    "organisation_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    },
    "private_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  },
  "creditor_account": {
    "iban": "FI1737631867613465"
  },
  "creditor_agent": {
    "bic_fi": "string",
    "clearing_system_member_id": {
      "clearing_system_id": "NZNCC",
      "member_id": "020368"
    },
    "name": "string"
  },
  "debtor": {
    "name": "MyPreferedAisp",
    "postal_address": {
      "address_type": "DeliveryTo",
      "department": "Department of resources",
      "sub_department": "Sub Department of resources",
      "street_name": "Vasavagen",
      "building_number": "4",
      "post_code": "00123",
      "town_name": "Helsinki",
      "country_sub_division": "Uusima",
      "country": "Finland",
      "address_line": [
        "Mr Asko Teirila PO Box 511",
        "39140 AKDENMAA FINLAND"
      ]
    },
    "organisation_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    },
    "private_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  },
  "debtor_account": {
    "iban": "FI8638798819867751"
  },
  "debtor_agent": {
    "bic_fi": "string",
    "clearing_system_member_id": {
      "clearing_system_id": "NZNCC",
      "member_id": "020368"
    },
    "name": "string"
  },
  "bank_transaction_code": {
    "description": "Utlandsbetalning",
    "code": "12",
    "sub_code": "32"
  },
  "credit_debit_indicator": "CRDT",
  "status": "BOOK",
  "booking_date": "2020-01-01",
  "value_date": "2020-01-01",
  "transaction_date": "2020-01-01",
  "balance_after_transaction": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "reference_number": "RF07850352502356628678117",
  "remittance_information": [
    "RF07850352502356628678117",
    "Gift for Alex"
  ],
  "debtor_account_additional_identification": [
    {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  ],
  "creditor_account_additional_identification": [
    {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  ],
  "exchange_rate": {
    "unit_currency": {
      "iban": "FI8821291587733472",
      "other": {
        "identification": "123456",
        "scheme_name": "BBAN"
      }
    },
    "exchange_rate": "string",
    "rate_type": "SPOT",
    "contract_identification": "string",
    "instructed_amount": {
      "currency": "EUR",
      "amount": "1.23"
    }
  },
  "note": "string"
}

Properties

Name	Type	Required	Description
entry_reference	string	false	Unique transaction identifier provided by ASPSP. This identifier is both unique and immutable for accounts with the same identification hashes and can be used for matching transactions across multiple PSU authentication sessions. Usually the same identifier is available for transactions in ASPSP's online/mobile interface and is called archive ID or similarly. Please note that this identifier is not globally unique and same entry references are likely to occur for transactions belonging to different accounts.
merchant_category_code	string	false	Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction
transaction_amount	AmountType	true	Amount of money of the transaction
creditor	PartyIdentification	false	Identification of the party receiving money in the transaction
creditor_account	AccountIdentification	false	Identification of the account on which the transaction is credited
creditor_agent	FinancialInstitutionIdentification	false	Identification of the creditor agent
debtor	PartyIdentification	false	Identification of the party sending money in the transaction
debtor_account	AccountIdentification	false	Identification of the account on which the transaction is debited
debtor_agent	FinancialInstitutionIdentification	false	Identification of the debtor agent
bank_transaction_code	BankTransactionCode	false	Allows the account servicer to correctly report a transaction, which in its turn will help account owners to perform their cash management and reconciliation operations.
credit_debit_indicator	CreditDebitIndicator	true	Accounting flow of the transaction
status	TransactionStatus	true	Available transaction status values
booking_date	string(date)	false	Booking date of the transaction on the account
value_date	string(date)	false	Value date of the transaction on the account
transaction_date	string(date)	false	Date used for specific purposes: - for card transaction: date of the transaction - for credit transfer: acquiring date of the transaction - for direct debit: receiving date of the transaction
balance_after_transaction	AmountType	false	Amount of money on the account after execution of the transaction
reference_number	string	false	Credit transfer reference number (also known as the creditor reference or the structured creditor reference). The value is set when it is known that the transaction data contains a reference number (in either ISO 11649 or a local format).
remittance_information	[string]	false	Payment details. For credit transfers may contain free text, reference number or both at the same time (in case Extended Remittance Information is supported). When it is known that remittance information contains a reference number (either based on ISO 11649 or a local scheme), the reference number is also available via the reference_number field.
debtor_account_additional_identification	[GenericIdentification]	false	All other debtor account identifiers provided by ASPSPs
creditor_account_additional_identification	[GenericIdentification]	false	All other creditor account identifiers provided by ASPSPs
exchange_rate	ExchangeRate	false	Provides details on the currency exchange rate and contract.
note	string	false	The internal note made by PSU

TransactionStatus

"BOOK"

Enumerated Values

Value	Description
BOOK	Accounted transaction (ISO20022 Closing Booked)
CNCL	Cancelled transaction
HOLD	Account hold
OTHR	Transaction with unknown status or not fitting the other options
PDNG	Instant Balance Transaction (ISO20022 Expected)
RJCT	Rejected transaction
SCHD	Scheduled transaction

Usage

"PRIV"

Enumerated Values

Value	Description
PRIV	private personal account
ORGA	professional account

UI Widgets

Data sharing terms

This widget provides the possibility to display to an end user terms of the service and acquire their consent before redirecting them to tilisy.enablebanking.com for authorization of the requested access in an ASPSP.

In order to use the widget, the following is needed.

1. Load the widgets library https://tilisy.enablebanking.com/lib/widgets.umd.min.js on the page where it is going to be used.

<script src="https://tilisy.enablebanking.com/lib/widgets.umd.min.js"></script>

2. Put the custom element tilisy-consent registered by the widgets library into the place on the page where the widget needs to be shown.

<tilisy-consent
  id="tilisy-consent"
  authorization="a8bfe9f4-dfdf-4c86-9a94-9db7660bd4bd"
  locale="SV"
  can-cancel
  sandbox></tilist-consent>

The element tilisy-consent has the following attributes:

• authorization (required), should contain authorization ID received from POST /auth API call
• locale (optional), language in which the widget content should be presented. Supported languages: DA, EN, ET, FI, FR, LT, LV, NL, NO, PL, RU, SV
• can-cancel (optional), when present the “Cancel” button will be displayed, which will emit cancel event when pressed
• sandbox (optional), to be used when authorization was initiated with an application registered to sandbox environment
• no-redirect (optional), to be used if the end user should not be automatically redirected to tilisy.enablebanking.com for authorization of the access in an ASPSP; in this case redirect is to be performed when confirmed event is triggered.

Using event listener function

<script>
  document.getElementById("tilisy-consent").addEventListener("confirmed", function(e) {
    console.log(e)
  });
</script>

The widget produces the following events.

• error, if an error occurs
• ready, when the widget is fully loaded
• confirmed, after a user has confirmed the consent
• cancelled, if the “Cancel” button was pressed

The events can be listened similarly to standard Javascript events using addEventListener method called for the tilisy-consent element.

The widget does not include any CSS, it will use the styles present on the page where included.

The widget can be used only on the websites with origins whitelisted for the application used to initiate end user authorization.

Sandbox environment

ASPSPs' sandboxes

After you register a sandbox application, you will get access to a limited number of ASPSPs' sandboxes, i.e. simulation environments provided by ASPSPs to third-party developers.

Enable Banking does not aim to provide access to a large number of ASPSPs' sandboxes, because very often an ASPSP sandbox environment does not accurately simulates its live environment. Moreover, many sandbox environments provides ASPSPs are not suitable for the entire flow simulation, for example, due to hard rate limits, or lack of possibility to redirect end-users to a necessary URL. ASPSPs primarily develop their sandbox environments, for providing the possibility to test basic technical functionality, such as request signing and to address generic interoperability issues with TPPs, thus they are not obliged to entirely simulate live environment.

In case an ASPSP's simulated authentication flow requires credentials to be input, the credentials can be found in the sandbox field of the ASPSP details.

You may experience a situation when an ASPSP sandbox is not working, e.g. you are not able to make simulated authentication, or an error occurs after redirect from the simulated authentication interface, or you are not able to retrieve data for one or several accounts. Mainly this happen due to instability of the ASPSP's sandbox environments or changes made to the sandbox environment without prior notice to TPPs. This does not in any way affect our integration with the ASPSP's live environment and the problem may soon disappear. However sometimes we have to completely disable some ASPSPs' sandboxes, because it is not viable to support them. Please note that due to low traffic and lack of regulatory requirements for ASPSP sandbox environment, at scale it is much harder to maintain stability of sandbox integrations.

Mock ASPSP

We provide the posibility to simulate various aspects for the API behaviour by using the "Mock ASPSP" integration controlled through the control panel on enablebanking.com.

Please refer to the video below on how data entry for Mock ASPSP works.

And the following video shows simulation of the authorisation flow with Mock ASPSP.