XS2A App

The Open Banking XS2A App handles all consumer interactions. It is used whenever the API flow requires an input from the consumer, such as selecting the consumer bank or the strong customer authentication towards the bank. In addition, depending on the selected flow, the XS2A App may be used to select a specific bank account or to authorize an account-to-account payment.

Usage

Initializing the App and setting the Configuration

To open the XS2A App the provided library has to be included via script-tag.

<script>
    window.onXS2AReady = XS2A => {
        // configure once for all flows (optional)
        window.XS2A.configure({
            appearanceMode: 'light',
            autoClose: true,
            hideTransitionOnFlowEnd: true,
            openPoliciesInNewWindow: true,
            psd2RedirectMethod: 'newWindow',
            skipInitialLoader: false,
            theme: 'default',
            unfoldConsentDetails: false,
            onLoad: () => {
                console.log('onLoad called')
            },
            onReady: () => {
                console.log('onReady called')
            },
            onAbort: () => {
                console.log('onAbort called')
            },
            onError: error => {
                console.log('onError called', error)
            },
            onFinished: () => {
                console.log('onFinished called')
            },
            onClose: () => {
                console.log('onClose called')
            },
        })
    }
</script>
<script src="https://x.klarnacdn.net/xs2a/app-launcher/v0/xs2a-app-launcher.js"></script>

A preconfigured window.onXS2AReady-callback will be called once the launcher has been set up. Thereafter the XS2A object is attached to the window (window.XS2A). It's recommended to define a default configuration, which will be used for all startFlow function calls, in this callback.

Starting a Flow

A Flow can be started using the startFlow method. After retrieving a client token from our XS2A API it has to be passed to the library.

try {
    // override parts of the configuration just for this flow
    window.XS2A.startFlow(
        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cHWL6MGW4LeYvnm1JA',
        {
            onLoad: () => {
                console.log('onLoad called #2')
            },
        }
    )
} catch (e) {
    // Handle error.
}

If a configuration object was provided as the optional second parameter, it's merged with the default configuration.

Closing the App

The App can be closed at any time using the close() function.

// close the xs2a app modal with this function immediately
window.XS2A.close()

Configuration and Callbacks

All configuration options in detail:

Callbacks that are available in the configuration object in detail:

The error object has the following structure:

{
    "category": String, // represents the category of the error
    "message": ?String, // text to be displayed to the user (optional)
    "reason": ?Error, // caught `error`-object if there was an internal js-error (optional)
}

All possible error categories can be found here.

Examples

Starting multiple consecutive flows:

try {
    // you can override parts of the configuration just for this flow
    window.XS2A.startFlow(
        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cHWL6MGW4LeYvnm1JA',
        {
            autoClose: false, // don't close the App after the first flow is finished
            hideTransitionOnFlowEnd: false, // keep transition on screen while you can do things in the onFinished callback
            onFinished: () => {
                // start second flow after first flow
                window.XS2A.startFlow(
                    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXoifQ.jhYdghVeKsi7Y-tdsiSpwuplzjZaSseUcmdoudKbdnQ'
                )
            },
        }
    )
} catch (e) {
    // Handle error.
}

In this example we want to start another flow after the first has finished. For a smooth transition between the flows the success screen should not be shown after the first flow. Using the hideTransitionOnFlowEnd option it is possible to keep the transition screen open until the next flow will start. For the second startFlow call the option hideTransitionOnFlowEnd is not overridden, so the default value (true) is kept.