Redirect Authorization flow

Here you'll find the steps required to authorize the end user with the redirect grant, for Handelsbanken's PSD2 APIs.

 

 

General information

This page describes the details of how to implement PSU authorization with the SCA method Redirect for our PSD2 APIs. To read more about which SCA methods are supported for the countries we operate in, please check here: SCA Methods

When the PSU authorization process is successfully completed, you will receive an Authorization Code Grant access token (ACG).

An overview of the steps in these guidelines can be found here: SCA Redirect - Authorization flow chart

These guidelines are valid for the Live environment and Sandbox environment, however, please note that in the Live environment, the endpoints are requested with a TPP certificate (issued by a QTSP).

Sandbox Gateway Host URL

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

Live Data Gateway Host URL

When using our APIs in the Live environment, please ensure that the below base URLs are used in the calls. Either of the below URLs are used depending on which endpoint is called - please refer to the example requests for guidance on when to use them.

 

Step-by-step guide (for Redirect Authorization)

• StepsDescription
• 1. Initiate authorizationInitiation of the authorization process, where the PSU will be presented with the Handelsbanken dialog for redirect authorization.
• 2. The redirect requestThe request being made to your specified redirect URI.
• 3. Request Authorization Code Grant tokenRetrieve an ACG token.
• 4. Access API resources with Authorization Code Grant tokenAccess the functional APIs by using the ACG token in authorization header.
• 5. Refresh tokenRefresh an ACG token.

 

Step 1: Initiate authorization

The PSU authorization process starts with an initiation step against Handelsbanken's Authorization Code Grant API

Request

This is a request that preferably should be called from the end user (PSU) client's browser. It contains a number of URL-encoded query parameters. The request must contain your application's client-id and the scope of the authorization code grant. This scope is a single AIS / PIS / CBPII combined with your consent-id (for Account / Card Account Information) or payment-id (for Payment Initiation).

Please note: the URL used below is only an example. The correct URL to use, is returned in the response message for consent or payment initiation.

The above request is an example against the Live environment.

Parameter	Description	Example
response_type	The type of response, should always be "code". Mandatory.	code
scope	"AIS" for Account / Card information plus consent-id "PIS" for Payments plus payment-id "CBPII" for Confirmation of Funds plus consent-id. Mandatory.	AIS%3A20014a81-520f-4287-bde8-11f1cdaaa2ba PIS%3A495e37a4-c896-4370-8fbe-14ab48522956 CBPII%3Afad82d13-02df-4656-8e2c-6c2590322412
client_id	Your application's client-id. Mandatory.	bb089f8c-8a28-4455-88ad-a572c9f794b0
state	An identifier chosen by you (the TPP), to be able to identify the current transaction. This will be provided in the call to your redirect URI. Mandatory.	bc4b933c-bfc2-44c8-b858-eba90f559f91
redirect_uri	This is the callback URI to your own service, that will be called after the PSU finishes authorizing themselves with the Supported Authentication Method for Redirect. Here you can see which type is applicable per country SCA Methods Please be aware that this must be the same URI that you used when registering your app (see Step 3, Live Data Access guidelines). Mandatory.	http%3A%2F%2FYourCallbackServer%2Fredirect%2Fresult

Response

The response should preferably be handled by the (end user) PSU client's browser. It works in the way that the response is returned with a HTTP code 302 and with a Location header set to the Handelsbanken dialog for redirect authorization. This has the effect that the PSU is redirected to this dialog and can perform the authorization.

When the authorization is successfully finished, your redirect URI will be called with query parameters of state (from the request) and an authorization code to be used in Step 3: Request Authorization Code Grant token.

Errors

There are two types of error situations that can occur as a result of failure in this authorization request:

1. A static error page is returned. This happens for two reasons:
- The client_id is invalid.
- The redirect_uri does not match the URI you supplied when registering your app.

2. For all other errors (for example, incorrect scope), a redirect (HTTP 302 and Location header set) will instead be made to your registered redirect URI, with the query parameters "error" and "error_description", so you can choose your own way of informing the end user (PSU) what went wrong.

 

Step 2: The redirect request

This is an example of a successful request (i.e. the PSU has made a successful authorization) against your own "callback service" (just to give you an idea of how to handle this).

Parameter	Description	Example
state	The identifier that you provided in the authorize request (Step 1), to identify the current transaction. Mandatory.	bc4b933c-bfc2-44c8-b858-eba90f559f91
code	An authorization code to be used in Step 3. Mandatory.	02e31fc1-8320-4952-bba9-8ad99fc80941

Errors

Here is also an example of an error that might be returned to you if the authorization server doesn't approve your request in Step 1: Initiate authorization, or the end user (PSU) failed / cancelled the authorization. 

Parameter	Description	Example
state	The identifier that you provided in the authorize request (Step 1), to identify the current transaction. Mandatory.	bc4b933c-bfc2-44c8-b858-eba90f559f91
error	Type of error: invalid_request - the request is not approved. access_denied - PSU failed / cancelled the authorization. Mandatory.	invalid_request access_denied
error_description	Detailed description of what went wrong (plus-signs replace whitespaces). Optional.	Something+went+wrong

If the end user (PSU) cancels the authorization, they will be returned to the page that allows them to “ Choose signing method ”. If the user cancels on the "Signing Method" page, they will be redirected back to your (TPP) page by a call to the above URL with "error" parameter set to "access_denied".

 

Step 3: Request Authorization Code Grant token

The final step in the ACG authorization process is to retrieve an access token, by calling the Authorization Code Grant API

Request

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.

Parameter	Description	Example
grant_type	The type of token call. Should be "authorization_code". Mandatory.	authorization_code
scope	"AIS" for Account / Card information plus consent-id "PIS" for Payments plus payment-id "CBPII" for Confirmation of Funds plus consent-id. Mandatory.	AIS%3A20014a81-520f-4287-bde8-11f1cdaaa2ba PIS%3A495e37a4-c896-4370-8fbe-14ab48522956 CBPII%3Afad82d13-02df-4656-8e2c-6c2590322412
client_id	Your application's client-id. Mandatory.	bb089f8c-8a28-4455-88ad-a572c9f794b0
code	The authorization code from Step 2. Mandatory.	02e31fc1-8320-4952-bba9-8ad99fc80941
redirect_uri	This is the callback URI to your own service, that will be called after the PSU finishes authorizing themselves with the Supported Authentication Method for Redirect. Here you can see which type is applicable per country SCA Methods Please be aware that this must be the same URI that you used when registering your app (see Step 3, Live Data Access guidelines). Mandatory.	http%3A%2F%2FYourCallbackServer%2Fredirect%2Fresult

Response

This is what the response looks like when an access token has been successfully retrieved from the authorization server.

The above response is an example.

Parameter	Description	Example
access_token	The access token to be used in Authorization header in the coming requests against the endpoints of the functional APIs (see Step 4 below). Note! This token can only be used for the particular scope+PSU consent, that was given at initiation of the authorization in Step 1.	QVQTI4OWMtZGRlYy00ZDBmLTg3YTktzYxZjk0NGZm
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
refresh_token	A token that can be used when the access_token has expired, but the consent is still valid. This way, you don't need the PSU to grant a new consent. See Step 5 for how to do this.	UlQ6NNWMtNWQ3YS00MWUyLTg3NTk5NmUxZDkwNTll

 

Step 4: Access API resources with Authorization Code Grant Token

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

Using the ACG access token, the endpoints of the functional APIs can be called and you can retrieve balances and transactions (using the Account and Card Information APIs) or initiate and execute a payment (using the Payment Initiation API) or check availability of funds (using the Confirmation of Funds API).

Please note: the access token from the previous step (Step 3: Request Authorization Code Grant token) is sent in the “Authorize” HTTP-header.

See more details about this step in the links below:

Accounts & Cards - Step 4: Call the Account / Card Account Information APIs

Payments - Step 4: Request payment execution

Confirmation of Funds - Step 4: Validate consent (using ACG/DG token)

 

Step 5: Refresh token

**Refresh tokens are only issued in the Authorization flow for the Account/Card-Account Information requests.**

If the Authorization Code Grant access token (ACG) expires, a new ACG can be requested using the refresh token (which is valid for 180 days) that was issued together with the ACG (Step 3: Request Authorization Code Grant token). Typically, this should be made when an ACG token has expired (after 24 hours), but the consent is still valid, so you don't need the PSU to grant a new consent.

Request

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 the full definitions, descriptions and codes Refresh Token Grant (OAuth 2.0)

Please make sure you replace the example values with the correct ones in your request.

Parameter	Description	Example
grant_type	The type of token call. Should be "refresh_token". Mandatory.	refresh_token
refresh_token	The refresh token from Step 3. Mandatory.	UlQ6NNWMtNWQ3YS00MWUyLTg3NTk5NmUxZDkwNTll
client_id	Your application's client-id. Mandatory.	bb089f8c-8a28-4455-88ad-a572c9f794b0

The above response is an example.

Response

This is what the response looks like when an access token has been successfully retrieved from the authorization server.

The above response is an example.

Parameter	Description	Example
access_token	The access token to be used in Authorization header in coming requests against the endpoints of the functional APIs (see Step 4 above). Note! This token can only be used for the particular scope+PSU consent, that was given at initiation of the authorization in Step 1.	"QVQ6MGQ2YmYtMmZjOC00Yzg3LzYyOGU0NTg5YmM3"
expires_in	Number of seconds the access_token is valid. Always use this value rather than hardcoding a set time value (e.g. 90 days).	e.g. 123456 (please check what you receive in the response.)
token_type	Always the value ”Bearer”.	Bearer

 

 

 

 

Step 6: Sandbox and testing.

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.

Test Data documentation decoupled authorization flow