Session

The concept of sessions was introduced to enable the execution of multiple flows in an efficient manner as the consumer has to authorize the access only once per session. For example: It might be convenient to first check the balance of an account to ensure sufficient funds for a following transfer.

Without sessions the consumer would first have to grant access to the account in order for the TPP/merchant to retrieve the balance information. Then the consumer would have to grant access to the account once again and would possibly have to provide a one-time password that could be required to complete the transfer. With sessions, the second redundant access grant is not necessary.

For this concept to work smoothly a bank and the corresponding login is bound to the session, meaning it can not be changed any more during the session.

Starting a Session

A session can be started by making a PUT request towards the XS2A API endpoint /xs2a/v1/sessions. This request needs to be authenticated.

The Request

PUT /xs2a/v1/sessions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <Token>
Host: <Host>

 <payload>
curl -X "PUT" "<Host>/xs2a/v1/sessions" \
         -H "Authorization: Bearer <Token>" \
         -H "Content-Type: application/json" \
         -d $'<payload>'

The following properties can be specified in the JSON payload:

{
    "selected_bank": ?{
        "bank_code": string,
        "country_code": string
    },
    "language": ?string,
    "allowed_countries": ?Array<string>,
    "preselected_country": ?string,
    "psu": {
        "user_agent": string,
        "ip_address": string
    },
    "consent_scope": ?{
        "accounts": ?{
        },
        "account_details": ?{
            "ibans": ?Array<string>
        },
        "balances": ?{
            "ibans": ?Array<string>
        },
        "transactions": ?{
            "ibans": ?Array<string>
        },
        "transfer": ?{
            "ibans": ?Array<string>
        },
        "insights_refresh": ?{
             "intended_reports": Array<IntendedReport>,
             "ibans": ?Array<string>,
             "insights_account_ids": ?Array<string>,
             "from_date": ?Date,
             "to_date": ?Date
        },
        "lifetime": ?integer
    }
}

selected_bank Object, optional

The object identifies the bank that should be selected for the session. If there should not be a preselected bank, the selected_bank property has to be omitted.

selected_bank.bank_code String, required

Needs to be specified if the bank search in the Open banking. by Klarna XS2A App should be skipped.

selected_bank.country_code String, required

The country_code property needs to be specified if the bank search in the Open banking. by Klarna XS2A App should be skipped. It must comply with the ISO 3166-1 alpha-2 representation of the country.

language String, optional

The language property specifies in which language the banks website will be accessed. This determines which language the consumer sees e.g in the login-form. A default language is used if the language is not specified or not supported. However caution is advised as a bank-website might not support the specified language. The language must comply with the ISO 639-1 representation of the language name.

Country code Default language Supported languages
AT de de, en
BE nl nl, fr, de, en
CH de de, fr, en
CZ en en
DE de de, en
ES en en
FI fi fi, sv, en
FR fr fr, en
GB en en
HU en en
IT it it, en
NL nl nl, en
NO nb nb, en
PL en en, en
PT en en
SE sv sv, en
SK en en, de
US en en

allowed_countries String[], optional

The allowed_countries property is used to only allow banks from the specified countries for this session. The country identifiers in the list must comply with the ISO 3166-1 alpha-2 representation of the country.

preselected_country String, optional

The preselected_country property is used to preselect a country for the Klarna bank search.

psu Object, required

The psu property contains information about the consumer (payment service user).

psu.user_agent String, required

The user_agent property holds the user agent string of the consumer's client application, e.g. the web browser.

psu.ip_address String, required

The ip_address property holds the IP address of the consumer. Both IPv4 and IPv6 are accepted formats.

consent_scope Object, optional

The consent_scope property is used to request concrete scopes before starting a flow. Specifying consent scopes may lead to fewer strong customer authentications because the customer only has to grant access for the required scopes. If the consent_scope field is not defined all AIS- and PIS-scopes are requested with a lifetime of 90 days. Scopes are only applied for PSD2 interfaces and ignored otherwise.

consent_scope.lifetime Integer, optional

The lifetime property defines how many days the consent should be valid. The default value if not defined and the allowed maximum is 90 days.

consent_scope.<flow_type> Object, optional

As depicted in the JSON structure above, the consent can be scoped for one or multiple flows by providing a consent_scope.<flow_type> property with <flow_type> being one of the flow types (accounts, account_details, balances, transactions, transfer, insights_refresh). The default value for this parameter is an empty object.

consent_scope.<flow_type>.ibans String[], optional

A list of sender IBANs can be provided in the ibans property in order to restrict the scope for the flow type to the specified IBAN(s).

ibans is a valid property for all but the accounts flow as this is used to obtain the IBANs of a consumer.

consent_scope.insights_refresh Object, optional

The insights_refresh flow requires more detailed information. It is needed to provide all data for the required flows, which would be triggered by the insights_refresh flow. This will be determined by the intended_reports property.

consent_scope.insights_refresh.intended_reports IntendedReport, optional

With the intended_reports property the kind of insights will be determined. This will trigger other flows, which might require some additional information (e.g. the from_date property).

consent_scope.insights_refresh.insights_account_ids String[], optional

A list of Account Insights identifiers reprenting an account used by a previous insights_refresh flow.

consent_scope.insights_refresh.from_date Date (String: "YYYY-MM-DD"), optional

The from_date property (in combination with the to_date property) will be used as the start date for the account information to be retrieved. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

consent_scope.insights_refresh.to_date Date (String: "YYYY-MM-DD"), optional

The to_date property (in combination with the from_date property) will be used as the end date for the account information to be retrieved. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

For further configuration on the session creation call a white label integrator can visit the White Label Integration section.

{
...
    "consent_scope": {
        "accounts": { },
        "account_details": { },
        "balances": { },
        "transactions": { },
        "lifetime": 1
    },
...
}

The Response

After a successful call is made the following response is returned along with a 201 CREATED status code:

HTTP/1.1 201 Created
Content-Type: application/json
{
    "data": {
        "session_id": string,
        "session_id_short": string,
        "self": url,
        "consent": url,
        "flows": {
            <flow_type>: url,
            ...
        }
    }
}

data Object, always present

The data property wraps the actual information in every response returned by the XS2A-API and has no other purpose.

data.session_id String, always present

The session_id property holds a unique id which identifies the XS2A-API session. This id should be saved for later use and debugging purposes.

data.session_id_short String, always present

The session_id_short property holds a non-unique 8 character code. The code can be shown to the consumer and used for interaction with customer service.

data.self URL, always present

The self property holds a url which identifies the session and has to be saved for further calls. This url is bound to the session and can not be used for other sessions.

data.consent URL, always present

The consent property holds a url which can be called to retrieve the consent, if available. This url is bound to the session and can not be used for other sessions.

For more information see the documentation about fetching the consent token.

data.flows Object, always present

The flows property is a map that holds flows. Each entry in the flows property represents a flow of the type specified by the entry's key (flow_type). The value of an entry is the url that, when called, starts a flow of the specified type.

Getting Information about a Session

The Request

In order to obtain information about a session on the XS2A-API the self-url that is returned in the CREATE call when initiating a session needs to be called with GET:

GET <session.self> HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <Token>
curl "<session.self>" -H "Authorization: Bearer <token>"

There is no payload attached.

The Response

After a successful call is made the following response is returned:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "session_id": string,
        "session_id_short": string,
        "state": enum<'IN_FLOW', 'IDLE', 'EXCEPTION', 'CLOSED'>,
        "current_flow": ?{
            "flow_id": string,
            "url": string,
            "type": string
        },
        "previous_flows": Array<{
            "flow_id": string,
            "url": string,
            "type": string
        }>,
        "bank": {
            "bank_name": ?string,
            "country_code": ?string,
            "bank_code": ?string,
            "connection": ?enum<'PSD2', 'FALLBACK'>
        },
        "consumer_id": ?string
    }
}

data Object, always present

The data property wraps the actual information in every response returned by the XS2A-API and has no other purpose.

data.session_id String, always present

The session_id property holds a unique id which identifies the XS2A-API session.

data.session_id_short String, always present

The session_id_short property holds a non-unique 8 character code. The code can be shown to the consumer and used for interaction with customer service.

data.state Enum, always present

The state property holds the current state of the session that can be one of the following:

  • IN_FLOW - Currently in a running flow. The flow must be aborted or finished before the session can start a new flow or be closed.
  • IDLE - Currently not in a running flow but still open. Both starting a new flow and closing the session is possible.
  • EXCEPTION - Session ended in an exception and can not be used anymore.
  • CLOSED - Session is closed and can not be used anymore.

data.current_flow Object, optional

The current_flow property holds information about the currently running flow in the session.

data.current_flow.flow_id String, always present

The id of the flow

data.current_flow.url URL, always present

A url to call in order to get the state of the flow (see Retrieving Information about a Flow for more information).

data.current_flow.type String, always present

The type of the flow (see XS2A-API for a list of possible flow types).

data.previous_flows Object[], always present

The previous_flows property is an array holding all flows that were executed before.

The properties of the objects in the previous_flows array are the same as those listed for the current_flow object.

data.bank Object, always present

The bank property holds information about the selected bank in the session. All fields are optional and may be filled during the execution of a flow.

data.bank.bank_name String, optional

The bank_name property holds the name of the chosen bank.

data.bank.country_code String, optional

The country_code property holds the ISO 3166-1 alpha-2 country code of the chosen bank.

data.bank.bank_code String, optional

The bank_name property holds the bank code of the chosen bank.

data.bank.connection Enum, optional

The connection property holds the type of the integration towards the bank. Possible values are PSD2 and FALLBACK.

data.consumer_id String, optional

The consumer_id identifies the consumer throughout multiple sessions. It has a maximum length of 512 characters. The field will only be available after the consumer has successfully logged in.

Closing a Session

XS2A sessions should be closed as soon as possible because this, in turn, allows the XS2A API to close the session with the bank. An unclosed session between the XS2A API and the bank might influence or interfere with the consumer's future interaction with the bank.

A quick progression through the XS2A session also reduces the risk of "losing" sessions as some banks terminate sessions that have been inactive for some time. Sessions that have run in such a timeout on bank-side can not be interacted with anymore. Furthermore, these sessions are not ended "properly" and thus sometimes influence the consumer's future interaction with the bank as well.

Data from XS2A sessions with a terminated bank session can still be retrieved up to 30 minutes after the last interaction with the XS2A session. When the XS2A session expires or is closed, the data is deleted from Klarna's systems and can thus not be retrieved anymore.

How to close a Session

A running session can be closed by making a DELETE request towards the self-url that is returned when initiating a session.

The Request

DELETE <session.self> HTTP/1.1
Authorization: Bearer <Token>
curl -X "DELETE" "<session.self>"
         -H "Authorization: Bearer <token>"

There is no attached payload.

The Response

After a successful call is made the following response will be returned:

HTTP/1.1 204 No Content

Alternatively a 409 CONFLICT status code will be returned if there is still a running flow for the session:

HTTP/1.1 409 Conflict
Content-Type: application/json

The response holds the following payload:

{
    "data": {
        "code": "CONFLICT",
        "message": "Session with id <session.session_id> is still in running flow, finish/end all running flows before closing session"
    }
}

results matching ""

    No results matching ""