Confirmation of Funds Access Authorization API specific documentation

Changes from the previous version

This is the changelog of the Access Authorization API. The topmost item is the latest change and the API changes described in it are relative to the version directly below.

The current latest version of the API is 1.1.

Version 1.1

Three below mentioned, deprecated methods have been finally decommissioned:

• Nordea ID authentication method in offline mode (MTA_OFF)
• Mobile BankID for Norway (BANKIDM_NO)
• QR reader for Sweden (QR_RDR)

Overview of Confirmation of Funds Access Authorization (redirect) API  

Confirmation of Funds Access Authorization API consists of endpoints that enable Clients (TPP Applications) to initiate access authorization flow, whereby the customer (Resource Owner) authorizes account access. To be able to use the Confirmation of Funds Access Authorization API PSD2-regulated TPPs (Client) should have the role Card Based Payment Instrument Issuer (CBPII). Ultimately the Client receives an access token that can be used in Confirmation of Funds (COF) calls as applicable.

Note: it is assumed that, before initiating this flow, the TPP will have negotiated consent with the customer.

Note: the Client can also query the /assets endpoint for information on the authorized access (account and FUNDS_CONFIRMATION scope).

Note: the Client also receives a refresh token together with the access token that can be used to obtain a new access token after expiry.

How it works

To be able to use the Confirmation of Funds API, the Client needs an access token. The Client is provided with an access token after the customer (Resource Owner) has authenticated themselves and authorized access to their account.

The access token generation consists of the following steps:

1. Initiation of access authorization.

   For Denmark, Finland, Norway and Sweden use POST /funds-confirmation/authorize endpoint

2. Receipt of an authorization code.

   To get authorization code use received via the Client’s redirect URI (for Denmark, Finland, Norway and Sweden). An authorization code will be received when the Resource Owner authorizes access and is then redirected back to the Client.

   Please note that the authorization code is one-time use only and is never used or required again after it is exchanged to access token.

3. Exchange of the authorization code for an access token and a refresh token.

   The authorization code is subsequently exchanged for an access token (and associated refresh token). Use POST /funds-confirmation/authorize/token endpoint for Denmark, Finland, Norway and Sweden.

   Please note: The refresh token one time usage can be used to obtain a new access token after its expiry.

Once an access token has been received, the authentication and authorization flow is complete.

API endpoints

The Confirmation of Funds Access Authorization API has the following endpoints:

Redirect Confirmation of Funds Access Authorization flow

For Denmark, Finland, Norway and Sweden:

We also provide the following additional endpoints for the TPPs.

The endpoint usage is described in more detail below.

Redirect Confirmation of Funds Access Authorization flow

The redirect Confirmation of Funds Access Authorization flow, available in Denmark, Finland, Norway and Sweden, enables the Client to get a Y/N response whether Resource Owner has enough funds on their account for a particular payment amount, subject to the Resource Owner’s authorization. The Client calls the /funds-confirmation/authorize endpoint to initiate this flow, from which the customer is directed to authenticate themselves for which the agreed access should apply. The Client can then acquire an access token to use in the Confirmation of Funds API.

Note: Before initiating this flow, it is assumed the Client will have negotiated consent with the Resource Owner. The consent can be life-long.

The framework has four roles:

• Resource Owner - payment account holder with Nordea.
• Client - TPP, owner of the Client Application consuming Nordea’s Open Banking API.
• Nordea Open Banking (API).
• Nordea User Interface, enabling the Resource Owner to authenticate themselves and if requested by the TPP, to select accounts for which the agreed access should apply.

The Resource Owner is the person giving the consent to the Client’s application to access its payment account information for one of its payment account and an agreed duration. The Client is the owner of the Client application which is requesting this access.

The following diagram illustrates how the flow works:

1. Consent is negotiated and agreed between the customer (Resource Owner) and the TPP with CBPII role (Client). Amongst other information that makes up explicit consent, this will include the scope of access required and the duration this access has been agreed.
2. The Client calls Nordea’s /funds-confirmation/authorize endpoint, passing, amongst other mandatory and optional parameters, the agreed access scope and duration.
3. Nordea responds with an acknowledgment.
4. The Resource Owner is redirected to Nordea, where they authenticate using their Nordea credentials (for example, via Nordea ID in Finland, MitID in Denmark, Mobile BankID in Sweden, and BankID in Norway).
5. The Resource Owner is shown the access scope, duration and the account number for which this access should apply, and clicks ‘Continue’.
6. Whilst the Resource Owner is being redirected back to the Client’s App, Nordea responds to the Client through the redirect URI with an OAuth2-style auth code.
7. The Client can exchange this short-lived auth code for an access token (plus associated refresh token), which can be used for the Confirmation of Funds API.
8. When the access token has expired, a new access token can be obtained by calling /funds-confirmation/authorize/token using the received refresh token. The refresh token is long-living but one-time-only use.

Redirect - How the flow looks like for the customer

This example illustrates a scenario where a Swedish customer is going through the Redirect Confirmation of Funds Access Authorization flow and chooses to use their Mobile BankID as an authentication method.

TPP calls POST /personal/v1/funds-confirmation/authorize endpoint and provides the following input parameter in addition to all of the mandatory parameters.

• account_number

1. The customer is redirected to Nordea, to authenticate themselves.
2. In this illustration, the customer selects Mobile BankID Sweden as an authentication method.

Note: If authentication_method is provided, the method is pre-selected for the customer.

3. The customer enters their BankID credentials.
4. The customer is redirected briefly back to Nordea UI.

5. The customer receives an indication of successful authentication.
6. The customer is automatically redirected back to the TPP application.

Note: authentication_method parameter can be used to further reduce the interaction of the user in the Nordea User Interface. Please see Swagger’s definition of the interface for more information.

Redirect - Prerequisites

To be able to use Confirmation of Funds APIs 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 the My apps page. The Client ID and Client Secret can be found when clicking the app icon after the app is created.

When making requests, the Client ID, Client Secret, and access token are sent in a header of each request. Note that both the Client ID and Secret are always sent, in every single authorization Confirmation Of Funds request.

Here is an example of how the parameters look in the request header:

...
other Header data omitted
...
Authorization: Bearer <ACCESS-TOKEN>
...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

If the Client Secret is lost or leaked, it can be regenerated by clicking the reset button from the apps page. See the examples section of any API to learn how these headers are sent.

Note that the X-IBM-Client-Id and X-IBM-Client-Secret parameters are only used by the Client (TPP Application).

Redirect - Confirmation of Funds Access Authorization API

In the previous section, we described the requirements to connect to the Confirmation of Funds API. The Client ID and Client Secret are parameters that are configured to the TPP, and they are never exposed to the actual application customer. After they are configured, the TPP can initiate the access authorization flow to acquire an access token and a refresh token.

To receive an access token, the Client (TPP Application) and Resource Owner (customer) must first agree on consent, after which the Client:

1. The Client redirects the customer to Nordea.
2. The Resource Owner authenticates with Nordea.
3. The Resource Owner reviews requested access and authorizes access.
4. Nordea redirects the customer back to TPP.

Please note that the auth code and the refresh token are one-time use only, codes are never used or required again after they have been exchanged to access token. The refresh token can then be exchanged for a new access token when the existing access token has expired.

After the auth code has been exchanged for an access token, the authorization flow is complete and the Client (TPP Application) can start using the API.

Redirect - Initiating the authorization flow

First, the Resource Owner needs to agree on consent with the Client, and then the Client starts the process by initiating the Redirect Authorization flow. The flow can be initiated through the following endpoints:

POST /funds-confirmation/authorize

With the example body shown in the below:

{
  "account_number": "<Account number>",
  "authentication_method": "BANKID_SE",
  "country": "<country code>",
  "duration": "3600",
  "redirect_uri": "<redirect_uri>",
  "scope": "FUNDS_CONFIRMATION",
  "state": "state"
}

…plus additional optional parameters

Please refer to the Swagger definition to find optional parameters that you can add to the request, and for the different values of these parameters.

The call will return an HTTP 302 redirect code, indicating a successful redirect.

See the Access Authorization API Specific documentation for example how the OAuth flow works, it can be used through the API console or programmatically.

To clarify the value and meaning of parameters please see API Reference.

Redirect - Receiving the Auth Code

Once the Resource Owner has authorized the requested access, the Nordea Authorization Server will send an OAuth2-style auth code through the redirect_uri provided in the /funds-confirmation/authorize request. The state parameter will also be returned together with the auth code.

GET /test.com?code=<code>&state=<state>

Redirect - Token Exchange

Now that the auth code has been received, it can be exchanged for an access token and a refresh token by calling:

POST  /funds-confirmation/authorize/token

The Header includes:

...
other Header data omitted
...
-H "X-IBM-Client-Id": "<Client ID>"
-H "X-IBM-Client-Secret": "<Client Secret>"
-H "Content-Type": "application/x-www-form-urlencoded"

The example body looks like this:

Requesting an access token with an authorization_code

 
  code=<CODE>
  &redirect_uri=http://exampleuri.com/post
  &grant_type=authorization_code
 

Requesting an access token with a refresh_token

 
  refresh_token=<refresh_token>
  &grant_type=refresh_token
 

The call will return the following response:

{
 "access_token": "<access token value>"
 "expires_in": 300,
 "token_type": "Bearer"
 "refresh_token": "<refresh token value>"
}

Redirect - Token exchange with the refresh token

Now that the Refresh Token has been received, it can be exchanged for a new access token and a new refresh token.

The response above shows the token type, token expiration time in seconds, actual access token which can be used to make requests, and a refresh token which can be used to obtain a new access token after the access token duration has expired. Please also note that the auth code to retrieve the access_token will expire in 60 seconds for security reasons.