Accounts & Cards flow

Step-by-step guide to help you retrieve balances, transactions etc via our Account and Card Account Information APIs.

 

General information

This page describes the details of how to get access to a PSU's account information, via Handelsbanken's PSD2 APIs.

An overview of the steps in these guidelines: Account and Card Information - Authorization flow chart

The guidelines on this page are only valid for the Live environment.

For Sandbox testing, please follow this guide (as there are differences): Sandbox testing for Accounts & Cards (AISP)

Live Data Gateway Host URL

When using our APIs in the Live environment, please ensure that the below base URL is used in the calls.

 

Step-by-step guide (for Accounts & Card Accounts)

 

Step 1: Request Client Credential Grant (CCG) token

The authorization process starts with requiring a Client Credentials Grant (CCG).
This is an access token that is specific for the requesting client-id and scope, e.g. the registered application and scope AIS.

Request

curl -X POST https://api.handelsbanken.com/mlurd/oauth2/token/1.0 \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=AIS&client_id=f31b7318-8f21-4eaf-8817-6b5e4e02d6bc'

The above request is an example against the Live environment.

See below for the type of information that needs to be in your request. Please make sure you replace the example values with the correct ones in your request.

Please also refer to the API documentation for the full definitions, descriptions and codes Client Credentials Grant (OAuth 2.0)

Parameter Description Example
grant_type Type of token request - CCG in this case. Allowed value: “client_credentials”.
Mandatory
client_credentials
scope A static scope with one or several values. For the Account & Card Information APIs, "AIS" must be the scope.
Several scopes can be added if you plan on using our other APIs, but they must be divided by whitespace characters.
Mandatory
AIS


AIS PIS CBPII
client_id The unique identifier of your registered application.
Mandatory
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc

Response

This is what the response looks like when the CCG token has been successfully created. This CCG token is valid for 24 hours.
With this access token, you can call the POST /consents endpoint of the Consents API (Step 2), to acquire AIS consents for the PSUs (for as long as the returned expiry time allows).

HTTP/1.1 200 OK
{
"access_token": "QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4",
"expires_in": 123456,
"token_type": "Bearer"
}

The above response is an example.

Parameter Description Example
access_token The returned CCG token, associated with your registered application for the scope(s) you have requested.
QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4
expires_in Number of seconds the access_token is valid. Always use this value rather than hardcoding a set time value (e.g. 24h). e.g. 123456 (please check what you receive in the response)
token_type Always the value ”Bearer”. Bearer

 

Step 2: Initiate consent (using CCG‐token)

With the CCG, an end user consent can be initiated. The returned ID should be used in the next step (Step 3), when the end user (PSU) signs the consent.

Request

curl -X POST https://api.handelsbanken.com/openbanking/psd2/v1/consents\
--key <Your private key file> \
--cert <Your public cert file> \
-H 'Authorization: Bearer QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Country: <ISO 3166-1 country code>' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
-H 'PSU-Corporate-ID: <Corporate Identification>' \
-H 'PSU-Corporate-ID-Type: <Corporate ID Type;' \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-d '{"access":"ALL_ACCOUNTS"}'

The above request is an example against the Live environment.

See below for the type of information that needs to be in your request. Please also refer to the API documentation for definitions, descriptions and codes Consents API

The client-id example value must be replaced with your application's client-id and the authorization header must contain your CCG access token from Step 1: Request Client Credential Grant token.

Parameter Description Example
Authorization The CCG access token (from Step 1).
Mandatory.
Bearer
QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4
Country ISO 3166-1 country code.
Mandatory.
SE
TPP-Request-ID Unique identifier for the request.
Mandatory.
c8271b81-4229-5a1f-bf9c-758f11c1f5b1
TPP-Transaction-ID Unique identifier for the transaction.
Mandatory.
6b24ce42-237f-4303-a917-cf778e5013d6
PSU-Corporate-ID Corporate Identification (known by the customer). Mandatory for Corporate PSUs only. If left blank, we assume the customer is an Individual.
For GB Corporate customers the value should be set to UNKNOWN.
SE: 10 digit organisation number
FI: 10-11 digit business identity code
GB: 'UNKNOWN'
NL: 6 digit corporate number
LU: 10 digit organisation number
PSU-Corporate-ID-Type Corporate Identification type. Mandatory for Corporate PSUs only. Supported value is 'BANK'. BANK
X-IBM-Client-Id Your registered application's client-id.
Mandatory.
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc
access Accounts/Card Accounts to be covered by the consent. Supported value is 'ALL_ACCOUNTS'.
Mandatory.
ALL_ACCOUNTS

Response

This is what the response looks like when the consent initiation for Account / Card Account Information has been done. A successful response will include a consent ID as well as links to endpoints for continuing the authorization process (next step) with the signing of the consent by the end user (PSU).

HTTP/1.1 200 OK {
 "consentId": "22aa3559-577d-441c-b9e6-664ac3311a3e",
 "consentStatus": "RECEIVED",
 "scaMethods": [
    {
"_links": { "authorization": [

                {

               "href": "https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0",
               "name": "authorize_1.0",
                "type": "application/x-www-form-urlencoded"

                 }

              ]

    },
"scaMethodType": "REDIRECT"

}

]
"_links": { "authorization": [

             {

             "href": "https://api.handelsbanken.com/mlurd/decoupled/mbid/initAuthorization/2.0",
             "name": "decpld_mbid_1.0",
             "type": "application/json"

             }

          ]

    },
"scaMethodType": "DECOUPLED" },

The above response is an example.

Parameter Description Example
consentId The consent ID that has been created to be used later on when the PSU signs it.
22aa3559-577d-441c-b9e6-664ac3311a3e
scaMethods.[]._links.authorization.[].href Link to authorization endpoint for starting the PSU authorization process. Redirect:
https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0
Decoupled:
https://api.handelsbanken.com/mlurd/decoupled/mbid/initAuthorization/2.0
scaMethods.[].scaMethodType The type of PSU authorization method. REDIRECT
DECOUPLED

Important: In the Live environment, the link to the authorization endpoint is different than in Sandbox. See here for the difference:

- For Redirect:
Sandbox = "https://sandbox.handelsbanken.com/openbanking/redirect/oauth2/authorize/1.0"
Live = "https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0"

- For Decoupled:
Sandbox = "https://sandbox.handelsbanken.com/openbanking/decoupled/mbid/initAuthorization/1.0"
Live= "https://api.handelsbanken.com/mlurd/decoupled/mbid/initAuthorization/2.0"

 

Step 3: Consent Authorization Grant using ACG or DG

This is the step where the end user (PSU) signs the consent.

For the authorization process, the end user (PSU) should be able to choose among the type of authorization flows that are applicable to the specific country and customer type (Individual or Corporate customer). The applicable types of authorization flows are returned, including the URL to initiate the process, in the response of the consent initiation (Step 2: Initiate consent using CCG token).

On the successful completion of these processes, you will receive an access token which will be an Authorization Code Grant (ACG) for the Redirect Authorization flow or Decoupled Grant (DG) for the Decoupled Authorization flow. With this access token, you will be able to call the endpoints of the Account and Card Account APIs in the next step.

In the below links you can find more detailed technical information and the next steps so you can implement the different authorization processes.

SCA Redirect

SCA Decoupled

Important: not all countries support both SCA methods. See here for which methods are applicable per country SCA Methods

 

 

Step 4: Call the Account / Card Account Information APIs

After you have implemented the authorization process (in the previous step), the endpoints of the Account / Card Account Information APIs may now be called with either the ACG or the DG access token.

Please note: the access token from the previous step (Step 3) should be sent in the “Authorization” HTTP-header.

In the below links, you can find our API documentation (definitions, descriptions and codes):

Account Information API documentation

Card Account Information API documentation

and country specific information (which contains important business rules per country):

Country specific Account rules

Country specific Card Account rules

 

Sandbox test data

The Sandbox test data is designed to provide app development support, so we have made variety of fictitious PSUs and their accounts available to test.

The account profiles contain different response data with common account and transaction data. We have also included data that contains the maximum field lengths and number of transactions for each customer category (Individuals and Corporates) per country.

Sandbox testing for Accounts & Cards (AISP)