Payments flow

Step-by-step guide to help you initiate payments via our Payments API.

 

General information

This page describes the details of how to initiate payments on the behalf of a PSU, via Handelsbanken's PSD2 API. An overview of the steps in these guidelines can be found here: Payment Initiation - 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 that provides support for different payment types and responses 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 Payments)

• StepsDescription
• 1. Create CCG tokenClient Credentials Grant Access Token request using the Client Credentials Grant API.
• 2. Initiate PaymentInitiate End user (PSU) Payment process using the Payment API.
• 3. Authorization Code GrantEnd user authorization using available SCA Approach(es) received in the payment initiation response.
•    - SCA DecoupledSCA Decoupled Authorization flow using Decoupled Grant (Mobile BankID) API.
•    - SCA RedirectSCA Redirect Authorization flow using Authorization Code Grant API.
• 4. Request payment executionRequest the execution of a payment after the PSU has signed.
• 5. Get Payment statusCheck the status of the payment.
• Sandbox test dataTest data documentation for Payments.

 

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 PIS.

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 Payment Initiation API, "PIS" 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.	PIS AIS PIS CBPII
client_id	The unique identifier of your registered application. Mandatory.	f31b7318-8f21-4eaf-8817-6b5e4e02d6bc

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. 15mins).	e.g. 123456 (please check what you receive in the response)
token_type	Always the value ”Bearer”.	Bearer

 

Step 2: Initiate payment (using CCG token)

With the CCG, the payment can be initiated. The returned payment-id should be used in the next step (Step 3), when the end user (PSU) signs the payment.

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 definitions, descriptions and codes Payment Initiation 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
paymentproduct	Payment product identifier. Mandatory.	swedish-domestic-giro-payment cross-currency-credit-transfer sepa-credit-transfer
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 (known by the customer). 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

This is what the response looks like when the payment initiation has been done. A successful response will include a payment ID as well as links to endpoints for continuing the authorization process (next step) with the signing of the payment by the end user (PSU).

The above response is an example.

Parameter	Description	Example
paymentId	The payment ID that has been created to be used later on when the PSU signs the payment.	58cdfef9-7f6e-476e-a1af-c54c0a9a3135
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

 

Step 3: Payment Authorisation Grant using ACG or DG

This is the step where the end user (PSU) signs the payment.

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 initate the process, in the response of the payment initiation (Step 2: Initiate payments using CCG token). The authorization flows described here (in the links below), are the Decoupled Authorization Flow and Redirect Authorization Flow.

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 Payment API in the next step.

In the below links you can find more detailed technical information about how to implement the different authorization processes.

SCA Redirect

SCA Decoupled

Important: not all countries support both SCA methods. See here for which methods are applicable per country SCA Methods

 

Step 4: Request payment execution

After you have implemented the authorization process (in the previous step), the PUT (request payment execution) endpoint of the Payment API may now be called with either the ACG or the DG access token.

Please note: the access token from the previous step (Step 3) should be sent in the “Authorization” HTTP-header.

In the below link you can find more technical information about our API (the swagger file is found under "Explore bundled APIs").

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 Payment Initiation 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: Payment Authorization Grant using ACG or DG).

Parameter	Description	Example
paymentproduct	Payment product identifier. Mandatory.	swedish-domestic-giro-payment cross-currency-credit-transfer sepa-credit-transfer
paymentId	The payment ID that was created in Step 2.	58cdfef9-7f6e-476e-a1af-c54c0a9a3135
Authorization	The ACG/DG access token from Step 3. Mandatory.	Bearer QVQ6MGQ2YmYtMmZjOC00Yzg3LzYyOGU0NTg5YmM3
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
X-IBM-Client-Id	Your registered application's client-id. Mandatory.	f31b7318-8f21-4eaf-8817-6b5e4e02d6bc

Important: Make sure to remove unused optional parameters in the request. Sending a parameter with an empty value can cause the validation to fail due to an invalid parameter.

Please ensure you check out the Country specific information (which contains important business rules per country) and the Implementation Guidelines here Country specific Payment rules

The above response is an example.

Parameter	Description	Example
transactionStatus	The status of the payment.	"ACCC" "RJCT"

 

Step 5: Get payment status

The execution of a payment may not happen instantaneously, if for example, it's a weekend / bank holiday. To find out if a payment has been executed successfully, you can check its status.

Please note: The "Authorization" HTTP-header accepts either the CCG token from Step 1 or the ACG/DG token from Step 3.

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 Payment Initiation API documentation

The client-id example value must be replaced with your application's client-id and the authorization header must contain a valid access token.

Parameter	Description	Example
paymentproduct	Payment product identifier. Mandatory.	swedish-domestic-giro-payment cross-currency-credit-transfer sepa-credit-transfer
paymentId	The payment ID that was created in Step 2.	58cdfef9-7f6e-476e-a1af-c54c0a9a3135
Authorization	The CCG token from Step 1 or the ACG/DG access token from Step 3. Mandatory.	Bearer QVQ6MGQ2YmYtMmZjOC00Yzg3LzYyOGU0NTg5YmM3
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
X-IBM-Client-Id	Your registered application's client-id. Mandatory.	f31b7318-8f21-4eaf-8817-6b5e4e02d6bc

The above response is an example.

Parameter	Description	Example
paymentId	The payment ID that was created in Step 2.	58cdfef9-7f6e-476e-a1af-c54c0a9a3135
transactionStatus	The current status of the payment.	"ACCP" "ACSC" "ACCC"
reasonCode	Reason code if payment is rejected.	AC03
reason	Description of the reason for the rejected payment.	"Creditor account number is invalid or missing"

 

Sandbox test data

The Sandbox test data is designed to provide app development support so we have made available a variety of fictitious PSUs and payment profiles to test.

The payment test data consists of different payment types and responses from the Payment endpoints.

Test Data documentation for PISP

For guidance on how to make API requests, please follow the API documentation:

Payment Initiation API documentation