Technical Guidelines (overall)
Here you'll find a step-by-step guide, from enrolling with us as a TPP to using our APIs, in Sandbox or in Live.
General information
Authorization model and process
This page describes the authorization model and process of Handelsbanken's PSD2 APIs. Although the description is valid for the Live environment much of the same concepts and steps are also valid for the Sandbox environment - the main exception being that the endpoints are requested with a TPP certificate in the Live environment. At the bottom of this page you’ll find Sandbox test data which has a variety of fictitious PSUs and their accounts so you can test our APIs before going Live.
Most of the authorization endpoints follow the OAuth2-specification, with the Decoupled Authorization Flow being the exception.
Please refer to our API documentation for all endpoints, definitions, parameters and codes.
Authorization flow charts
Account and Card Information - Authorization flow chart
Payment Initiation - Authorization flow chart
Confirmations of Funds - Authorization flow chart
Step-by-step guide
- StepsDescription
- 0. Enrollment and subscription(s)TPP Enrollment to enable Live data access using our Third-parties API and subscribe to the APIs.
- 1. Client CredentialsClient Credentials Grant Access Token request using the Client Credentials Grant API.
- 2. Customer ConsentInitiate End user (PSU) consent process using the appropriate consent endpoint.
- 3. End user (PSU) authorizationEnd user authorization using the available SCA Approach(es) received in the consent response.
- 4. Call the PSD2 APIsCall the functional PSD2 APIs - Account Information, Card-Account Information, Payment Initiation or Confirmation of Funds.
- Sandbox test dataTest data documentation for our PSD2 APIs - Accounts, Cards, Payments and Confirmation of Funds.
Step 0: TPP enrollment and API subscription(s)
Before you start using our APIs, you'll need to have signed up / enrolled with Handelsbanken, registered your app and subscribed to our API(s). We explain the steps below as this process differs depending on whether you want to use Sandbox or Live APIs.
Sandbox
This is as simple as signing up for a free user account with us, then register an app (or multiple apps), and then subscribe to our APIs.
Live
Before you can use our APIs for Live data production, you must have received the following:
- Authorization from a National Competent Authority to become a Third-party Provider (TPP).
- PSD2 eIDAS certificate (QWAC) or a UK Open Banking certificate (OBWAC) from a Qualified Trust Service Provider (QTSP).
With the certificate, you can enroll with us by using our Third-Parties API then after you've enrolled, you should use the Subscriptions API to register your app(s) and subscribe to our API(s).
For further info on our enrollment process and accessing our Live APIs, check out our Live Data Access step-by-step guide
Step 1: Client Credentials Grant
The authorization process starts with requiring a Client Credentials Grant (CCG). This is an access token that is specific for the requesting client (the TPP).
With this access token, a TPP can (for example) call the POST /consents endpoint of the Consents API or start a payment initiation (POST /payments) with the Payments API.
To see more details of this step, click on either of the following links (depending on which API you want to implement):
Request a Client Credentials Grant token for Accounts / Card Accounts
Request a Client Credentials Grant token for Payments
Request a Client Credentials Grant token for Confirmation of Funds
Step 2: Initiate end user (PSU) consent
With the CCG, an end user consent can be initiated. (The consent needs to be signed by the end user in the next step).
A successful response will include a consent ID (or a payment ID for the payment flow) as well as links to endpoints for continuing the authorization process with the signing of the consent by the end user (payment service user, PSU).
To see more details of this step, click on either of the following links:
Initiate a consent for Accounts / Card Accounts using the Consents API
Initiate a payment using the Payment API
Initiate a consent for Confirmations of Funds using the Confirmations of Funds API
Step 3: End user (PSU) authorization process
The end user (PSU), can choose which authorization process they want, either the Decoupled Authorization flow or Redirect Authorization flow. Their option will depend on whether the authorization flow is applicable to the specific country and whether they are an Individual or Corporate customer.
On the successful completion of these processes, you will receive an access token which will either be a Decoupled Grant (DG) or Authorization Code Grant (ACG) respectively. With this access token, you'll be able to call the endpoints of the functional APIs.
To see more details of this step, click on either of the following links:
PSU authorization of Account / Card Account Consent
PSU authorization of Confirmation of Funds
Step 4: Call the functional APIs
The authorization process is finished and you can now call our APIs!
Account / Card Account Information APIs
| Call the Account / Card Account Information APIs | You can retrieve balances and transactions etc. using the Account / Card Account Information APIs. |
Payments API
| Request payment execution | The PUT (request payment execution) endpoint of the Payments API. |
| Get payment status | The GET (payment status) endpoint of the Payments API is to find out if the payment has been successfully made. |
Confirmation of Funds API
| Validate customer consent | The PUT (consent) endpoint of the Confirmation of Funds API, is for validating the consent. |
| Check availability of funds | The POST (CoF) endpoint of the Confirmation of Funds API is where you can retrieve confirmation on whether there are available funds in the customer's account. |
Sandbox test data
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.
The account profiles contain different response data with common account and transaction data. We've also included data that contains the maximum field lengths and number of transactions for each customer category (Individuals and Corporates) per country. The payment test data provides support for different payment types and responses from the payment endpoints.
Test Data documentation for our PSD2 APIs
For guidance on how to make API requests, please follow the API Documentation (see Step 4 for the links).