Authorization model and process

This page describes the authorization model and process of Handelsbanken's PSD2 APIs. Although the description is valid for the Live environment much of the same concepts and steps are also valid for the Sandbox environment - the main exception being that the endpoints are requested with a TPP certificate in the Live environment. At the bottom of this page you’ll find Sandbox test data which has a variety of fictitious PSUs and their accounts so you can test our APIs before going Live.

Most of the authorization endpoints follow the OAuth2-specification, with the Decoupled Authorization Flow being the exception.

Please refer to our API documentation for all endpoints, definitions, parameters and codes.

Authorization flow charts

Account and Card Information - Authorization flow chart

Payment Initiation - Authorization flow chart

Confirmation of Funds - Authorization flow chart

• StepsDescription
• 0. Enrollment and subscription(s)TPP Enrollment to enable Live data access using our Third-parties API and subscribe to the APIs.
• 1. Client CredentialsClient Credentials Grant Access Token request using the Client Credentials Grant API.
• 2. Customer ConsentInitiate End user (PSU) consent process using the appropriate consent endpoint.
• 3. End user (PSU) authorizationEnd user authorization using the available SCA Approach(es) received in the consent response.
• 4. Call the PSD2 APIsCall the functional PSD2 APIs - Account Information, Card-Account Information, Payment Initiation or Confirmation of Funds.
• Sandbox test dataTest data documentation for our PSD2 APIs - Accounts, Cards, Payments and Confirmation of Funds.

Before you start using our APIs, you'll need to have signed up / enrolled with Handelsbanken, registered your app and subscribed to our API(s). We explain the steps below as this process differs depending on whether you want to use Sandbox or Live APIs.

Sandbox

This is as simple as signing up for a free user account with us, then register an app (or multiple apps), and then subscribe to our APIs.

Live

Before you can use our APIs for Live data production, you must have received the following:

1. Authorization from a National Competent Authority to become a Third-party Provider (TPP).
2. PSD2 eIDAS certificate (QWAC) or a UK Open Banking certificate (OBWAC) from a Qualified Trust Service Provider (QTSP).

With the certificate, you can enroll with us by using our Third-Parties API then after you've enrolled, you should use the Subscriptions API to register your apps and subscribe to our APIs.

For further info on our enrollment process and accessing our Live APIs, check out our Live Data Access step-by-step guide

The authorization process starts with requiring a Client Credentials Grant (CCG). This is an access token that is specific for the requesting client (the TPP).

With this access token, a TPP can (for example) call the POST /consents endpoint of the Consents API or start a payment initiation (POST /payments) with the Payments API.

To see more details of this step, click on either of the following links (depending on which API you want to implement):

Request a Client Credentials Grant token for Accounts / Card Accounts

Request a Client Credentials Grant token for Payments

Request a Client Credentials Grant token for Confirmation of Funds

With the CCG, an end user consent can be initiated. (The consent needs to be signed by the end user in the next step).

A successful response will include a consent ID (or a payment ID for the payment flow) as well as links to endpoints for continuing the authorization process with the signing of the consent by the end user (payment service user, PSU).

To see more details of this step, click on either of the following links:

Initiate a consent for Accounts / Card Accounts using the Consents API

Initiate a payment using the Payment API

Initiate a consent for Confirmations of Funds using the Confirmations of Funds API

The end user (PSU), can choose which authorization process they want, either the Decoupled Authorization flow or Redirect Authorization flow. Their option will depend on whether the authorization flow is applicable to the specific country and whether they are an Individual or Corporate customer.

On the successful completion of these processes, you will receive an access token which will either be a Decoupled Grant (DG) or Authorization Code Grant (ACG) respectively. With this access token, you'll be able to call the endpoints of the functional APIs.

To see more details of this step, click on either of the following links:

PSU authorization of Account / Card Account Consent

PSU authorization of Payment

PSU authorization of Confirmation of Funds

The authorization process is finished and you can now call our APIs!

Account / Card Account Information APIs

Payments API

Confirmation of Funds API

The Sandbox test data is designed to provide application development support. We've created some fictitious PSUs, which have varying information relating to their accounts and payment profiles.

The account profiles contain different response data with common account and transaction data. We've also included data that contains the maximum field lengths and number of transactions for each customer category (Individuals and Corporates) per country. The payment test data provides support for different payment types and responses from the Payment endpoints.

Test Data documentation for AISP

Test Data documentation for PISP

Test Data documentation for CBPII

For guidance on how to make API requests, please follow the API Documentation (see Step 4 for the links).