Tilisy API

Scroll down for code samples, example requests and responses.

This API provides possibility to initiate authentication and access account information.

Base URLs:

• api.tilisy.com

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.

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.

By default you would get access to sandbox environment (i.e. simulated PSU authentication and data retrieval is served through a limited number of ASPSPs' sandboxes). Access to production environment is a subject of a contract. Please contact us at openbanking@enablebanking.com for more information.

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.tilisy.com" (always the same)
• "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/tilisy-api-samples

Send request with JWT provided

Example request

GET https://api.tilisy.com/application HTTP/1.1
Host: api.tilisy.com
Authorization: Bearer eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJSUzI1NiIsICJraWQiOiAiY2Y1ODliZTMtMzc1NS00NjViLWE4ZGYtYTkwYTE2YTMxNDAzIn0.eyJpc3MiOiAiZW5hYmxlYmFua2luZy5jb20iLCAiYXVkIjogImFwaS50aWxpc3kuY29tIiwgImlhdCI6IDE2MDE0NTY3NjgsICJleHAiOiAxNjAxNTQzMTY4fQ.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 api.tilisy.com/auth HTTP/1.1

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": "2021-01-01T00:00:00Z"
  },
  "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
}

Parameters

Name	In	Type	Required	Description
body	body	StartAuthorizationRequest	true	none

Example responses

200 Response

{
  "url": "https://sandbox.tilisy.com/welcome?sessionid=73100c65-c54d-46a1-87d1-aa3effde435a",
  "authorization_id": "a30fe4ea-62db-46aa-ab9e-d6294a70943c"
}

Responses

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

Authorize user session

Code samples

POST api.tilisy.com/sessions HTTP/1.1

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"
        }
      },
      "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",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "identification_hash": "string"
    }
  ],
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "psu_type": "business"
}

Responses

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

Get session data

Code samples

GET api.tilisy.com/sessions/{session_id} HTTP/1.1

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": "2021-01-01T00:00:00Z"
  },
  "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:30Z",
  "created": "2020-12-01T12:00:00Z",
  "psu_type": "business",
  "status": "AUTHORIZED"
}

Responses

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

Delete session

Code samples

DELETE api.tilisy.com/sessions/{session_id} HTTP/1.1

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

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	PSU geo location

Example responses

200 Response

{
  "message": "OK"
}

Responses

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

Accounts data

Get account balances

Code samples

GET api.tilisy.com/accounts/{account_id}/balances HTTP/1.1

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

GET /accounts/{account_id}/balances

Get list of available account balances by provided account 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	PSU geo location

Example responses

200 Response

{
  "balances": [
    {
      "name": "Booked balance",
      "balance_amount": {
        "currency": "EUR",
        "amount": "1.23"
      },
      "balance_type": "Accounting Balance (ISO20022 Closing Booked)",
      "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
422	Unprocessable Entity	Unprocessable Entity	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Get account transactions

Code samples

GET api.tilisy.com/accounts/{account_id}/transactions HTTP/1.1

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

GET /accounts/{account_id}/transactions

Get list of account transactions according to provided parameters

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	PSU geo location

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_numbder": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "creditor_account": "",
      "debtor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_numbder": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "debtor_account": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "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": [
        "Gift for Alex"
      ]
    }
  ],
  "continuation_key": "string"
}

Responses

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

Misc

Get list of ASPSPs

Code samples

GET api.tilisy.com/aspsps HTTP/1.1

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}$"
            }
          ]
        }
      ],
      "sandbox": {
        "users": [
          {
            "username": "MyUsername",
            "password": "MySecretPassowrd",
            "otp": "123456"
          }
        ]
      }
    }
  ]
}

Responses

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

Get application

Code samples

GET api.tilisy.com/application HTTP/1.1

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
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	GetApplicationResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden	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}$"
        }
      ]
    }
  ],
  "sandbox": {
    "users": [
      {
        "username": "MyUsername",
        "password": "MySecretPassowrd",
        "otp": "123456"
      }
    ]
  }
}

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.

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. 2021-01-01T00:00:00Z. 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"
    }
  },
  "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",
  "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
  "identification_hash": "string"
}

Properties

Name	Type	Required	Description
account_id	AccountIdentification	false	none
account_servicer	FinancialInstitutionIdentification	false	Information about the financial institution servicing the account
name	string	true	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
uid	string(uuid)	true	Account unique identificator
identification_hash	string	true	Account identification hash

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

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.

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"
        }
      },
      "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",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "identification_hash": "string"
    }
  ],
  "aspsp": {
    "name": "Nordea",
    "country": "FI"
  },
  "psu_type": "business"
}

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

BalanceResource

{
  "name": "Booked balance",
  "balance_amount": {
    "currency": "EUR",
    "amount": "1.23"
  },
  "balance_type": "Accounting Balance (ISO20022 Closing Booked)",
  "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

"CLBD"

Enumerated Values

Value	Description
CLBD	Accounting Balance (ISO20022 Closing Booked)
FWAV	Balance of money that is at the disposal of the account owner on the date specified (ISO20022 Forward Available)
ITAV	Available balance calculated in the course of the day (ISO20022 Interim Available)
ITBD	Booked balance calculated in the course of the day (ISO20022 Interim Booked)
OTHR	Other Balance
VALU	Value-date balance
XPCD	Instant Balance (ISO20022 Expected)

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	List of card based transactions (non ISO 20022)
LOAN	Loan account

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

"ACCOUNT_DOES_NOT_EXIST"

Enumerated Values

Value	Description
ACCOUNT_DOES_NOT_EXIST	No account found matching provided id
AUTHORIZATION_NOT_PROVIDED	Authorization header is not provided
ASPSP_ERROR	Error interacting with ASPSP
DATE_TO_WITHOUT_DATE_FROM	date_from must be provided if date_to provided
EXPIRED_AUTHORIZATION_CODE	Authorization code is expired
EXPIRED_SESSION	Session is expired
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
SESSION_DOES_NOT_EXIST	No session found matching provided id
UNAUTHORIZED_ACCESS	Wrong request provided
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

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

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

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}$"
            }
          ]
        }
      ],
      "sandbox": {
        "users": [
          {
            "username": "MyUsername",
            "password": "MySecretPassowrd",
            "otp": "123456"
          }
        ]
      }
    }
  ]
}

Properties

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

GetSessionResponse

{
  "access": {
    "valid_until": "2021-01-01T00:00:00Z"
  },
  "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:30Z",
  "created": "2020-12-01T12:00:00Z",
  "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": "Accounting Balance (ISO20022 Closing Booked)",
      "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_numbder": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "creditor_account": "",
      "debtor": {
        "name": "MyPreferedAisp",
        "postal_address": {
          "address_type": "DeliveryTo",
          "department": "Department of resources",
          "sub_department": "Sub Department of resources",
          "street_name": "Vasavagen",
          "building_numbder": "4",
          "post_code": "00123",
          "town_name": "Helsinki",
          "country_sub_division": "Uusima",
          "country": "Finland",
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
        },
        "organisation_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        },
        "private_id": {
          "identification": "12FR5",
          "scheme_name": "COID",
          "issuer": "FR"
        }
      },
      "debtor_account": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "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": [
        "Gift for Alex"
      ]
    }
  ],
  "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_numbder": "4",
    "post_code": "00123",
    "town_name": "Helsinki",
    "country_sub_division": "Uusima",
    "country": "Finland",
    "address_line": "Mr Asko Teirila PO Box 511\n        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_numbder": "4",
  "post_code": "00123",
  "town_name": "Helsinki",
  "country_sub_division": "Uusima",
  "country": "Finland",
  "address_line": "Mr Asko Teirila PO Box 511\n        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_numbder	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	true	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

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
TXII	TaxIdentificationNumberIndividual. Handelsbanken-specific code
EMPI	EmployeeIdentificationNumberIndividual. Handelsbanken-specific code
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
BBAN	Basic Bank Account Number. Represents a country-specific bank account number.
BG	Swedish BankGiro account number. Used in domestic swedish giro payments
PG	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
CLOSED	CLOSED

StartAuthorizationRequest

{
  "access": {
    "valid_until": "2021-01-01T00:00:00Z"
  },
  "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
}

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

StartAuthorizationResponse

{
  "url": "https://sandbox.tilisy.com/welcome?sessionid=73100c65-c54d-46a1-87d1-aa3effde435a",
  "authorization_id": "a30fe4ea-62db-46aa-ab9e-d6294a70943c"
}

Properties

Name	Type	Required	Description
url	string(uri)	true	URL to redirect PSU to
authorization_id	string(uuid)	true	PSU session id. Note that it is not the same as session id used to fetch account data

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_numbder": "4",
      "post_code": "00123",
      "town_name": "Helsinki",
      "country_sub_division": "Uusima",
      "country": "Finland",
      "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
    },
    "organisation_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    },
    "private_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  },
  "creditor_account": "",
  "debtor": {
    "name": "MyPreferedAisp",
    "postal_address": {
      "address_type": "DeliveryTo",
      "department": "Department of resources",
      "sub_department": "Sub Department of resources",
      "street_name": "Vasavagen",
      "building_numbder": "4",
      "post_code": "00123",
      "town_name": "Helsinki",
      "country_sub_division": "Uusima",
      "country": "Finland",
      "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND "
    },
    "organisation_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    },
    "private_id": {
      "identification": "12FR5",
      "scheme_name": "COID",
      "issuer": "FR"
    }
  },
  "debtor_account": {
    "iban": "FI8821291587733472",
    "other": {
      "identification": "123456",
      "scheme_name": "BBAN"
    }
  },
  "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": [
    "Gift for Alex"
  ]
}

Properties

Name	Type	Required	Description
entry_reference	string	false	Unique transaction identifier provided by ASPSP. This identifier is both unique and immutable 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.
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	none
creditor	PartyIdentification	false	none
creditor_account	AccountIdentification	false	none
debtor	PartyIdentification	false	none
debtor_account	AccountIdentification	false	none
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	none
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.

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