This page describes the details of how to implement PSU authorization with the SCA method Redirect (using Handelsbanken's card and card reader), via our PSD2 APIs. When the 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.

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

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

curl -X GET https://secure.handelsbanken.com/bb/gls5/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'

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

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

If the end user (PSU) cancels the authorization, they will be returned to the page that allows them to “Select 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".

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

curl -X POST https://api.handelsbanken.com/bb/gls5/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'

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

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 Information API) or initiate and execute a payment (using the Payment Initiation 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:

Account / Card Account Information

Payment Execution

Confirmation of Funds

**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 90 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.

curl -X POST https://api.handelsbanken.com/bb/gls5/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'

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.

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