Live Data Access
This guide is only applicable to TPPs with valid certificates. The following steps help you get set up to access our Live Data APIs as well as any changes you need to make (e.g. certificates, subscriptions).
Authenticate
Authorize
Create
Manage
General information
This guide will help you through the enrollment process so you can gain access to Handelsbanken's Live Data. Please note that you are not able to test this flow in our Sandbox, as the APIs are currently only available in our Live Data environment.
Go Live prerequisites
Before using our Live Data APIs you must have completed the following:
1. Received authorisation from a Local Competent Authority to become a Third Party Provider (TPP).
2. Received a PSD2 eIDAS certificate (QWAC) or a UK Open Banking certificate (OBWAC) from a Qualified Trust Service Provider (QTSP).
It is important that the certificate includes the services you are interested in. In this context called "scopes". The following scopes are available:
Account Information Services (AIS): Allows the TPP to access and aggregate information from a user’s various bank accounts, including viewing balances, transaction history, and other account details.
Payment Initiation Services (PIS): Enables the TPP to initiate payments directly from a user’s bank account.
Confirmation of Funds Service (CBPII): Allows the TPP to confirm whether a specific amount, necessary for a transaction, is available in the payer’s account.
Note that a PIS scope also give authorization to the Confirmation of Funds (CoF) API, that is, you do not need to have a certificate with the CBPII scope to be able to use the CoF API.
Important information about QTSPs:
If you encounter issues when following our step-by-step guide below, it could be that your QTSP is not on our trusted list and we need to add them. Please contact us and include the name of the QTSP and the link to the CRL distribution points (i.e. the URL where the revocation list can be located). You can send us a message via this page Contact us
Live Data Gateway URL
Live Data Enrollment flow
Below you'll find a simplified version of the necessary steps that you must perform to enroll in our Live Data environment.
- First you must request access through our Third-Parties API to get your unique TPP-id (e.g. SE-FINA-100001).
- Then you'll need to do a Client Credential grant request to get an Access Token.
- After that you'll use the TPP-id (from the first step) and the Access Token (from the second step) to register an app. Then you need to subscribe at least one of our API Products to your app (you can always add more later on). Once that's done, you'll receive a unique App-id that must be used for all AISP or PISP operations.
Please note: "-H" represents HEADER payload and "-d" represents BODY payload.
Step-by-step guide
- StepsDescription
- 1. Request third party accessRegister with us as a TPP and add your QWAC / OBWAC certificate.
- 1.1 Add an additional certificateAdd an additional QWAC / OBWAC certificate.
- 2. Request Client Credential grant tokenObtain access tokens based on the credentials of the client.
- 3. Register your app and subscribe to our APIsCreate subscriptions to your app in the Live environment.
- 3.1 Add an additional API subscriptionAdd an additional API product subscription.
1. Request third party access
Our Third-Parties API allows you to enroll with us as a TPP and add your PSD2 eIDAS certificate (QWAC) or a UK Open Banking certificate (OBWAC). If you would like to add an additional certificate, please follow the step below and not this step.
Please note that we only accept QWAC and OBWAC.
POST https://api.handelsbanken.com/openbanking/psd2/v1/third-parties
Response: TPP-id
See example request below (the values are only visual representations and are not to be used for real requests).Note: "-H" represents the HEADER.
curl -X POST https://api.handelsbanken.com/openbanking/psd2/v1/third-parties \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'TPP-Request-ID: < BY TPP >' \
-H 'TPP-Transaction-ID: < BY TPP >'
HTTP/1.1 201 Created
{ "clientId": "SE-FINA-100001" }
Important information about QTSPs:
If you encounter issues when enrolling, it could be that your QTSP is not on our trusted list and we need to add them. Please contact us and include the name of the QTSP and the link to the CRL distribution points (i.e. the URL where the revocation list can be located). You can send us a message via this page Contact us
If you experience any problems, please see our FAQs about onboarding and certificates under the "Live Environment FAQs" section on this page FAQs
For more detailed information on this API, please log in to our portal so you can read the documentation for our Third Parties API
1.1 Add an additional certificate
This is not a mandatory step for going Live, but may be required by some TPPs who need to add another certificate.
If you would like to add an additional PSD2 eIDAS certificate (QWAC) or a UK Open Banking certificate (OBWAC) because you want to add a certificate with another "role" or one of your certificates will expire soon (for example), you should use this PUT endpoint.
It's very important that you use PUT and not POST if you have already onboarded with us!
This PUT request will just add another certificate, it will not replace the certificate(s) you already have, which means you can use multiple certificates at the same time. The consents and tokens that were issued previously will remain valid, as they are not locked to a specific certificate.
Please note that we also only accept QWAC and OBWAC.
PUT https://api.handelsbanken.com/openbanking/psd2/v1/third-parties
Response: TPP-id
See example request below (the values are only visual representations and are not to be used for real requests).
Note: "-H" represents the HEADER and "-d" represents the BODY payload.
curl -X PUT https://api.handelsbanken.com/openbanking/psd2/v1/third-parties \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'TPP-Request-ID: < BY TPP >' \
-H 'TPP-Transaction-ID: < BY TPP >'\
-H 'Content-type: application/json' \
-d '{"clientCertificate":"MIIHfACIBWSgBwI.....sXoG0mxxYva"}'
HTTP/1.1 200 OK
{ "clientId": "SE-FINA-100001" }
Please note:
It is very important that the new client certificate is used in both the TLS (Transport Layer Security) and in the payload of the request. There should be no line breaks or white spaces either.
If you experience any problems, please see our FAQs about onboarding and certificates under the "Live Environment FAQs" section on this page FAQs
For more detailed information on this API, please log in to our portal so you can read the documentation for our Third Parties API
2. Request Client Credential grant token
This API allows you to obtain access tokens based on the credentials of the client.
POST https://api.handelsbanken.com/mlurd/oauth2/token/1.0 -d TPP-id
Response: Access Token
See example request below (the values are only visual representations and are not to be used for real requests).
Note: "-H" represents the HEADER and "-d" represents the BODY payload.
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=client_credentials&scope=PSD2-ADMIN&client_id=SE-FINA-100001'
HTTP/1.1 200 OK
{ "access_token": "QVQ6ZWU1M2Y1ZTQtY2U1Ni00MTNkLWIzYWItYjRkYWEzMTA5ZmYw", "expires_in": 7776000, "token_type": "Bearer" }
Please note:
You must use the TPP-id as a value for the client_id in this request.
For more detailed information on this API, please log in to our portal so you can read the documentation for our Client Credentials Grant
3. Register your app and subscribe to our APIs
This API allows you to create subscriptions to our APIs for your app in the Live environment.
POST https://api.handelsbanken.com/openbanking/psd2/v1/subscriptions -H TPP-id -H Access Token -d {App details and initial API Product subscription}
Response: App-id
See example request below (the values are only visual representations and are not to be used for real requests).
Note: "-H" represents the HEADER and "-d" represents the BODY payload.
curl -X POST https://api.handelsbanken.com/openbanking/psd2/v1/subscriptions \
--key <Your private key file> \
--cert <Your public cert file> \
-H "X-IBM-Client-Id: SE-FINA-100001" \
-H "Authorization: Bearer QVQ6ZWU1M2Y1ZTQtY2U1Ni00MTNkLWIzYWItYjRkYWEzMTA5ZmYw" \
-H "TPP-Request-ID: <BY TPP>" \
-H "TPP-Transaction-ID: <BY TPP>" \
-H "Content-Type: application/json" \
-d '{ "app": { "name": "testapp", "description": "Test app mobile device.", "oauthRedirectURI": "<YOUR REDIRECT URI>" }, "product": { "name": "accounts" } }'
HTTP/1.1 200 OK
{ "clientId": "2cffdb50-2323-4be7-a2a2-70a6610f8a06", "name": "testapp", "description": "Test app mobile device.", "oauthRedirectURI": "YOUR REDIRECT URI", "subscription": { "subscriptionId": "5a72e1531b6586f34a0d7ce3", "product": { "name": "accounts", "version": "2.0.0", "scope": "AIS" } } }
Please note:
- You must use the header X-IBM-Client-Id with your TPP-id (e.g. SE-FINA-100001) in this request.
- Input the name of one of our APIs in the name value e.g. "product": { "name": "replace-with-API-name" }. In the above example, the "Accounts API" has been subscribed to. The names of the API products are as follows:
"consents"
"accounts"
"accounts-gb"
"accounts-lu-individual"
"accounts-lu-corporate"
"card-accounts"
"payments"
"payments-gb"
"payments-lu"
"funds-confirmations"
"funds-confirmations-gb"
- If you are subscribing to the general Accounts API or Card Accounts API for multiple countries, don't forget to subscribe to our Consents API also, otherwise you won't be able to create a consent which is a prerequisite for retrieving the accounts and transactions. If you are subscribing to the Accounts and Cards API GB (for Great Britain), the consent is included in the API.
- There is no support for multiple redirect_uris on a single app. If you would like to add another redirect_uri, you will need to register a separate app (by following this step).
- If you would like your app to consume several APIs, follow the next step.
For more detailed information on this API, please log in to our portal so you can read the documentation for our Subscriptions API
3.1 Add an additional API subscription (one per request)
This is not a mandatory step for going Live, but may be required by some TPPs who need to subscribe to additional APIs.
If you would like to add an additional API subscription you can use the POST endpoint, but include the App-id (from the initial step).
POST https://api.handelsbanken.com/openbanking/psd2/v1/subscriptions -H TPP-id -H Access Token -d App-id {Additional API Product for subscription}
Response: Confirmation and verification information about the new subscription.
See example request below (the values are only visual representations and are not to be used for real requests).
Note: "-H" represents the HEADER and "-d" represents the BODY payload.
curl -X POST https://api.handelsbanken.com/openbanking/psd2/v1/subscriptions \
--key <Your private key file> \
--cert <Your public cert file> \
-H "X-IBM-Client-Id: SE-FINA-100001" \
-H "Authorization: Bearer QVQ6ZWU1M2Y1ZTQtY2U1Ni00MTNkLWIzYWItYjRkYWEzMTA5ZmYw" \
-H "TPP-Request-ID: <BY TPP>" \
-H "TPP-Transaction-ID: <BY TPP>" \
-H "Content-Type: application/json" \
-d '{ "clientId": "2cffdb50-2323-4be7-a2a2-70a6610f8a06", "product": { "name": "payments" } }'
HTTP/1.1 200 OK
{ "clientId": "2cffdb50-2323-4be7-a2a2-70a6610f8a06", "name": "testapp", "description": "Test app mobile device.", "oauthRedirectURI": "<YOUR REDIRECT URI>", "subscription": { "subscriptionId": "5a72e1531b6586f34a0d7ce7", "product": { "name": "payments", "version": "1.0.2", "scope": "PIS" } } }
Please note:
- Input the name of one of our APIs in the name value e.g. "product": { "name": "replace-with-API-name " }. In the above example, the "Payments API" has been subscribed to. The names of the API products are as follows:
"consents"
"accounts"
"accounts-gb"
"accounts-lu-individual"
"accounts-lu-corporate"
"card-accounts"
"payments"
"payments-gb"
"payments-lu"
"funds-confirmations"
"funds-confirmations-gb"
- If you are subscribing to the general Accounts API or Card Accounts API for multiple countries, don't forget to subscribe to our Consents API also, otherwise you won't be able to create a consent which is a prerequisite for retrieving the accounts and transactions. If you are subscribing to the Accounts and Cards API GB (for Great Britain), the consent is included in the API.
- The response will only contain information about the new subscription that was created in the request, not all subscriptions for the app.
- There is no support for multiple redirect_uris on a single app. If you would like to add another redirect_uri, you will need to register a separate app (by following the previous step).
For more detailed information on this API, please log in to our portal so you can read the documentation for our Subscriptions API
Summary
With your newly registered unique App identifier App-id (e.g. 2cffdb50-2323-4be7-a2a2-70a6610f8a06) and designated API Product subscriptions, you are now ready to proceed to the AISP and/or PISP flow that's described in our Technical Guidelines. From here after, all forthcoming AISP and PISP requests will use this Identifier for all requests as the X-IBM-Client-Id key value. The exception is for Authorizations requests, where the key client_id is used instead.
Please check out our FAQs if you experience any problems with along the way Frequently Asked Questions