API Market documentation

Corporate accounts API - details

The Corporate Accounts API provides Account Information Services (AIS) and is available to Clients subscribing to the Corporate Accounts product.
A variety of endpoints (four in total) are provided to fetch information about business accounts and their transaction histories.

Changes from the previous version

This is the changelog of Corporate accounts API. The topmost item is the latest version and the changes described in it are relative to the previous version which is listed directly below. The current version of the API documentation is 3.1. It is related to Corporate accounts API version 3.

Version 3.1

Endpoint	Change
List Accounts, Filter Accounts, Account Details	Field opening_balance available outside of sandbox currently for DK currency accounts. We will gradually provide value for this field for all countries (FI, SE, NO).

Version 3.0

Endpoint	Change
List Transactions	In new version v3 of API transaction data within single request can be retrieved only for a period of up to 7 days. This means that difference between from_date and to_date parameters can not exceed 7 days. Notice: Please keep in mind that it is still possible to obtain historical data for up to 15 months back in time by sending several consecutive requests with different date parameters.

Version 2.10

Endpoint	Change
List Accounts, Filter Accounts, Account Details	Endpoint returns new optional field opening_balance. We will gradually provide value for this field for all countries (FI, SE, DK, NO). It contains information about booked balance on the account at the beginning of the day. It equals the closing balance of the previous business day.

Version 2.9 - currently only available in sandbox

Endpoint	Change
List Transactions	Endpoint returns more transaction details for Finnish transactions. The new fields are original_archive_code, correction_flag, exchange_rate_reference, debtor_id, extra_info.
List Transactions	To mimic current production implementation, the default behaviour of endpoint was changed in sandbox in case when optional parameter from_date is not provided explicitly in request. In such scenario endpoint will return transactions from “yesterday” and “today”. (Default from_date parameter value will be set to yesterday’s date).

Version 2.8

Endpoint	Change
List Accounts, Filter Accounts, Account Details	Endpoint returns new optional field branch_code. This field is returned only for Danish accounts. It contains information about local branch code.
List Transactions	Changed the default behaviour of endpoint in case when optional parameter from_date in not provided explicitly in request. In such scenario transactions will be returned only for a period of 2 months.

Version 2.7

Endpoint	Change
List Accounts	New fields error_status and error_description are added to the response. The returned values are described below. Additionally, the _id field value is masked in case of error. Examples of error responses are added to this document.

Values for the new fields:

Error_status	Error_description
NOT_FOUND	Account information is not currently accessible.
ERROR_OCCURRED	Error occurred while accessing account information. The details cannot be returned right now.

Version 2.6

No changes in the API, only improvement to the documentation.

Version 2.5

The following changes that have been available earlier only in Sandbox are now available in production as well:

Endpoint	Change
List Accounts, Filter Accounts, Account Details	Endpoint returns a new optional field plusgiro. This field is returned only for Swedish Plusgiro accounts. It contains the account number in Plusgiro format.
List Accounts, Filter Accounts, Account Details	Endpoints return Danish IBAN account numbers in Nordea official format. This means that the bank code within IBAN is always 2000. Previously these endpoints returned IBAN account numbers containing real Nordea branch number. For the account “1543124180” the new IBAN is “DK8820001543124180”. Previously endpoints returned IBAN “DK4713421543124180”.
List Transactions	Endpoint returns more transaction details for Swedish transactions. The new fields are counterparty_address, counterparty_bank_bic, counterparty_bank_name, counterparty_bank_address, correspondent_bic, payment_urgency, charge_type, transfer_purpose, end_to_end_reference.

Version 2.4

Endpoint	Change
Account Details	Endpoint returns new optional fields account_short_name, group_account_type, legal_balance and master_account_number. The fields group_account_type, legal_balance and master_account_number are returned only for cashpool accounts.

Version 2.3

Endpoint	Change
List Accounts, Filter Accounts, Account Details	Endpoint returns a new optional field plusgiro. This field is returned only for Swedish Plusgiro accounts. It contains the account number in Plusgiro format.
List Accounts, Filter Accounts, Account Details	Endpoints return Danish IBAN account numbers in Nordea official format. This means that the bank code within IBAN is always 2000. Previously these endpoints returned IBAN account numbers containing real Nordea branch number. For the account “1543124180” the new IBAN is “DK8820001543124180”. Previously endpoints returned IBAN “DK4713421543124180”.
List Transactions	Endpoint returns more transaction details for Swedish transactions. The new fields are counterparty_address, counterparty_bank_bic, counterparty_bank_name, counterparty_bank_address, correspondent_bic, payment_urgency, charge_type, transfer_purpose, end_to_end_reference.

Version 2.2

A new query parameter from_transaction is added to the List Transactions endpoint. This parameter should contain the transaction ID of a transaction provided in the List Transactions response. When used, the service will return only transactions that have been booked after the transaction ID is provided. This new parameter can coexist alongside other filters.

Version 2.0

Sample data for Norway was added and can be used with all the Corporate Accounts API endpoints.
The new version v2 of the API has a mandatory Signature header. All consumers will be required to use certificates (eIDAS or self-signed) for the API after September 14, 2019, thus we will be enforced to depreciate all API versions below v2.
The following headers are required for the Corporate Accounts API GET requests: “(request-target) x-nordea-originating-host x-nordea-originating-date”.

Version 1.0

This is the first official version of the Business API (v1). Compared to Initial Version, the following changes were introduced: Pagination of the results for accounts and transaction listing was added to the following endpoints: /corporate/v1/accounts and /corporate/v1/accounts/<account_id>/transactions
Sample data for Denmark was added and can be used with all the Corporate Accounts API endpoints.
Sample data for Sweden was extended with various transaction types and can be used with the following endpoint: /corporate/v1/accounts/<account_id>/transactions

Initial Version

Accounts endpoints implemented

API endpoints

As stated above, the Corporate Accounts API has four endpoints:

Endpoint	Supported HTTP Methods
List Accounts: corporate/v3/accounts	GET
Filter Accounts: corporate/v3/accounts/filter	POST
Account Details: corporate/v3/accounts/<account_id>	GET
List Transactions: corporate/v3/accounts/<account_id>/transactions	GET

As you can see from the table, the Corporate Accounts API supports HTTP GET and HTTP POST requests.

The first endpoint can be used to list all accounts accessible within the company’s agreement and will list detailed information about each account.
The second endpoint can be used to filter accounts within the company’s agreement. It will also list detailed information about each filtered account.
The third endpoint can be used to query detailed information about a specified account.
Finally, the fourth endpoint can be used to obtain the transaction history from a specified account.

Corporate accounts API examples

Here you can find examples showing how to use the API endpoints.
All Corporate Accounts API endpoints require the following headers, in order to obtain responses:

Content-Type: application/json
Authorization: Bearer <access_token>
X-IBM-Client: <client_id>
X-IBM-Client-Secret: <client_secret>
Signature: <signature>
X-Nordea-Originating-Date: <date>
X-Nordea-Originating-Host: <host>

Additionally any POST /corporate/v3/accounts/filter request will also require a Digest header to be included

The <access_token> represents the Customer’s authorization for the Client to access their Account Information. This token is obtained during the Corporate Access Authorization process which must have been completed before the Corporate Accounts API request. Please see Corporate Access Authorization API for all details about the access token, signature, and other HTTP header contents.

Example: List Accounts

This endpoint URL has the following form:

GET /corporate/v3/accounts

The response will look like this:

{
    "group_header": {
        "message_identification": "98fd5dc931e52f3dea148824b6cc54c4",
        "creation_date_time": "2020-04-29T05:38:47.55898Z",
        "http_code": 200
    },
    "response": {
        "accounts": [
            {
                "_id": "DK20001543507527-DKK",
                "country": "DK",
                "iban": "DK0720001543507527",
                "bban": "20001543507527",
                "currency": "DKK",
                "account_name": "TEST COMPANY 6",
                "product": "Koncernintern pengemarked",
                "account_type": "Current",
                "bic": "NDEADKKK",
                "status": "OPEN",
                "credit_limit": "0.00",
                "available_balance": "-2751581980.70",
                "booked_balance": "-2751581980.70",
                "value_dated_balance": "-2751581980.70",
                "latest_transaction_booking_date": "2020-04-28",
                "_links": [
                    {
                        "rel": "details",
                        "href": "/v3/accounts/DK20001543507527-DKK"
                    },
                    {
                        "rel": "transactions",
                        "href": "/v3/accounts/DK20001543507527-DKK/transactions"
                    }
                ]
            },
            {
                "_id": "DK20001543507586-DKK",
                "country": "DK",
                "iban": "DK6320001543507586",
                "bban": "20001543507586",
                "currency": "DKK",
                "account_name": "TEST COMPANY 6",
                "product": "Koncernintern pengemarked",
                "account_type": "Current",
                "bic": "NDEADKKK",
                "status": "OPEN",
                "credit_limit": "0.00",
                "available_balance": "79764.32",
                "booked_balance": "79764.32",
                "value_dated_balance": "79764.32",
                "latest_transaction_booking_date": "2020-04-28",
                "_links": [
                    {
                        "rel": "details",
                        "href": "/v3/accounts/DK20001543507586-DKK"
                    },
                    {
                        "rel": "transactions",
                        "href": "/v3/accounts/DK20001543507586-DKK/transactions"
                    }
                ]
            }
}

Where a large number of accounts are available, the List Accounts responses may be paginated.
The _links section will then reference different pages of the response, and it is possible to request individual pages by including a ?page the parameter in the http request.
A default page size is set (for example 50 accounts) but this too can be varied (reduced) where the Client includes a ?size the parameter in the http request.

page – number of the page with results
size – the number of results displayed on one page

Example displaying the first 30 accounts out of a total 135 accounts available:

GET /corporate/v3/accounts?page=1&size=30

here the links section in the response might be:

{
  "_links": [
         {
             "rel": "first",
             "href": "/v3/accounts?page=1&size=30"
         },
         {
             "rel": "self",
             "href": "/v3/accounts?page=1&size=30"
         },
         {
             "rel": "next",
             "href": "/v3/accounts?page=2&size=30"
         },
         {
             "rel": "last",
             "href": "/v3/accounts?page=5&size=30"
         }
     ]
}

And an example for displaying results for middle page:

GET /corporate/v3/accounts/?page=3&size=30

{
 "_links": [
           {
               "rel": "first",
               "href": "/v3/accounts?page=1&size=30"
           },
           {
               "rel": "previous",
               "href": "/v3/accounts?page=2&size=30"
           },
           {
               "rel": "self",
               "href": "/v3/accounts?page=3&size=30"
           },
           {
               "rel": "next",
               "href": "/v3/accounts?page=4&size=30"
           },
           {
               "rel": "last",
               "href": "/v3/accounts?page=5&size=30"
           }
       ]
}

Examples for error responses:

{
    "_id": "DK50******98-DKK",
    "error_status": "ERROR_OCCURRED",
    "error_description": "Error occurred while accessing account information. The details cannot be retrieved right now."
}

{
    "_id": "DK20**********15-DKK",
    "error_status": "NOT_FOUND",
    "error_description": "Account information is not currently accessible."
}

Example: Filtered Account List

This endpoint URL has the following form:

POST /corporate/v3/accounts/filter

It is possible, using parameters in the body of this request to filter the List Accounts response by specifying an account list, currency list, and/or country list. Example values for body parameters are presented below:

{
	"account_list":["FI0315723000321109-EUR"],
	"currency_list":["EUR"],
	"country_list":["FI","SE"]
}

The response will look like this:

{
     "group_header": {
         "message_identification": "w3TfB31w5U4",
         "creation_date_time": "2018-10-16T08:36:39.399Z",
         "http_code": 200
     },
     "response": {
         "accounts": [
             {
                 "_id": "FI8510113000207927-EUR",
                 "country": "FI",
                 "iban": "FI8510113000207927",
                 "currency": "EUR",
                 "account_name": "Test Name FI",
                 "product": "SHEKKITILI",
                 "account_type": "Current",
                 "available_balance": "22237.10",
                 "booked_balance": "22491.12",
                 "value_dated_balance": "22678.21",
                 "bic": "NDEAFIHH",
                 "status": "OPEN",
                 "credit_limit": "100",
                 "latest_transaction_booking_date": "2018-10-16",
                 "_links": [
                     {
                         "rel": "self",
                         "href": "/v3/accounts/FI8510113000207927-EUR"
                     },
                     {
                         "rel": "transactions",
                         "href": "/v3/accounts/FI8510113000207927-EUR/transactions"
                     }
                ]
         }
     ],
     "_links": [
         {
             "rel": "first",
             "href": "/v3/accounts/filter?page=1&size=50"
         },
         {
             "rel": "self",
             "href": "/v3/accounts/filter?page=1&size=50"
         },
         {
             "rel": "last",
             "href": "/v3/accounts/filter?page=1&size=50"
         }
      ]
   }
}

Example: Account Details

This endpoint is used to retrieve the details of a single specified account. The URL has the following form:

GET /corporate/v3/accounts/<account_id>

Where <account_id> is the identifier (_id) of the required account. For example FI8510113000207927-EUR The response will look like this:

{
      "group_header": {
         "message_identification": "WHHYRLfR3II",
         "creation_date_time": "2018-10-16T08:36:45.005Z",
         "http_code": 200
      },
      "response": {
          "_id": "FI8510113000207927-EUR",
          "country": "FI",
          "iban": "FI8510113000207927",
          "currency": "EUR",
          "account_name": "Test Name FI",
          "product": "SHEKKITILI",
          "account_type": "Current",
          "available_balance": "22237.10",
          "booked_balance": "22491.12",
          "value_dated_balance": "22678.21",
          "bic": "NDEAFIHH",
          "status": "OPEN",
          "credit_limit": "100",
          "latest_transaction_booking_date": "2018-10-16",
          "_links": [
              {
                  "rel": "self",
                  "href": "/v3/accounts/FI8510113000207927-EUR"
             },
             {
                  "rel": "transactions",
                  "href": "/v3/accounts/FI8510113000207927-EUR/transactions"
             }
         ]
    }
}

Example: List Transactions

NOTE: Please note that there is a different behaviour in transaction_list endpoint in requests sent for Finnish accounts. When searching for transactions within date range from “today´s date” and four days back in time.

Example: Today´s date is in this example: “2024-05-30” Query Params is set to be “From_date: 2024-05-28”, “To_date”: 2024-05-29”. Then transactions from “Today´s date”(in this example 2024-05-30) will also be returned.

This will only be the case in searches from one to four days back in time.

When requesting data outside business hours during our transaction processing there is a possibility that an empty transaction_list with only a continuation key will be returned. Please use continuation key until data is returned. Be aware that in our automated charging process we are not able to exclude the extra calls that the above scenarios are causing. But with the right use of Instant Reporting where data is requested every day, this will be limited to a minimum.

NOTE: You will receive an access token from Nordea for a period defined by you up to 180 days. You are only entitled to access the payment transactions executed in the last 90 days when using this access token, unless strong customer authentication is performed.

This endpoint URL has the following form:

GET /corporate/v3/accounts/<account_id>/transactions

Where <account_id> is the identifier (_id) of the required account. For example SE2647845003-SEK The response will look like this:

{
    "group_header": {
        "message_identification": "Qmy4MjDTKvw",
        "creation_date_time": "2018-12-13T21:16:09.894Z",
        "http_code": 200
    },
    "response": {
        "transactions": [
            {
                "transaction_id": "0801 01907 5555556",
                "currency": "SEK",
                "booking_date": "2018-07-31",
                "value_date": "2018-07-31",
                "type_description": "PlusGiro",
                "narrative": "Paymet PG 1154469-9 Green Engery",
                "status": "billed",
                "reference": "489091283320",
                "counterparty_name": "Green Energy Sweden",
                "payment_date": "2018-07-31",
                "balance_after_transaction": "202.90",
                "amount": "-308.00"
            },
            {
                "transaction_id": "0801 01907 5555557",
                "currency": "SEK",
                "booking_date": "2018-06-28",
                "value_date": "2018-06-28",
                "type_description": "PlusGiro",
                "narrative": "Paymet PG 1154469-9 Green Engery",
                "status": "billed",
                "reference": "489091283321",
                "counterparty_name": "Green Energy Sweden",
                "payment_date": "2018-06-28",
                "balance_after_transaction": "-72.10",
                "amount": "-275.00"
            },
            {
                "transaction_id": "0911 01907 0980156",
                "currency": "SEK",
                "booking_date": "2018-09-11",
                "value_date": "2018-09-11",
                "type_description": "Överföring andras",
                "narrative": "SHB 605013152",
                "status": "billed",
                "reference": "9991536581212960000001",
                "transaction_date": "2018-09-11",
                "payment_date": "2018-09-11",
                "balance_after_transaction": "-100.00",
                "amount": "-100.00"
            },
            {
                "transaction_id": "0801 01907 5555570",
                "currency": "SEK",
                "booking_date": "2018-08-01",
                "value_date": "2018-08-01",
                "type_description": "Autogiro BG",
                "narrative": "Direct Debit Söder Insurance",
                "status": "billed",
                "counterparty_name": "Söder Insurance",
                "balance_after_transaction": "-20627.22",
                "amount": "-184.00"
            },
            {
                "transaction_id": "0801 01907 5555559",
                "currency": "SEK",
                "booking_date": "2018-07-30",
                "value_date": "2018-07-30",
                "type_description": "BankGiro",
                "narrative": "Betalning BG 555-4444 Top Magazines",
                "status": "billed",
                "reference": "9000000898147369",
                "counterparty_name": "Top Magazines & Brands AB",
                "payment_date": "2018-07-30",
                "balance_after_transaction": "-4193.10",
                "amount": "-2700.00"
            },
            {
                "transaction_id": "0801 01907 5555560",
                "currency": "SEK",
                "booking_date": "2017-12-21",
                "value_date": "2017-12-21",
                "type_description": "BankGiro",
                "narrative": "Betalning BG 1234-4567 The D Carrot  Sociality",
                "status": "billed",
                "counterparty_name": "The D Carrot  Sociality Sweden",
                "payment_date": "2017-12-21",
                "balance_after_transaction": "-4493.10",
                "amount": "-300.00"
            }
        ],
        "_links": [
            {
                "rel": "self",
                "href": "/v3/accounts/SE2647845003-SEK/transactions"
            }
        ]
    }
}

Where a large number of transactions are available, the List Transactions responses may be paginated or further filtered by specifying a date range or transaction id as a starting point.
This is done by specifying parameters within the request path:

Parameter	Mandatory (Yes/No)	Description
from_date	No	Introduces a date range, only transactions falling within the period starting at this date will be included in response. If not provided transactions will return historical data for one day. (data from “today” from time of the request ” and “yesterday” = data for two days).
to_date	No	Further describes a date range, only transactions falling with the period ending at this date will be included in response
continuation_key	No	Where response has been paginated, the continuation_key parameter is used to index successive pages of the response
from_transaction	No	Provides the option to only include transactions that are booked after specified transaction ID. Using a from_transaction filter has no impact on pagination - if the from_transaction is not found on the requested page then a full page of transactions, together with any continuation_key (as appropriate) is returned to the client. The given transaction id is included in the response.

Example request to display the first page of transaction history from the beginning of January 2019:

GET /corporate/v3/accounts/SE2647845003-SEK/transactions?from_date=2019-01-01&to_date=2019-01-02

If multiple pages are provided the request to retrieve a subsequent page of the response might be as follows:

GET /corporate/v3/accounts/SE2647845003-SEK/transactions?from_date=2019-01-01&to_date=2019-01-02&continuation_key=<continuation_key>

Where the <continuation_key> will have been provided in the previous List Transactions response (all other parameters remain the same).
An example of how the <continuation_key> is provided is shown below:

{
    "continuation_key": "2019-01-01-19.24.01.457739",
    "_links": [
        {
            "rel": "self",
            "href": "/v3/accounts/SE2647845003-SEK/transactions?from_date=2019-01-01&to_date=2019-01-02"
        },
        {
            "rel": "next",
            "href": "/v3/accounts/SE2647845003-SEK/transactions?from_date=2019-01-01&to_date=2019-01-02&continuation_key=2019-01-01-19.24.01.457739"
        }
    ]
}

Example request to display transaction history starting from a given transaction id:

GET /corporate/v3/accounts/SE2647845003-SEK/transactions?from_transaction=0801 01907 5555560

where <from_transaction> contains “transaction_id” value of a transaction provided in the List Transactions response. The best performance is achieved if the last transaction_id from the Transaction List response is provided. The given transaction id (e.g. “0801 01907 5555560”) is included in the response.

Overview Corporate Payments API v2