Confirmation of Funds flow
Step-by-step guide to help you perform an availability of funds check via our Confirmation of Funds API.
General information
This page describes the details of how you can check whether funds are available on an end user's (PSU's) account, via Handelsbanken's PSD2 API.
An overview of the steps in these guidelines can be found here: Confirmation of Funds - 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). 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 API before going Live.
Sandbox Gateway Host URL
When testing our API in our Sandbox environment, please ensure that the below base URL is used in the calls.
Live Data Gateway Host URL
When using our API in the Live environment, please ensure that the below base URL is used in the calls.
Step-by-step guide (for Confirmation of Funds)
- StepsDescription
- 1. Create CCG tokenClient Credentials Grant Access Token request using the Client Credentials Grant API.
- 2. Initiate Customer ConsentInitiate End user (PSU) consent process using the Confirmation of Funds API.
- 3. Consent Authorization GrantEnd user authorization using available SCA Approach(es) received in the consent response.
- - SCA RedirectSCA Redirect Authorization flow using Authorization Code Grant API.
- - SCA DecoupledSCA Decoupled Authorization flow using Decoupled Grant Mobile BankID API.
- 4. Validate Customer ConsentValidate End user (PSU) consent process using the Confirmation of Funds API.
- 5. Check availability of fundsCheck whether there are available funds or not, by using the Confirmation of Funds API.
- Sandbox test dataTest data documentation for Funds Confirmations.
Step 1: Request Client Credential Grant token
The authorization process starts with requiring a Client Credentials Grant (CCG).
This is an access token that is specific for the requesting client-id and scope, e.g. the registered application and scope CBPII.
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=client_credentials&scope=CBPII&client_id=f31b7318-8f21-4eaf-8817-6b5e4e02d6bc'
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 | 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 Confirmation of Funds API, "CBPII" must be the scope. Several scopes can be added if you plan on using our other APIs, but they must be divided by whitespace characters. Mandatory |
CBPII AIS PIS CBPII |
| client_id | The unique identifier of your registered application. Mandatory |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc
|
Response
This is what the response looks like when the CCG token has been successfully created. This CCG token is valid for 15 minutes. With this access token, you can call the POST /funds-confirmations/consents endpoint of the Confirmation of Funds API to acquire CBPII consents for the PSUs (for as long as the returned expiry time allows).
HTTP/1.1 200 OK
{
"access_token": "QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4",
"expires_in": 123456,
"token_type": "Bearer"
}
The above response is an example.
| Parameter | Description | Example |
|---|---|---|
| access_token | The returned CCG token, associated with your registered application for the scope(s) you have requested. |
QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4
|
| expires_in | Number of seconds the access_token is valid. Always use this value rather than hardcoding a set time value (e.g. 15 mins). | e.g. 123456 (please check what you receive in the response) |
| token_type | Always the value ”Bearer”. | Bearer |
Step 2: Initiate consent (using CCG token)
With the CCG, an end user consent can be initiated. The returned id should be used in the next step (Step 3), when the end user (PSU) signs the consent.
Request
curl -X POST https://api.handelsbanken.com/openbanking/psd2/v2/funds-confirmations/consents \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'Authorization: Bearer QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4' \
-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>' \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-d '{"account": {"iban": "SE5460000000000403333911"} }'
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 Confirmation of Funds API documentation
The client-id example value must be replaced with your application's client-id and authorization header must contain your CCG access token from Step 1: Request Client Credential Grant token.
| Parameter | Description | Example |
|---|---|---|
| Authorization | The CCG access token from Step 1. Mandatory. |
Bearer
QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4 |
| Country | ISO 3166-1 country code. Mandatory. |
SE |
| TPP-Request-ID | Unique identifier for the request. Mandatory. |
c8271b81-4229-5a1f-bf9c-758f11c1f5b1 |
| TPP-Transaction-ID | Unique identifier for the transaction. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
| PSU-Corporate-ID | Corporate Identification. Mandatory for Corporate PSUs only. If left blank, we assume the customer is an Individual. For GB Corporate customers, the 6 digit number can be obtained from the GET /accounts response (from the country specific Accounts GB API). |
SE: 10 digit organisation number FI: 10-11 digit business identity code GB: 6 digit corporate number NL: 6 digit corporate number LU: 10 digit organisation number |
| PSU-Corporate-ID-Type | Corporate Identification type. Mandatory for Corporate PSUs only. Supported value is 'BANK'. | BANK |
| X-IBM-Client-Id | Your registered application's client-id. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc
|
| account | Account to be covered by the consent. Support format is IBAN. Mandatory. |
{"iban": "SE5460000000000403333911"} |
Response
This is what the response looks like when the consent initiation for Confirmation of Funds has been done. A successful response will include a consent ID as well as links to endpoints for continuing the authorization process (see next step) with the signing of the consent by the end user (PSU).
HTTP/1.1 200 OK
{
"consentId": "69b50cd4-33d9-47b6-bfe7-98aea7bda22d",
"consentStatus": "RECEIVED",
"scaMethods": [{
"_links": {
"authorization": [{
"href": "https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0",
"name": "authorize_1.0",
"type": "application/x-www-form-urlencoded"
}
]
},
"scaMethodType": "REDIRECT"
},
{
"_links": {
"authorization": [{
"href": "https://api.handelsbanken.com/mlurd/decoupled/mbid/initAuthorization/2.0",
"name": "decpld_mbid_2.0",
"type": "application/json"
}]
},
"scaMethodType": "DECOUPLED"
}
]
}
The above response is an example.
| Parameter | Description | Example |
|---|---|---|
| consentId | The consent ID that has been created to be used later on when the PSU signs it. |
69b50cd4-33d9-47b6-bfe7-98aea7bda22d
|
| scaMethods.[]._links.authorization.[].href | Link to authorization endpoint for starting the PSU authorization process. | Redirect: https://secure.handelsbanken.com/bb/gls5/oauth2/authorize/1.0 Decoupled: https://api.handelsbanken.com/mlurd/decoupled/mbid/initAuthorization/2.0 |
| scaMethods.[].scaMethodType | The type of PSU authorization method. | REDIRECT 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/mlurd/decoupled/mbid/initAuthorization/1.0"
Step 3: Consent Authorisation Grant using ACG or DG
This is the step where the end user (PSU) signs the consent.
For the authorization process, 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 (Step 2: Initiate consent using CCG token).
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 validate the PSU consent in the next step.
In the below links you can find more detailed technical information and the next steps so you can implement the different authorization processes.
Important: not all countries support both SCA methods. See here for which methods are applicable per country SCA Methods
Step 4: Validate consent (using ACG/DG token)
Before you can do the actual check for availability of funds, you need to validate the consent. In this request you need to use the ACG/DG token from the previous step.
If the consent is successfully validated, it will remain valid for as long as you like / the PSU wants. Later on, if you want to remove the PSU's consent, you need to do this via the endpoint DELETE /funds-confirmations/consents/{consentId}.
Request
curl -X PUT https://api.handelsbanken.com/openbanking/psd2/v1/funds-confirmations/consents/69b50cd4-33d9-47b6-bfe7-98aea7bda22d \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'Authorization: Bearer QVQ6YTM2ZmYyMmIyYjFkMS00M2VlLTk5MWMt' \
-H 'Accept: 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>' \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc'
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 Confirmation of Funds API documentation
The client-id example value must be replaced with your application's client-id and authorization header must contain your ACG/DG access token from the previous step (Step 3: Consent Authorisation Grant using ACG or DG).
| Parameter | Description | Example |
|---|---|---|
| consentId | The consent ID that was created in Step 2. Mandatory. |
69b50cd4-33d9-47b6-bfe7-98aea7bda22d
|
| Authorization | The ACG or DG access token from Step 3. Mandatory. |
Bearer
QVQ6YTM2ZmYyMmIyYjFkMS00M2VlLTk5MWMt |
| Country | ISO 3166-1 country code. Mandatory. |
SE |
| TPP-Request-ID | Unique identifier for the request. Mandatory. |
b9382c92-5229-6a1f-cf9c-868f11c1f6c2 |
| TPP-Transaction-ID | Unique identifier for the transaction. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
| X-IBM-Client-Id | Your registered application's client-id. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc
|
Response
This is what the response looks like when the consent validation for Confirmation of Funds has been done. A successful response will contain a status saying whether the consent is valid or not.
HTTP/1.1 200 OK { "consentStatus": "VALID" }
| Parameter | Description | Example |
|---|---|---|
| consentStatus | The status of the consent. Possible values are "VALID" or "INVALID". | VALID INVALID |
Step 5: Check availability of funds
At this point, the PSU will have signed the consent and you will have validated it. By using a CCG token, the POST /funds-confirmations endpoint may now be called so you can retrieve confirmation on whether there are available funds in the customer's account. If you want to remove the PSU's consent, you do this via the endpoint DELETE /funds-confirmations/consents/{consentId}.
Please note: the CCG token from Step 1 should be sent in the “Authorization” HTTP-header, or you may need to request a new CCG token if the old one has expired.
Request
curl -X POST https://api.handelsbanken.com/openbanking/psd2/v1/funds-confirmations \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'Authorization: Bearer QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4' \
-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>' \
-H 'X-IBM-Client-Id: f31b7318-8f21-4eaf-8817-6b5e4e02d6bc' \
-d '{ "account": {
"iban": "SE5460000000000403333911"
},
"consentId": "69b50cd4-33d9-47b6-bfe7-98aea7bda22d",
"instructedAmount": {
"currency": "SEK", "amount": 4321.50
},
"payee": "H&M"
}'
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 Confirmation of Funds API documentation
The client-id example value must be replaced with your application's client-id and authorization header must contain your CCG token from Step 1 (or a renewed one).
| Parameter | Description | Example |
|---|---|---|
| Authorization | The CCG token from Step 1 (or a renewed one). Mandatory. |
Bearer
QVQ6M2NkMjUzMzMtZDZkZS00OGU1LTk0MzMtMmVhOTY5ZDA5YmU4 |
| Country | ISO 3166-1 country code. Mandatory. |
SE |
| TPP-Request-ID | Unique identifier for the request. Mandatory. |
b9382c92-5229-6a1f-cf9c-868f11c1f6c2 |
| TPP-Transaction-ID | Unique identifier for the transaction. Mandatory. |
6b24ce42-237f-4303-a917-cf778e5013d6 |
| X-IBM-Client-Id | Your registered application's client-id. Mandatory. |
f31b7318-8f21-4eaf-8817-6b5e4e02d6bc
|
| account | Account to be covered by the consent. Support format is IBAN. Mandatory. |
{"iban": "SE5460000000000403333911"} |
| consentId | The consent ID that was created in Step 2. Mandatory. |
69b50cd4-33d9-47b6-bfe7-98aea7bda22d
|
| instructedAmount | The amount of funds that need to be available. Mandatory. |
{"currency": "SEK", "amount": 4321.50} |
| payee | The card merchant performing the funds check Optional. |
H&M |
Response
A response will contain a boolean saying whether there are available funds or not.
HTTP/1.1 200 OK
{
"fundsAvailable": true
}
| Parameter | Description | Example |
|---|---|---|
| fundsAvailable | Confirmation of funds response. | true false |
Sandbox test data
The Sandbox test data is designed to provide app development support for those interested in performing an availability of funds check. Documentation for our Sandbox can be found here:
Test Data documentation for CBPII
For guidance on how to make API requests, please follow the API documentation:
Confirmation of Funds API documentation