Maintenance Sunday 6th October

On Sunday 6th October from 06:00-09:00 CET, Handelsbanken online services, including our PSD2 APIs, for Sweden and Finland, will experience issues with card information during that time period, purchases will still be able to be executed during the maintenance period.

Redirect Authorization flow

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

SCA Redirect

 

 

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)

 

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.

curl -X GET https://secure.handelsbanken.com/mlurc/oauth2/authorize/1.0?response_type=code& scope=AIS%3A20014a81-520f-4287-bde8-11f1cdaaa2ba
& client_id=bb089f8c-8a28-4455-88ad-a572c9f794b0&state=bc4b933c-bfc2-44c8-b858-eba90f559f91
&redirect_uri=http%3A%2F%2FYourCallbackServer%2Fredirect%2Fresult \
-H 'Accept: application/json'

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

http://YourCallbackServer/redirect/result?state=bc4b933c-bfc2-44c8-b858-eba90f559f91&code=02e31fc1-8320-4952-bba9-8ad99fc80941

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. 

http://YourCallbackServer/redirect/result?state=bc4b933c-bfc2-44c8-b858-eba90f559f91&error=invalid_request&error_description=Something+went+wrong

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

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=authorization_code&scope=AIS%3A20014a81-520f-4287-bde8-11f1cdaaa2ba &client_id=bb089f8c-8a28-4455-88ad-a572c9f794b0&code=02e31fc1-8320-4952-bba9-8ad99fc80941&redirect_uri=http%3A%2F%2FYourCallbackServer%2Fredirect%2Fresult'

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.

HTTP/1.1 200 OK {
"access_token":"QVQTI4OWMtZGRlYy00ZDBmLTg3YTktzYxZjk0NGZm",
"expires_in":123456,
"token_type":"Bearer",
"refresh_token":"UlQ6NNWMtNWQ3YS00MWUyLTg3NTk5NmUxZDkwNTll"
}

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

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=refresh_token&refresh_token=UlQ6NNWMtNWQ3YS00MWUyLTg3NTk5NmUxZDkwNTll&client_id=bb089f8c-8a28-4455-88ad-a572c9f794b0 '

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.

HTTP/1.1 200 OK {
"access_token":"QVQ6MGQ2YmYtMmZjOC00Yzg3LzYyOGU0NTg5YmM3",
"expires_in":86400,
"token_type":"Bearer"
}

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