White Label Integration
Open banking. by Klarna offers a white label integration for TPPs/merchants that want to take full control of the user experience in accordance with their corporate identity.
Auth API
Via the Auth API the TPP/merchant can retrieve various forms and submit the responses towards Open banking. by Klarna.
XS2A Form Schema
The JSON-based XS2A Form Schema was created to describe form elements accurately yet independent of the rendering method.
Encryption
While the empty forms can be retrieved unencrypted, the form data has to be sent back encrypted.
Translations
The XS2A API exposes a dedicated endpoint from which the translations can be obtained.
Session Creation Call
The session creation call features additional parameters for white label integrators:
aspsp_access which can be used to configure the way the bank is accessed.
The following values are possible:
prefer_psd2- If there is a PSD2 bank connection available, it will be used. If this option is not possible the fallback bank connection is used.force_psd2- The PSD2 bank connection will be used and forced. If the bank is only supported via the fallback bank connection, an error is returned.prefer_fallback- The fallback bank connection will be used. Otherwise if available the PSD2 bank connection is used.force_fallback- The fallback bank connection will be used and forced. If the bank is only supported via PSD2 bank connection, an error is returned.
If a value for this parameter is not set the default behaviour is prefer_fallback.
Additionally the parameter redirect_return_url is required for white label integrators.
Example of a Session Creation Call
PUT /sessions
{
"aspsp_access": "prefer_psd2",
"redirect_return_url": "https://...",
"psu": {
"ip_address": "127.0.0.1",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36"
},
"keys": {
"hsm": "xxx",
"aspsp_data": "yyy"
}
...
}
Requirements for a White Label integration
White label integrators have to send the keys object as part of the body of POST, PUT and DELETE requests. This is a mandatory field for all server-side API's (XS2A API, Auth API and Consent API). The keys object should look like this:
{
"keys": {
"hsm": String,
"aspsp_data": String
}
}
The keys object contains the HSM credentials and the ASPSP data.
The hsm field is a static string containing the encrypted access credentials to the eIDAS private keys in the Klarna HSM. This field must only be set if the Klarna HSM is used. For more information see eIDAS certificate handling section in this documentation.
The aspsp_data field is a static string containing two HEX-values separated by a colon. This field is required for the decryption of bank specific access credentials. For more information see on boarding TPPs towards ASPSPs section in this documentation.
XS2A API
The payload for a session creation should be structured like this:
{
"keys": {
"hsm": String,
"aspsp_data": String
},
"selected_bank": ?{
"bank_code": String,
"country_code": String
},
"language": ?String,
"allowed_countries": ?Array<String>,
"preselected_country": ?String,
"psu": {
"user_agent": String,
"ip_address": String
},
"redirect_return_url": String
}
Auth API
The payload for a POST request that is a response to a bank_search towards the Auth API should be structured like this:
{
"keys": {
"hsm": String,
"aspsp_data": String
},
"bank_code": "81070000",
"country_code": "DE"
}
The payload for a POST request that is a response to a form towards the Auth API should be structured like this:
{
"keys": {
"hsm": String,
"aspsp_data": String
},
"ct": "AubzQQVfFsDFi+Ofm68cCzNFkrNbtP1fXanUmZHz0nzbLdUR0kYCY6Q+MGtQILqeK/SMlX/o/1KFdHSWSCl1c6k5g8xq147emOkwwMJUTFdovDkcTiq5Kcz3guO24DUwnV7r8kdmUUqJMuPhE27wsN+xJ8NgKhk/WJdim09nVBBShNQ2Skj13sq8xcDgRV1y5dGwJiqXaAeJ1a/RN7BNog==",
"iv": "4ad3c9a234ca5c3ea566d2ff4f71c748",
"ek": "Pect4rWxJrU4HREtImiKFwhC8tPSfbMU6cz+ZStoBVKamoF2vFb1jnSZPKp/h+8x3Q6Nt57odaBQWlOxwT2WCq6v2a1iTJuI7ESRw4fhw+h81i0c41HX1yuDKTgXTjJn3ucnifhQxxhJEel7A3o/hXbot/VokZ+qh6kV3hYGyjtZqQmxVbSiO1a/3nV+OJk2Rcti0yNJriPhJVEAk3/ObmbQ5pjJXVdu+ZWSMpmfuEmlTZhIw6I7mFALnQD9ausN9Sm67+nu9xwKgau+82uyjVo8A91IZIlB7zbTTPD8AkerhwBZgZb8B01/PZqx3UVJDg3v5xtehlHt0kQsseMf1A=="
}
As depicted in the last example, the keys object must not be part of the encrypted payload data.
Consent API
The payload for a POST request towards the Consent API should be structured like this:
{
"keys": {
"hsm": String,
"aspsp_data": String
},
"consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjEyMzQ1Njc4OTAifQ.na71ipK8ASvggoM6C5vMjBKgJlZLxV-m6ElgHBrNtlU",
"account_id": "fdff8f6f-d923-4489-90b3-43d11c021e1b",
"from_date": "2018-10-05",
"to_date": "2018-10-25",
"psu": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Safari/537.36",
"ip_address": "192.168.2.1",
}
}