NAV Navigation
HTTP

Tilisy API

Scroll down for code samples, example requests and responses.

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

Base URLs:

Authentication

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

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:

JWT body must contain following fields:

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 Node.js, 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 https://api.tilisy.com/auth HTTP/1.1
Host: api.tilisy.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": "2021-01-01T00:00:00Z"
  },
  "aspsp": {
    "country": "FI",
    "name": "Nordea"
  },
  "psu_type": "business",
  "redirect_url": "http://example.com",
  "state": "3a57e2d3-2e0c-4336-af9b-7fa94f0606a3"
}

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

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 https://api.tilisy.com/sessions HTTP/1.1
Host: api.tilisy.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

{
  "accounts": [
    {
      "account_id": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "balances": [
        {
          "balance_amount": {
            "amount": null,
            "currency": null
          },
          "balance_type": "CLBD",
          "last_change_date_time": "2019-08-24T14:15:22Z",
          "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a",
          "name": "Booked balance",
          "reference_date": "2019-08-24"
        }
      ],
      "bic_fi": "string",
      "cash_account_type": "CACC",
      "currency": "string",
      "details": "string",
      "identification_hash": "string",
      "linked_account": "string",
      "name": "string",
      "product": "string",
      "psu_status": "string",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "usage": "PRIV"
    }
  ],
  "session_id": "string"
}

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

Delete session

Code samples

DELETE https://api.tilisy.com/sessions/{session_id} HTTP/1.1
Host: api.tilisy.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: 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

Get session data

Code samples

GET https://api.tilisy.com/sessions/{session_id} HTTP/1.1
Host: api.tilisy.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

{
  "accounts": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accounts_data": [
    {
      "identification_hash": "string",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5"
    }
  ],
  "status": "INVALID"
}

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

Accounts data

Get account balances

Code samples

GET https://api.tilisy.com/accounts/{account_id}/balances HTTP/1.1
Host: api.tilisy.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: 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": [
    {
      "balance_amount": {
        "amount": "1.23",
        "currency": "EUR"
      },
      "balance_type": "CLBD",
      "last_change_date_time": "2019-08-24T14:15:22Z",
      "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a",
      "name": "Booked balance",
      "reference_date": "2019-08-24"
    }
  ]
}

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 https://api.tilisy.com/accounts/{account_id}/transactions HTTP/1.1
Host: api.tilisy.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: 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
date_to query string(date) false Date to fetch transactions to
continuation_key query string false Key, allowing iterate over multiple API pages of transactions
transaction_status query string 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

Enumerated Values

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

Example responses

200 Response

{
  "continuation_key": "string",
  "transactions": [
    {
      "bank_transaction_code": {
        "code": "12",
        "description": "Utlandsbetalning",
        "sub_code": "32"
      },
      "booking_date": "2020-01-01",
      "credit_debit_indicator": "CRDT",
      "creditor": {
        "name": "MyPreferedAisp",
        "organisation_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        },
        "postal_address": {
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
          "address_type": "[",
          "building_numbder": "4",
          "country": "Finland",
          "country_sub_division": "Uusima",
          "department": "Department of resources",
          "post_code": "00123",
          "street_name": "Vasavagen",
          "sub_department": "Sub Department of resources",
          "town_name": "Helsinki"
        },
        "private_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        }
      },
      "creditor_account": "",
      "debtor": {
        "name": "MyPreferedAisp",
        "organisation_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        },
        "postal_address": {
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
          "address_type": "[",
          "building_numbder": "4",
          "country": "Finland",
          "country_sub_division": "Uusima",
          "department": "Department of resources",
          "post_code": "00123",
          "street_name": "Vasavagen",
          "sub_department": "Sub Department of resources",
          "town_name": "Helsinki"
        },
        "private_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        }
      },
      "debtor_account": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "entry_reference": "5561990681",
      "merchant_category_code": "stri",
      "remittance_information": "Gift for Alex",
      "status": "BOOK",
      "transaction_amount": {
        "amount": "1.23",
        "currency": "EUR"
      },
      "transaction_date": "2020-01-01",
      "value_date": "2020-01-01"
    }
  ]
}

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 application

Code samples

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

GET /application

Get application associated with provided JWT key id

Example responses

200 Response

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

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

Get list of ASPSPs

Code samples

GET https://api.tilisy.com/aspsps HTTP/1.1
Host: api.tilisy.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 string false Display only ASPSPs which support specified psu type

Enumerated Values

Value Description
business business
personal personal

Example responses

200 Response

{
  "aspsps": [
    {
      "country": "FI",
      "logo": "https://enablebanking.com/brands/FI/Nordea/",
      "name": "Nordea",
      "psu_types": [
        "personal",
        "business"
      ],
      "sandbox": {
        "users": [
          null
        ]
      }
    }
  ]
}

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

Schemas

ASPSP

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

Properties

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

ASPSPData

{
  "country": "FI",
  "logo": "https://enablebanking.com/brands/FI/Nordea/",
  "name": "Nordea",
  "psu_types": [
    "personal",
    "business"
  ],
  "sandbox": {
    "users": [
      {
        "password": "MySecretPassowrd",
        "username": "MyUsername"
      }
    ]
  }
}

Properties

Name Type Required Description
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/
name string true ASPSP name
psu_types [PSUType] true List of PSU types supported by ASPSP
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 ISO20022: 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"
    }
  },
  "balances": [
    {
      "balance_amount": {
        "amount": "1.23",
        "currency": "EUR"
      },
      "balance_type": "CLBD",
      "last_change_date_time": "2019-08-24T14:15:22Z",
      "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a",
      "name": "Booked balance",
      "reference_date": "2019-08-24"
    }
  ],
  "bic_fi": "string",
  "cash_account_type": "CACC",
  "currency": "string",
  "details": "string",
  "identification_hash": "string",
  "linked_account": "string",
  "name": "string",
  "product": "string",
  "psu_status": "string",
  "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
  "usage": "PRIV"
}

Properties

Name Type Required Description
account_id AccountIdentification false none
balances [BalanceResource] false list of balances provided by the ASPSP
bic_fi string false ISO20022: 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)".
cash_account_type CashAccountType true An enumeration.
currency string true none
details string false Account description set by PSU or provided by ASPSP
identification_hash string true Account identification hash
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.
name string true Account holder(s) name
product string false Product Name of the Bank for this account, proprietary definition
psu_status string false Relationship between the PSU and the account - Account Holder - Co-account Holder - Attorney
uid string(uuid) true Account unique identificator
usage Usage false An enumeration.

AddressType

"Business"

Enumerated Values

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

AmountType

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

Properties

Name Type Required Description
amount string true ISO20022: 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.
currency string true Currency code of the amount

AuthorizeSessionRequest

{
  "code": "string"
}

Properties

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

AuthorizeSessionResponse

{
  "accounts": [
    {
      "account_id": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "balances": [
        {
          "balance_amount": {
            "amount": null,
            "currency": null
          },
          "balance_type": "CLBD",
          "last_change_date_time": "2019-08-24T14:15:22Z",
          "last_committed_transaction": "4604aa90-f8a8-4180-92d8-0c3270846f0a",
          "name": "Booked balance",
          "reference_date": "2019-08-24"
        }
      ],
      "bic_fi": "string",
      "cash_account_type": "CACC",
      "currency": "string",
      "details": "string",
      "identification_hash": "string",
      "linked_account": "string",
      "name": "string",
      "product": "string",
      "psu_status": "string",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
      "usage": "PRIV"
    }
  ],
  "session_id": "string"
}

Properties

Name Type Required Description
accounts [AccountResource] true none
session_id string(uuid4) true ID of the PSU session

BalanceResource

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

Properties

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

BalanceStatus

"CLBD"

Enumerated Values

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

BankTransactionCode

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

Properties

Name Type Required Description
code string false ISO20022: Specifies the family of a transaction within the domain
description string true Arbitrary transaction categorization description
sub_code string false ISO20022: 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
CARD List of card based transactions (non ISO 20022)
CASH Account used for the payment of cash
LOAN Loan account

CreditDebitIndicator

"CRDT"

Enumerated Values

Value Description
CRDT Credit type transaction
DBIT Debit type transaction

Environment

"PRODUCTION"

Enumerated Values

Value Description
PRODUCTION PRODUCTION
SANDBOX SANDBOX

ErrorCode

"ACCOUNT_DOES_NOT_EXIST"

Enumerated Values

Value Description
ACCOUNT_DOES_NOT_EXIST No account found matching provided id
ASPSP_ERROR Error interacting with ASPSP
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 or equal than date_to
WRONG_REQUEST_PARAMETERS Wrong request parameters provided
WRONG_SESSION_STATUS Wrong session status
WRONG_TRANSACTIONS_PERIOD Wrong transactions period requested

ErrorResponse

{
  "code": 0,
  "detail": null,
  "error": "ACCOUNT_DOES_NOT_EXIST",
  "message": "string"
}

Properties

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

GenericIdentification

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

Properties

Name Type Required Description
identification string true API Identifier
issuer string false ISO20022: Entity that assigns the identification. this could a country code or any organisation name or identifier that can be recognized by both parties
scheme_name SchemeName true An enumeration.

GetApplicationResponse

{
  "description": "string",
  "environment": "PRODUCTION",
  "kid": "string",
  "name": "string",
  "redirect_urls": [
    "http://example.com"
  ]
}

Properties

Name Type Required Description
description string false Application description
environment Environment true An enumeration.
kid string(uuid4) true Application key id
name string true Application name
redirect_urls [string] true List of allowed redirect urls

GetAspspsResponse

{
  "aspsps": [
    {
      "country": "FI",
      "logo": "https://enablebanking.com/brands/FI/Nordea/",
      "name": "Nordea",
      "psu_types": [
        "personal",
        "business"
      ],
      "sandbox": {
        "users": [
          null
        ]
      }
    }
  ]
}

Properties

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

GetSessionResponse

{
  "accounts": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accounts_data": [
    {
      "identification_hash": "string",
      "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5"
    }
  ],
  "status": "INVALID"
}

Properties

Name Type Required Description
accounts [string] true List of account ids available in the session
accounts_data [SessionAccount] true Accounts data stored in the session
status SessionStatus true An enumeration.

HalBalances

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

Properties

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

HalTransactions

{
  "continuation_key": "string",
  "transactions": [
    {
      "bank_transaction_code": {
        "code": "12",
        "description": "Utlandsbetalning",
        "sub_code": "32"
      },
      "booking_date": "2020-01-01",
      "credit_debit_indicator": "CRDT",
      "creditor": {
        "name": "MyPreferedAisp",
        "organisation_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        },
        "postal_address": {
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
          "address_type": "Business",
          "building_numbder": "4",
          "country": "Finland",
          "country_sub_division": "Uusima",
          "department": "Department of resources",
          "post_code": "00123",
          "street_name": "Vasavagen",
          "sub_department": "Sub Department of resources",
          "town_name": "Helsinki"
        },
        "private_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        }
      },
      "creditor_account": "",
      "debtor": {
        "name": "MyPreferedAisp",
        "organisation_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        },
        "postal_address": {
          "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
          "address_type": "Business",
          "building_numbder": "4",
          "country": "Finland",
          "country_sub_division": "Uusima",
          "department": "Department of resources",
          "post_code": "00123",
          "street_name": "Vasavagen",
          "sub_department": "Sub Department of resources",
          "town_name": "Helsinki"
        },
        "private_id": {
          "identification": "12FR5",
          "issuer": "FR",
          "scheme_name": "["
        }
      },
      "debtor_account": {
        "iban": "FI8821291587733472",
        "other": {
          "identification": "123456",
          "scheme_name": "BBAN"
        }
      },
      "entry_reference": "5561990681",
      "merchant_category_code": "stri",
      "remittance_information": "Gift for Alex",
      "status": "BOOK",
      "transaction_amount": {
        "amount": "1.23",
        "currency": "EUR"
      },
      "transaction_date": "2020-01-01",
      "value_date": "2020-01-01"
    }
  ]
}

Properties

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

PSUType

"business"

Enumerated Values

Value Description
business business
personal personal

PartyIdentification

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

Properties

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

PostalAddress

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

Properties

Name Type Required Description
address_line [string] false Unstructured address. The two lines must embed zip code and town name
address_type AddressType false An enumeration.
building_numbder string false Number that identifies the position of a building on a street.
country string true ISO20022: 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.
country_sub_division string false Identifies a subdivision of a country such as state, region, county.
department string false Identification of a division of a large organisation or building.
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.
street_name string false Name of a street or thoroughfare.
sub_department string false Identification of a sub-division of a large organisation or building.
town_name string false Name of a built-up area, with defined boundaries, and a local government.

SandboxInfo

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

Properties

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

SandboxUser

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

Properties

Name Type Required Description
password string false Password
username string false Username

SchemeName

"ARNU"

Enumerated Values

Value Description
ARNU AlienRegistrationNumber
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.
BBAN Basic Bank Account Number. Represents a country-specific bank account number.
BG Swedish BankGiro account number. Used in domestic swedish giro payments
CCPT PassportNumber
CHID Clearing Identification Number
COID CountryIdentificationCode. Country authority given organisation identification (e.g., corporate registration number)
CPAN Card PAN
CUSI CustomerIdentificationNumberIndividual. Handelsbanken-specific code
CUST CorporateCustomerNumber
DRLC DriversLicenseNumber
DUNS Data Universal Numbering System
EMPI EmployeeIdentificationNumberIndividual. Handelsbanken-specific code
EMPL EmployerIdentificationNumber
GS1G GS1GLNIdentifier
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
OTHC OtherCorporate. Handelsbanken-specific code
OTHI OtherIndividual. Handelsbanken-specific code
PG Swedish PlusGiro account number. Used in domestic swedish giro payments
SOSE SocialSecurityNumber
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.
TXID TaxIdentificationNumber
TXII TaxIdentificationNumberIndividual. Handelsbanken-specific code

SessionAccount

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

Properties

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

SessionStatus

"AUTHORIZED"

Enumerated Values

Value Description
AUTHORIZED AUTHORIZED
CLOSED CLOSED
INVALID INVALID
PENDING_AUTHORIZATION PENDING_AUTHORIZATION
RETURNED_FROM_BANK RETURNED_FROM_BANK

StartAuthorizationRequest

{
  "access": {
    "valid_until": "2021-01-01T00:00:00Z"
  },
  "aspsp": {
    "country": "FI",
    "name": "Nordea"
  },
  "psu_type": "business",
  "redirect_url": "http://example.com",
  "state": "3a57e2d3-2e0c-4336-af9b-7fa94f0606a3"
}

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
psu_type PSUType false An enumeration.
redirect_url string(uri) true URL that PSU will be redirected to after authorization
state string true Arbitrary string. Same string will be returned in query parameter when redirecting to the URL passed via redirect_url parameter

StartAuthorizationResponse

{
  "url": "https://sandbox.tilisy.com/welcome?sessionid=73100c65-c54d-46a1-87d1-aa3effde435a"
}

Properties

Name Type Required Description
url string(uri) true URL to redirect PSU to

SuccessResponse

{
  "message": "OK"
}

Properties

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

Transaction

{
  "bank_transaction_code": {
    "code": "12",
    "description": "Utlandsbetalning",
    "sub_code": "32"
  },
  "booking_date": "2020-01-01",
  "credit_debit_indicator": "CRDT",
  "creditor": {
    "name": "MyPreferedAisp",
    "organisation_id": {
      "identification": "12FR5",
      "issuer": "FR",
      "scheme_name": "ARNU"
    },
    "postal_address": {
      "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
      "address_type": "Business",
      "building_numbder": "4",
      "country": "Finland",
      "country_sub_division": "Uusima",
      "department": "Department of resources",
      "post_code": "00123",
      "street_name": "Vasavagen",
      "sub_department": "Sub Department of resources",
      "town_name": "Helsinki"
    },
    "private_id": {
      "identification": "12FR5",
      "issuer": "FR",
      "scheme_name": "ARNU"
    }
  },
  "creditor_account": "",
  "debtor": {
    "name": "MyPreferedAisp",
    "organisation_id": {
      "identification": "12FR5",
      "issuer": "FR",
      "scheme_name": "ARNU"
    },
    "postal_address": {
      "address_line": "Mr Asko Teirila PO Box 511\n        39140 AKDENMAA FINLAND ",
      "address_type": "Business",
      "building_numbder": "4",
      "country": "Finland",
      "country_sub_division": "Uusima",
      "department": "Department of resources",
      "post_code": "00123",
      "street_name": "Vasavagen",
      "sub_department": "Sub Department of resources",
      "town_name": "Helsinki"
    },
    "private_id": {
      "identification": "12FR5",
      "issuer": "FR",
      "scheme_name": "ARNU"
    }
  },
  "debtor_account": {
    "iban": "FI8821291587733472",
    "other": {
      "identification": "123456",
      "scheme_name": "BBAN"
    }
  },
  "entry_reference": "5561990681",
  "merchant_category_code": "stri",
  "remittance_information": "Gift for Alex",
  "status": "BOOK",
  "transaction_amount": {
    "amount": "1.23",
    "currency": "EUR"
  },
  "transaction_date": "2020-01-01",
  "value_date": "2020-01-01"
}

Properties

Name Type Required Description
bank_transaction_code BankTransactionCode false ISO20022: 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.
booking_date string(date) false Booking date of the transaction on the account
credit_debit_indicator CreditDebitIndicator true An enumeration.
creditor PartyIdentification false none
creditor_account AccountIdentification false none
debtor PartyIdentification false none
debtor_account AccountIdentification false none
entry_reference string false Technical incremental identification of the transaction.
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
remittance_information [string] false ISO20022: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.
status TransactionStatus true An enumeration.
transaction_amount AmountType true none
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
value_date string(date) false Value date of the transaction on the account

TransactionStatus

"BOOK"

Enumerated Values

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

Usage

"ORGA"

Enumerated Values

Value Description
ORGA professional account
PRIV private personal account
HTTP