Commercial Cards Access Authorization API specific documentation

Changes from the previous version

This is the changelog of the Commercial Cards 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.3.

Version 1.3

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)

Version 1.2  

KEY CHANGE: Adding note.

• Updated Overview

Version 1.1

Consent maximum duration changed to 180 days.

Overview of Commercial Cards Access Authorization (redirect) API

Commercial Cards Access Authorization API consists of endpoints that enable Clients (TPP Applications) to initiate access authorization flow, whereby Cardholder authorizes commercial card access. Ultimately the Client receives an access token that can be used in Commercial Cards API.

Note: According to the Delegated Regulation, which amends the regulatory technical standards (RTS) since 25th July 2023 maximum consent duration will change from 90 to 180 days.

Note: the Client can also query the commercial-cards/v1/assets endpoint for information on the authorized access (commercial cards).

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.

Note:

Please note that this API provides access to company data. When using this API, you need to ensure that you have received consent both from the company for which this card was issued and from the cardholder. The sole use of the API cannot ensure that you have collected company consent given that the cardholder through which you receive access is not necessarily entitled to give you consent on behalf of the company. We would therefore recommend that you use the API only in connection with an environment for which you can ensure that you have collected the necessary company consent or in any other way which secures that you have company consent for the data accessed.

How it works

To be able to use the Commercial Cards APIs, the Client needs an access token. The Client is provided with an access token after the Cardholder has authenticated themselves and authorized access to their commercial cards.

The redirect access token generation consists of the following steps:

1. Initiation of access authorization.
2. Receipt of an authorization code.
3. Exchange of the authorization code for an access token and a refresh token.
   • The refresh token can be used to obtain a new access token after its expiry.

Initiation of access authorization flow:

• For Denmark, Finland, Norway and Sweden: POST commercial-cards/v1/authorize endpoint.

The authorization code:

• For Denmark, Finland, Norway and Sweden: received via the Client’s redirect URI.

An authorization code will be received when the Cardholder 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.

Exchange of the authorization code for an access token and refresh token:

The authorization code is subsequently exchanged for an access token (and associated refresh token) via POST commercial-cards/v1/authorize/token

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

API endpoints

The Commercial Cards Access Authorization (redirect) API has the following endpoints:

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.

Commercial Cards access authorization (redirect) flow

The redirect commercial cards access authorization flow, currently available in Finland, Sweden, Denmark, and Norway, enables the Client to get access to Nordea Cardholder’s commercial cards, subject to the Cardholder’s authorization. The Client calls the commercial-cards/v1/authorize endpoint to initiate this flow, from which the Cardholder is directed to authenticate themselves and select cards if applicable, for which the agreed access should apply. The Client can then acquire an access token to use in the Commercial Cards APIs.

Note: Before initiating this flow, it is assumed the Client will have negotiated consent with the company and the cardholder.

Note: When skip_card_selection in POST commercial-cards/v1/authorize is set to “true”, then TPP can request access to all of the PSU’s commercial cards. Otherwise PSU will get list of commercial cards to select.

The framework has four roles:

• Cardholder - cardholder of commercial cards in Nordea.
• Client - TPP, owner of the Client Application consuming Nordea’s Open Banking API.
• Nordea Open Banking (API).
• Nordea User Interface, enabling the Cardholder to authenticate themselves and if requested by the TPP, to select commercial cards for which the agreed access should apply.

The Cardholder is the person giving the consent to the Client’s application to access their commercial cards information for an agreed duration. The Client is the owner of the Client application which is requesting this access. It is important to stress that the consent is between the Client and both the cardholder and company.

The following diagram illustrates how the flow works:

1. Consent is negotiated and agreed between the cardholder, the company and the TPP (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 commercial-cards/v1/authorize endpoint, passing, amongst other mandatory and optional parameters, the agreed access scopes and duration.
3. Nordea responds with an acknowledgment.
4. The Cardholder 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. Note: This step is only present if card selection is enabled for the Cardholder - The Cardholder is shown list of commercial cards to select for which this access should apply, and clicks ‘Continue’.
6. Whilst the Cardholder is being redirected back to the Client’s App, Nordea responds to the Client through the redirect URI with an OAuth2-style authorization code (code).
7. The Client can exchange this short-lived authorization code for an access token (plus associated refresh token), which can be used for the agreed Commercial Cards APIs.
8. When the access token has expired, a new access token can be obtained by calling commercial-cards/v1/authorize/token using the received refresh token. The refresh token is long-living but one-time-only use.

How the flow looks like for the PSU

This example illustrates a scenario where a Swedish PSU is going through the Commercial Cards Access Authorization (redirect) flow and chooses to use their Mobile BankID as an authentication method.

Scenario: PSU user experience without card selection step in Nordea UI.

TPP calls POST /commercial-cards/v1/authorize endpoint and provides the following optional input parameters in addition to all of the mandatory parameters.

• skip_card_selection

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

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

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

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

Scenario: PSU user experience with account selection in Nordea UI.

TPP calls POST /commercial-cards/v1/authorize without providing skip_card_selection.

The flow looks similar as in the above flow with the exception that after the PSU has authenticated,

1. The PSU is redirected to Nordea UI to select the commercial cards they wish to grant access to.

2. After this selection is done, they can continue the flow and return back to TPP application.

Note: authentication_method can be used together with skip_card_selection to further reduce the interaction of the customer in the Nordea User Interface.

Note: authentication_method parameter can be used to further reduce the interaction of the user in the Nordea User Interface. When passing this parameter the authentication method is pre-filled for the PSU. Please see Swagger’s definition of the interface for more information.

Prerequisites

To be able to use and consume AIS and PIS for Commercial Cards 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 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).

Commercial Cards Access Authorization API

In the previous section, we described the requirements to connect to the Commercial Cards APIs. 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) must first agree on consent with the Company and the Cardholder , after which the Client:

1. The Client redirects the customer to Nordea.
2. The Cardholder authenticates with Nordea.
3. If card selection is enabled - The Cardholder reviews requested access, selects cards, and authorizes access.
4. Nordea redirects the customer back to TPP.

Please note that the authorization code (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 authorization code has been exchanged for an access token, the authorization flow is complete and the Client (TPP Application) can start using the API.

Initiating the authorization flow

First, the Client needs to agree on consent with the Company and the Cardholder, and then the Client starts the process by initiating the Commercial Cards Authorization flow. The flow can be initiated through the following endpoint:

POST /commercial-cards/v1/authorize

With the URL parameters including those shown in the example below:

/authorize?
state=123
 &client_id=<CLIENT_ID>
 &redirect_uri=https:%2F%2Fexampleuri.org%2Fpost
 &scope=COMMERCIAL_CARDS_INFORMATION, COMMERCIAL_CARDS_TRANSACTIONS
 &duration=500
 &country=<country code>

…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.

Receiving the Authorization Code

Once the Cardholder has authorized the requested access, the Nordea Authorization Server will send an OAuth2-style authorization code (code) through the redirect_uri provided in the commercial-cards/v1/authorize request. The state parameter will also be returned together with the authorization code.

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

Token Exchange

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

POST  /commercial-cards/v1/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 (placed in code field)

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

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.