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:
- 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 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"
},
"auth_method": "methodName",
"credentials": {
"userId": "MyUsername"
},
"credentials_autosubmit": true,
"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"
}
],
"aspsp": {
"country": "FI",
"name": "Nordea"
},
"psu_type": "business",
"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"
}
],
"aspsp": {
"country": "FI",
"name": "Nordea"
},
"psu_type": "business",
"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": "5511",
"reference_number": "RF07850352502356628678117",
"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
{
"active": true,
"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": [
{
"auth_methods": [
{
"credentials": [
{}
],
"name": "string",
"psu_type": "business",
"title": "string"
}
],
"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
{
"auth_methods": [
{
"credentials": [
{
"description": "Your identifier used for logging in to online banking",
"name": "userId",
"required": true,
"template": "^\\d{8}$",
"title": "User ID"
}
],
"name": "string",
"psu_type": "business",
"title": "string"
}
],
"country": "FI",
"logo": "https://enablebanking.com/brands/FI/Nordea/",
"name": "Nordea",
"psu_types": [
"personal",
"business"
],
"sandbox": {
"users": [
{
"otp": "123456",
"password": "MySecretPassowrd",
"username": "MyUsername"
}
]
}
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| 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. |
| 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 |
AuthMethod
{
"credentials": [
{
"description": "Your identifier used for logging in to online banking",
"name": "userId",
"required": true,
"template": "^\\d{8}$",
"title": "User ID"
}
],
"name": "string",
"psu_type": "business",
"title": "string"
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| credentials | [Credential] | true | List of credentials which are possible to supply while initiating authorization. |
| name | string | false | Internal name of the authentication method |
| psu_type | PSUType | true | An enumeration. |
| title | string | false | Human-readable title of the authentication method |
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"
}
],
"aspsp": {
"country": "FI",
"name": "Nordea"
},
"psu_type": "business",
"session_id": "string"
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| accounts | [AccountResource] | true | none |
| aspsp | ASPSP | true | ASPSP used with the session |
| psu_type | PSUType | true | An enumeration. |
| 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 |
Credential
{
"description": "Your identifier used for logging in to online banking",
"name": "userId",
"required": true,
"template": "^\\d{8}$",
"title": "User ID"
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| description | string | false | Description of the credential to be displayed to PSU |
| name | string | true | Internal name of the credential. The name is to be used when passing credentials to the "start user authorization" request |
| required | boolean | true | Indication whether the credential is required |
| template | string | false | Perl compatible regular expression used for check of the credential format |
| title | string | true | Title for the credential to be displayed to PSU |
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 |
| 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_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
{
"active": true,
"description": "string",
"environment": "PRODUCTION",
"kid": "string",
"name": "string",
"redirect_urls": [
"http://example.com"
]
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| active | boolean | true | Indication whether the application is active |
| 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": [
{
"auth_methods": [
{
"credentials": [
{}
],
"name": "string",
"psu_type": "business",
"title": "string"
}
],
"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"
}
],
"aspsp": {
"country": "FI",
"name": "Nordea"
},
"psu_type": "business",
"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 |
| aspsp | ASPSP | true | ASPSP used with the session |
| psu_type | PSUType | true | An enumeration. |
| 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": "5511",
"reference_number": "RF07850352502356628678117",
"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": [
{
"otp": "123456",
"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
{
"otp": "123456",
"password": "MySecretPassowrd",
"username": "MyUsername"
}
Properties
| Name | Type | Required | Description |
|---|---|---|---|
| otp | string | false | One time password |
| 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"
},
"auth_method": "methodName",
"credentials": {
"userId": "MyUsername"
},
"credentials_autosubmit": true,
"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 |
| 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 |
| 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": "5511",
"reference_number": "RF07850352502356628678117",
"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 | 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 |
| 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. |
| 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 |