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 call has a parameter called 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.

Also there is a redirect_return_url parameter which is a string. This property defines the URL to which the consumer is redirected after the interaction with the bank's website is completed.

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 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",
    }
}