Sandbox testing for Accounts & Card Accounts (AISP)
Step-by-step guide to help you start testing our Account and Card Account Information APIs in our Sandbox using our static test data.
Sandbox Accounts & Card Accounts
General information
This guide will take you through the steps so you can start testing our Account and Card Account APIs in our Sandbox environment.
Once you are satisfied with your testing and would like to implement the Accounts and Card Accounts APIs in our Live environment, please follow this guide Live Accounts & Cards flow
The data in our sandbox is static, so within this guide you’ll find all the access tokens you need in order to perform the tests. We have tried to make it useful, but also simple!
4 easy steps so you can start testing our APIs...
1. Sign up
Sign up to create a free account on our Developer Portal. You can sign up here. Don’t forget to activate it by following the instructions in the activation email (check your junk mail).
2. Log in
After activating your account, log in and then click on your username (top right corner) and in the drop down list select “My apps”. This is where you'll see all of the test apps you've created (later on) and which APIs they are subscribed to.
3. Create an app
On the Manage your apps page, click Create new app and complete the information. Once you’ve created an app, make a note of the Client ID (App-id) as you'll be using it in the requests later on.
Note: You'll only ever see your TEST apps in our Developer Portal, meaning you won't see your Live environment apps (and subscriptions) here.
4. Subscribe to an API
After creating an app, go to “Subscriptions” and then you can browse the “Available APIs”. If you want to test, you need to subscribe! Click on an API product and under "Plans" press the "Subscribe" button. You can find the full list of available APIs on "All API Products" (found in the drop down list under "APIs" on the main menu). Click on an API, scroll to the bottom and subscribe.
Note: if you are not logged in to our Developer Portal, you will not be able to see all of our API Products (you'll see an access denied error message instead!)
Testing the Accounts & Card Accounts API
Now let's get started with some testing!
We have tried to make this as simple as possible for you, which is why we provide Authorization tokens that you just have to copy and paste in. The test data that you receive back (regarding PSU Account & Card Account information) is static and basic, but it should give you an idea of the type of information you will receive in our Live Environment.
Unfortunately we do not have a full Accounts & Card Accounts flow in our Sandbox, so we are missing the Consent Authorisation step where the PSU authenticates themselves using the Redirect or Decoupled SCA method. Where this step is missing, we'll provide you with the documentation where you can read about how it works in the Live environment.
Sandbox Gateway Host URL
When testing our APIs in our Sandbox environment, please ensure that the below base URL is used in the calls.
Important:When using our APIs in the Live environment, the base URL changes to https://api.handelsbanken.com/openbanking
For the Sandbox testing, we'll keep the same steps as our guidelines for our Live environment Accounts & Cards flow
Step-by-step guide
- StepsDescription
- 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 APIsCall the Account & Card Account Information APIs.
- - GET accountsExample of the request and response.
- - GET account detailsExample of the request and response.
- - GET account balancesExample of the request and response.
- - GET account transactionsExample of the request and response.
- Accounts Test Data Customer profiles and their associated access tokens.
- Card Accounts Test Data Customer profiles and their associated access tokens.
Step 1: Request Client Credential Grant (CCG) token
The authorization process starts with requiring a Client Credentials Grant (CCG). The result of this call will be a CCG access token which is used to call the POST /consents endpoint of the Consents API (which is used to acquire AIS consents for the PSU).
The Client Credential Grant request and responses are identified using the scope object (e.g. AIS) and the CCG is identical for all countries and is PSU independent.
Request
curl -X POST https://sandbox.handelsbanken.com/openbanking/oauth2/token/1.0 \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=AIS&client_id=f31b7318-8f21-4eaf-8817-6b5e4e02d6bc'
See below for the type of information that needs to be in your request for Sandbox testing.
| Parameter | Description | Example |
|---|---|---|
| grant_type | Type of token request - CCG in this case. Allowed value: “client_credentials”. Mandatory |
client_credentials |
| scope | A static scope with one or several values. For the Account & Card Account APIs, "AIS" must be the scope. Mandatory |
AIS |
| client_id | The client_id (app-id) for your test app which we said you should note down earlier. If you have forgotten it, under your username (top right corner), click the arrow and then in the drop down list select "My apps", click on your app and you'll find the client_id under "Credentials". Mandatory |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
Response
This is what the response looks like when the CCG token has been successfully created.
HTTP/1.1 200 OK
{
"access_token": "QVQ6YmNlZjI0M2QtZDBhZi00OGZiLWE0OTgtZGUwMTJhMDdjMjYz",
"expires_in": 7776000,
"token_type": "Bearer"
}
| Parameter | Description | Example |
|---|---|---|
| access_token | The returned CCG token, associated with your registered application for the scope(s) you have requested. | QVQ6YmNlZjI0M2QtZDBhZi00OGZiLWE0OTgtZGUwMTJhMDdjMjYz |
| expires_in |
Number of seconds the access_token is valid for. |
e.g. 7776000 |
| token_type | Always the value ”Bearer”. | Bearer |
Full definitions, descriptions and codes can be found here Client Credentials Grant (OAuth 2.0)
Step 2: Initiate consent (using CCG token)
With the CCG, an end user consent can be initiated. The returned ID would normally be used in the next step (Step 3 when the end user (PSU) signs the consent), however we are missing this step in our Sandbox environment.
The test data in the Sandbox for Consent requests and responses is identified using the Authorization object. The responses are identified by the Authorization token.
Request
curl -X POST https://sandbox.handelsbanken.com/openbanking/psd2/v1/consents \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-H 'Authorization: Bearer QVQ6YmNlZjI0M2QtZDBhZi00OGZiLWE0OTgtZGUwMTJhMDdjMjYz' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Country: <ISO 3166-1 country code>' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
-d '{"access":"ALL_ACCOUNTS"}'
See below for the type of information that needs to be in your request for Sandbox testing.
Important: In the Live environment, if the PSU is a Corporate customer, then the parameters "PSU Corporate ID" and "PSU Corporate ID" Type must be included in the header with the relevant values. More information about this can be found in the guidelines for the Live environment Accounts and Cards flow
| Parameter | Description | Example |
|---|---|---|
| X-IBM-Client-Id | The client_id (app-id) for your test app which we said you should note down earlier. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
| Authorization |
The CCG access token. Use the example on the right in your request. We have included a negative scenario as well for testing purposes. |
Bearer QVQ6YmNlZjI0M2QtZDBhZi00OGZiLWE0OTgtZGUwMTJhMDdjMjYz Access token expired (negative scenario): Bearer QVQ6MmQ3NGIwNTYtZTYwNy00M2FkLTkzZTEtYTQ3ZTc0NmQ4ODJm |
| Country | ISO 3166-1 country code. Mandatory. |
SE, GB, FI, NL, LU (one country per request) |
| TPP-Request-ID | Unique identifier for the request. For Sandbox testing, you can make this up. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. For Sandbox testing, you can make this up. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
| access | Supported value is 'ALL_ACCOUNTS'. Mandatory. |
ALL_ACCOUNTS |
Response
This is what the response looks like when the consent initiation for Account / Card Account Information has been done. A successful response will include a consent ID as well as links to endpoints for continuing the authorization process with the signing of the consent by the end user (PSU).
HTTP/1.1 200 OK { "consentId": "22aa3559-577d-441c-b9e6-664ac3311a3e",
"consentStatus": "RECEIVED",
"scaMethods": [{
"_links": {
"authorization": [{
"href": "https://sandbox.handelsbanken.com/openbanking/redirect/oauth2/authorize/1.0",
"name": "authorize_1.0",
"type": "application/x-www-form-urlencoded"
}
]
},
"scaMethodType": "REDIRECT"
},
{
"_links": {
"authorization": [{
"href": "https://sandbox.handelsbanken.com/openbanking/decoupled/mbid/initAuthorization/1.0",
"name": "decpld_mbid_1.0",
"type": "application/json"
}]
},
"scaMethodType": "DECOUPLED"
}
]
}
Important: In the Live environment, the link to the authorization endpoint is different than in Sandbox. See here for the difference:
- For Redirect:
Sandbox = "https://sandbox.handelsbanken.com/openbanking/redirect/oauth2/authorize/1.0"
Live = "https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0"
- For Decoupled:
Sandbox = "https://sandbox.handelsbanken.com/openbanking/decoupled/mbid/initAuthorization/1.0"
Live= "https://api.handelsbanken.com/bb/gls5/decoupled/mbid/initAuthorization/1.0"
| Parameter | Description | Example |
|---|---|---|
| consentId | The consent ID that has been created to be used later on when the PSU signs it. | 22aa3559-577d-441c-b9e6-664ac3311a3e |
| scaMethods.[]._links.authorization.[].href | Link to authorization endpoint for starting the PSU authorization process. |
Decoupled: Redirect: |
| scaMethods.[].scaMethodType | The type of PSU authorization method. | DECOUPLED REDIRECT |
Please also refer to the API documentation for definitions, descriptions and codes Consents API documentation
Step 3: Consent Authorisation Grant using ACG or DG
This is the step where the end user (PSU) signs the consent and this one is not testable in our Sandbox environment.
However, for the authorization process in the Live environment, the end user (PSU) should be able to choose among the type of authorization flows that are applicable to the specific country and customer type (Individual or Corporate customer). The applicable types of authorization flows are returned, including the URL to initiate the process, in the response of the consent initiation (in the previous step). On the successful completion of these processes, you will receive an access token which will be an Authorization Code Grant (ACG) for the Redirect Authorization flow or Decoupled Grant (DG) for the Decoupled Authorization flow. With this access token, you will be able to call the endpoints of the Account and Card Account APIs in the next step.
In the below links you can find more detailed technical help and the next steps required for the Live environment.
Important: not all countries support both SCA methods. See here for which methods are applicable per country SCA Methods
But as we aren't able to test this in our Sandbox, please continue to the next step!
Step 4: Call the Account / Card Account Information APIs
As the authorization process (the previous step) cannot be tested in our Sandbox (and therefore you will not obtain ACG or DG access tokens which are needed to call the Account & Card Account endpoints), we will provide you with necessary access tokens.
The information you retrieve can vary due to the type of customer and which country the customer holds accounts in. Whilst we always try to keep our Sandbox test data up to date, the Account and Card Account attribute documents reflect exactly what is retrievable in our Live APIs. So before integrating with our Live APIs, please check our Country specific pages for the countries you want to integrate with, particularly the Attribute documents (found on every country's page).
Country specific Account rules
Country specific Card Account rules
In the below links, you can find our API documentation (definitions, descriptions and codes):
Account Information API documentation
Card Account Information API documentation
Below we have provided some examples of the requests for the Accounts API along with the Account access tokens
To test the Card Accounts API, use the endpoints: GET /card-accounts and GET /card-accounts/{accountId}/transactions and the Card Account access tokens instead.
GET /accounts (Sandbox) example
Here is an example of how a request would look like when performing tests in our Sandbox:
curl -X POST https://sandbox.handelsbanken.com/openbanking/psd2/v2/accounts \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-H 'Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
See below for the type of information that needs to be in your request for Sandbox testing.
| Parameter | Description | Example |
|---|---|---|
| X-IBM-Client-Id | The client_id (app-id) foryour test app which we said you should note down earlier. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
| Authorization |
The CCG access token. Mandatory. |
For test, use the access tokens found under Accounts test data
|
| TPP-Request-ID | Unique identifier for the request. For Sandbox testing, you can make this up. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. For Sandbox testing, you can make this up. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
Response
You'll receive all the available accounts for the test customer.
GET /accounts/{accountId} (Sandbox) example
An accountId is obtained from the GET/accounts step which you just did, so make sure you add this in to the url ("REPLACE_ACCOUNTID").
curl -X POST https://sandbox.handelsbanken.com/openbanking/psd2/v2/accounts/REPLACE_ACCOUNTID \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-H 'Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
See below for the type of information that needs to be in your request for Sandbox testing.
| Parameter | Description | Example |
|---|---|---|
| X-IBM-Client-Id | The client_id (app-id) for your test app which we said you should note down earlier. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
| Authorization |
The CCG access token. Mandatory. |
Use the same access token as you did in the previous step (which should be one of the access tokens found under Accounts test data)
|
| TPP-Request-ID | Unique identifier for the request. For Sandbox testing, you can make this up. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. For Sandbox testing, you can make this up. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
Response
You'll receive all information available, excluding the balance, for a particular account.
GET /accounts/{accountId} with balance (Sandbox) example
If you would like to get a balance with the account too, please do the request with the accountId (that you previously received) and include the withBalance query parameter.
curl -X POST https://sandbox.handelsbanken.com/openbanking/psd2/v2/accounts/REPLACE_ACCOUNTID/withBalance=true \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-H 'Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
See below for the type of information that needs to be in your request for Sandbox testing.
| Parameter | Description | Example |
|---|---|---|
| X-IBM-Client-Id | The client_id (app-id) for your test app which we said you should note down earlier. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
| Authorization |
The CCG access token. Mandatory. |
Use the same access token as you did in the previous call (which should be one of the access tokens found under Accounts test data)
|
| TPP-Request-ID | Unique identifier for the request. For Sandbox testing, you can make this up. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. For Sandbox testing, you can make this up. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
Response
You'll receive all information available, including the balance, for a particular account.
GET /accounts/{accountId}/transactions (Sandbox) example
Please note: The date query parameter (dateFrom and dateTo) should not be used in our Sandbox environment due to (old) static transaction dates (between the years 2017-2019). If you do use it, you may not retrieve any transactions... so we recommend that you don't use it!
curl -X POST https://sandbox.handelsbanken.com/openbanking/psd2/v2/accounts/REPLACE_ACCOUNTID/transactions \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-H 'Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'TPP-Request-ID: <Unique identifier for the request>' \
-H 'TPP-Transaction-ID: <Unique identifier for the transaction>' \
See below for the type of information that needs to be in your request for Sandbox testing.
| Parameter | Description | Example |
|---|---|---|
| X-IBM-Client-Id | The client_id (app-id) for your test app which we said you should note down earlier. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc |
| Authorization |
The CCG access token. Mandatory. |
Use the same access token as you did in the previous step (which should be one of the access tokens found under Accounts test data)
|
| TPP-Request-ID | Unique identifier for the request. For Sandbox testing, you can make this up. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. For Sandbox testing, you can make this up. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
Response
You'll receive all transactions available for a particular account.
Accounts Test Data
Use the access tokens below when doing the requests. The static data you receive reflects the type of info you'll receive from our Live environment Account API.
Sweden
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI1 |
| Individual | 2 | Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI2 |
| Individual | 3 | Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3 |
| Corporate | 1 | Bearer U0VfRsOWUkVUQUdfUFJPRklMX18x |
| Corporate | 2 | Bearer U0VfRsOWUkVUQUdfUFJPRklMX18y |
| Corporate | 3 | Bearer U0VfRsOWUkVUQUdfUFJPRklMX18z |
Great Britain
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer VUtfUFJJVkFURV9QUk9GSUxFX18x |
| Individual | 2 | Bearer VUtfUFJJVkFURV9QUk9GSUxFX18y |
| Individual | 3 | Bearer VUtfUFJJVkFURV9QUk9GSUxFX18z |
| Corporate | 1 | Bearer VVtfQ9SQVRFU19QUk9GSUxFC31x |
| Corporate | 2 | Bearer VVtfQ9SQVRFU19QUk9GSUxFC31y |
| Corporate | 3 | Bearer VVtfQ9SQVRFU19QUk9GSUxFC31z |
Finland
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer MV9QUk9GSUxFLUZJX1BSSVZBVEUx |
| Individual | 2 | Bearer MV9QUk9GSUxFLUZJX1BSSVZBVEUy |
| Individual | 3 | Bearer MV9QUk9GSUxFLUZJX1BSSVZBVEUz |
| Corporate | 1 | Bearer MS9QUk9GSUwtRklDT1JQT1JBVEUx |
| Corporate | 2 | Bearer MS9QUk9GSUwtRklDT1JQT1JBVEUy |
| Corporate | 3 | Bearer MS9QUk9GSUwtRklDT1JQT1JBVEUz |
The Netherlands
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer MVBST0ZJTEVfTkxfUFJJVkFURV8x |
| Individual | 2 | Bearer MVBST0ZJTEVfTkxfUFJJVkFURV8y |
| Individual | 3 | Bearer MVBST0ZJTEVfTkxfUFJJVkFURV8z |
| Corporate | 1 | Bearer UFJPRklMRTFfTkxfQ09SUE9SQVRFU18x |
| Corporate | 2 | Bearer UFJPRklMRTFfTkxfQ09SUE9SQVRFU18y |
| Corporate | 3 | Bearer UFJPRklMRTFfTkxfQ09SUE9SQVRFU18z |
Luxembourg
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer QVQ6ZGViMzMwNTktMWIwMy00MjJkLTk4MzYtNjJjZjBhOTg1MmQ5 |
Card Accounts Test Data
As mentioned in Step 4: Call the Account / Card Account Information APIs to test the Card Accounts API, use the endpoints:
GET /card-accounts and GET /card-accounts/{accountId}/transactions and the Card Account access tokens below instead.
| Customer type | Profile | Access token |
|---|---|---|
| Individual | 1 | Bearer QVQ6NmQ4OTQwYWUtZjRmZi00NGMwLWJkYWQtZWU3ZTM0MTgxOTdmCg== |
| Individual | 2 | Bearer QVQ6OTU2Y2E5YWQtOWE0Zi00ZmM2LTg4ZTUtMGJmMWY4ZmJmZjU2Cg== |
| Individual | 3 | Bearer QVQ6M2U0ZTMzZjgtMmE3Yi00YjAwLTk3NGMtN2E2YzNiNTg0ZDc3Cg== |
| Individual | 4 | Bearer QVQ6ZWMwZmE5NmQtZTdhMi00NTlhLTljYTItNjgyYzYwY2FiNDU3Cg== |