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