Decoupled Authorization flow

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

SCA Decoupled

General information

This page describes the details of how to implement PSU authorization with the SCA method Decoupled (with Mobile BankID), via Handelsbanken's PSD2 APIs. Please note that this is only available to Swedish customers. When the process is successfully completed, you will receive a Decoupled Grant access token (DG).

An overview of the steps in these guidelines can be found here: SCA Decoupled - 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 URL is used in the calls.

Step-by-step guide (for Decoupled Authorization)

•     
• StepsDescription
•     
• 1. Initiate authorization The response from the initiation resource will contain either a so called autoStartToken (when same device) or a QR code (when different devices).
•     
• 2. Start BankID appAuto/Manual start of BankID app.
•     
• 3. Request Decoupled Grant tokenRetrieve a DG token.
•     
• 4. Access API resources with Decoupled Grant tokenAccess the functional APIs by using the DG token in the authorization header.
•     
• 5. Refresh tokenRefresh a DG token.
•     
• 6. Cancel tokenCancel the ongoing verification.
•     
• 7. DocumentationDocumentation for decoupled flow.

Step 1: Initiate authorization

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

Request

The above response is an example against the Live environment.

Description of response parameters.

Step 2: Start BankID app

This step is out of scope when it comes to the responsibility and support from Handelsbanken. Instead, please refer to the "Integrationsguide" found here: BankID's technical support page

The BankID app can be started in different ways, but in our case, the autostart token from the previous step must be used either by launching the BankID app on the same device (see chapter 3 in BankID's guidelines) or by using a QR code when the BankID app is launched on another device (see chapter 4 in Bank ID's guidelines).

Step 3: Request Decoupled Grant token

The final step in the DG authorization process is to retrieve an access token, by calling the Decoupled Grant API

If the end user (PSU) cancels the authorization, the session towards Mobile BankID will be cancelled. To complete the authorization, a new session towards Mobile BankID needs to be initiated.

HTTP status 400, 500 or 503 can be returned. Error handling is SHB specific but inspired by the Oauth2 specification. Status 500 Internal Server Error and 503 Service Not Available is returned with an empty body: "{}".

The table below describes the error situations when status code 400 is returned.

Step 4: Access API resources with Decoupled Grant token

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

Using the DG 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 Decoupled 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 Decoupled Grant access token (DG) expires, a new DG can be requested using the refresh token that was issued together with the DG (Step 3: Request Decoupled Grant token). Typically, this should be made when a DG token has expired (after 24 hours), but the consent is still valid. This way, you don't need the PSU to grant a new consent.

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.

The above response is an example.

Step 6: Cancel token

Cancel an ongoing verification. A TPP that provides a possibility for a PSU to cancel the verification in its user interface, can use this resource to cancel the transaction in the BankID enviroment. If the PSU decides to confirm again it may fail because the PSU already has an ongoing transaction, this situation will be prevented if cancel is implemented. The resource must only be invoked for transactions that are still alive (a initAuthorization must have been successful and no previous error from Authorization Server from token call).

Response

Response will always try to return 200 OK, regardless if the cancellation was successful or not. The response body will always be a empty json object.

7. Documentation

Documentation for the decoupled authorization flow, describes the techincal details for the this authorization flow.

Link to document Decoupled implementation document