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, i.e. 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 a 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
    },
    "redirect_return_url": ?string
}

The selected_bank property holds an object that 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.

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

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.

The allowed_countries property is used to block 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.

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

The psu property holds an object that contains information about the consumer (payment service user).

The user_agent property holds the user agent string of the consumer's client application, e.g. the web browser. The ip_address property holds the IP address of the consumer. Both IPv4 and IPv6 are accepted formats.

The redirect_return_url property defines the URL to which the consumer is redirected after the interaction with the bank's website is completed. The redirect_return_url property can only and has to be specified by white label TPPs.

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,
        "flows": {
            <flow_type>: url,
            ...
        }
    }
}

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

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.

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.

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.

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

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_name": ?string,
        "consumer_id": ?string
    }
}

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

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

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.

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.

The current_flow & previous_flows properties hold information about the flows inside the session. current_flow is the currently running flow and previous_flows is an array holding all flows which were executed before.

The flow-objects hold the following information:

• flow_id - the id of the flow
• url - a url to call in order to get the state of the flow (see Retrieving Information about a Flow for more information)
• type - the type of the flow (see XS2A-API for a list of possible flow types)

The bank_name property represents the name of the chosen bank. This field is optional and may be filled during the execution of a flow.

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

Closing a Session

XS2A API sessions should be closed as soon as possible to enable the XS2A API to also close the session with the bank. However, it has to be noted that data can not be retrieved anymore after a session has been closed.

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