Retail Finance Overview
About Documentation
The sandbox offers a safe and simple way to try out Nordea’s APIs. Developers can familiarize themselves with existing and upcoming functionality. Moreover, it allows the developers to experiment and build applications that use the Nordea API before release. See sandbox for more information regarding the sandbox and what it is.
The purpose of this documentation is to give an overview of all the APIs which are included in Nordea API sandbox and upcoming versions. There is separate documentation for each API which includes the full API reference of the particular API.
This API implementation is Representational State Transfer Service (RESTful service in short), and the responses produced by the Nordea API are in JavaScript Object Notation, JSON format. The API also consumes JSON so requests sent to it should have the request body in JSON format.
The links to download the swagger files can be found here
Note that the APIs might change in the future based on feedback. Backward compatibility is not guaranteed. This document discusses the latest version of the APIs.
Terminology
To avoid confusion, we, in this section, go through some explanations of the terminology used in the documentation.
| Term | Description |
|---|---|
| Access Token | A token which is retrieved by the Client after a successful access authorization flow. The access token is used by the API to authenticate Clients. The access token does not contain any information that the Client (or client’s application) can use |
| API | Application Programming Interface. A set of definitions, protocols, and tools that can be used to create applications, interact with other applications, and exchange data. |
| API Call | API call is a request towards an API which produces a response. The API is by design stateless, and therefore it does not “remember” anything about previous requests, i.e., there is no session. Therefore every request made towards the API must contain certain headers so that the API can authenticate and authorize the client |
| Certificate | An electronic ‘passport’ used to certify the identity of a person, machine, or organization over the Internet. |
| Client | The client refers to the consumer of the API. This is commonly an application provided by the corporate customer or a regulated third-party provider. |
| Client Authentication | Client authentication: the process which provides the correct identity of the Client; a key component in enforcing that Clients are only able to access the resources that they are allowed to |
| Refresh Token | A token which is retrieved by the Client after a successful access authorization flow. The refresh token is passed by the Client in a token exchange call to obtain a fresh access token once the previous access token has expired. |
| Resource Owner | The Resource Owner refers to the corporate customer who holds a banking agreement with Nordea and uses a Client application to access their credit list information and services. |
| Sandbox | Sandbox, in the context of the Corporate APIs, is a test environment facility where the data returned by the API consists of example data. Its purpose is to mimic the real / production version of the API. The sandbox will always have available the latest published version of the API, this means that all new versions appear in sandbox before they are introduced into the production. |
| TLS | Transport Layer Security. The TLS protocol aims primarily to provide privacy and data integrity between two or more communicating computer applications |
| TSP | Trust Service Provider. An entity that provides digital services which enable the issuance and proving mechanisms to secure and protect information online. Examples include Certificates and Electronic Seals. |
| Client applications | A client application might be a website, mobile application, and so on. During the access authorization flow, the Authorizer(s) on behalf of the Resource Owner grants permission for the Client Application (consumer of the API) to use API resources. This permission is represented by the Access Token. |
Security considerations
Security is an important aspect. This API is developed by using well-tested and widely adopted security schemes. The Client ID, Client Secret, Access Token and Signature are sent in the header of the request. All the communication between the API and client is secured by TLS, which encrypts the traffic. When developing an application, it is important to keep the credentials and tokens safe and handle them carefully to avoid secrets falling into the wrong hands.
API Conventions
Availability status in APIs
The availability status is meant to inform developers about the feature life-cycle. The availability status is defined for API operations, parameters, models, and properties. These are defined in the API swagger definition and can also be seen in the API reference.
There are five availability levels which are:
| Level | Description |
|---|---|
| Stable | The stable availability level signals that this feature is in production and should be used in production applications. No breaking changes will be made to stable features without deprecating them. |
| Sandbox only | The “Sandbox only” is an availability level which indicates that a feature is only available in the sandbox environment and it will never be available in the production environment. For instance, some application testing features have Sandbox only availability level. |
Stable features are found in sandbox.
Differences between production and sandbox APIs
The production version of the API provides access to real customer data. That is, you will be able to get real data. The sandbox is the environment where the application developers can develop their applications before they can subscribe in production to production. The sandbox API is a superset of the production API, and there will be features in the sandbox which are never going to be in the production version of the API.
API swagger definition
The OBI API specification is also available in the swagger format. Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), more information about it can be found here.
API responses
The APIs consume JSON objects and returns responses as JSON objects. Consult the API reference or the examples sections of each API page to see what the response objects look like. The responses are returned encoded in UTF-8 format.
Every response returned by this API has a response code. Response codes can be used to check the result of the requests. The following table shows the return codes used by the Corporate APIs.
| HTTP Status Code | Text | Description of the code |
|---|---|---|
| 200 | OK | Request was fulfilled |
| 201 | OK | The request has been fulfilled and resulted in a new resource being created. Code 201 is returned after the successful creation of a new access authorization or payment object |
| 400 | Bad Request | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing). |
| 401 | Unauthorized | Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
| 403 | Forbidden | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. |
| 404 | Not Found | The requested resource could not be found but may be available in the future. |
| 405 | Method not allowed | A request method is not supported for the requested resource. |
| 409 | Conflict | Indicates that the request could not be processed because of conflict in the current state of the resource. |
| 415 | Unsupported Media Type | The request entity has a media type which the server or resource does not support. |
| 500 | Internal Server Error | A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
| 503 | Service Unavailable | The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state. |
| 504 | Gateway Timeout | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server. |
API response codes
API response HTTP codes are returned within the JSON object. These codes can be divided into four categories.
-
2xx Success
-
3xx Redirection
-
4xx Client errors
-
5xx Server error.
The return codes used in the APIs are covered here or in the API reference
API versioning
The API is versioned by the version number in the URL, for example, if the URL is:
https://open.nordea.com/corporate/v2/some/api/endpoint
Then the version of the API and endpoint in question is version 2 (v2). When new versions are released, the version numbering will be incremented, that means, next version will have the following URL:
https://open.nordea.com/corporate/v3/some/api/endpoint
When version 3 is released, the old version 2 will still be available - although possibly deprecated, meaning version 2 will still work until removed. When APIs reach deprecated availability status, the application should be updated to use the newer version of the APIs as soon as possible.
Note: The API version number in the URL indicates the major version of the API. There can be minor updates to the APIs which do not change the major version number. The major version changes only when large changes are made which break backward compatibility.
Connecting to the API
To be able to use and connect to the API there are few requirements.
-
Application has to be created.
-
Client ID is required.
-
Client Secret is required.
-
Access Token is required.
The Client ID and Client Secret are generated after the application is created on My apps page. The Client ID and Client Secret can be found when clicking the app icon after the app is created. The Access Token must be retrieved by using the Authentication API endpoints, see the authentication API documentation for how to do this.
When making requests, the Client ID, Client Secret, and Access Token are sent in a header of each request.
See the examples section of any API to learn how these headers are sent.
Note that both, Client ID and Secret are always sent, in every single request that is made towards the API
If the Client Secret is lost or leaked, it can be regenerated by clicking the reset button on the apps page.
Note that the X-IBM-Client-Id and X-IBM-Client-Secret parameters are only used by the client application. Also, the access token is made available for the client, the access token should be stored by the client application, and it should not be given to the end-user.
API Overview
RESTful APIs like these one use HTTP methods when performing actions to fetch, modify, add or delete resources. Here we list methods used by this API.
-
GET- This method reads a resource and returns it. It returns 200 on success. -
POST- This method creates a new resource. It returns 201 on success. -
PUT- This method requests that the entity provided is stored in the URI provided. It returns 200 on success. -
DELETE- This method deletes the resource identified by URI. It returns 200 on success.
Following table shows which methods are supported by Retail Finance APIs.
| API | Availability Level | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|
| Authentication | Stable | X | - | - | - |
| Credit List API | Stable | X | - | - | - |
| Application With Purchase | Stable | - | X | - | - |
| Purchase | Stable | - | X | - | - |
| Loan Calculator | Stable | - | X | - | - |
API endpoints
| API | End Point |
|---|---|
| Authentication | /retail-finance/authentication/v2/consumers/authorize |
| Credit List | /retail-finance/credits/v2/credits |
| Application With Purchase | /retail-finance/credit-applications/v2/application-with-purchases |
| Purchase | /retail-finance/credit-applications/v2/purchases |
| Loan Calculator | /retail-finance/credit-applications/v2/interest-calculations |
Common issues
In this section, we describe some of the common issues that the users of the API face. This section is updated periodically.
Client secret is lost If you lose the client secret, you must generate a new one in the developer portal.
Application ID is not registered If you receive this error when making a request, please double-check in the developer portal that you are subscribed to the APIs you wish to use.
API returns 500 and not a meaningful error message In this case, most commonly, the request or request payload is invalid. Please check the request you are making carefully.
Postman collection is not working properly First, please check that the client secret and client id is set properly. Next, ensure that Automatically follow redirects is disabled in Postman, for this to work, you need to have the interceptor extension installed and activated for Postman. See capturing http requests and issues/2722.