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:

Name Type Default Functionality
appearenceMode String 'light' if set to 'dark', the app will render in dark mode, for 'system' the system setting shall be used
autoClose Boolean true if set to false the app will not close automatically after 3 seconds when flow is finished
hideTransitionOnFlowEnd Boolean true if set to false the last transition before the flow is finished will remain open
openPoliciesInNewWindow Boolean true if set to false the privacy policy will be shown in the XS2A App and not a new window
psd2RedirectMethod String 'newWindow' defines how redirects are handled in the XS2A App (options are 'newWindow' or 'sameWindow'). More details for embeddeding the XS2A App in mobile apps can be found here.
skipInitialLoader Boolean false defines if the initial loader shall be skipped
theme String 'default' sets the theme of the App (options are 'default' or 'embedded')
unfoldConsentDetails Boolean false if set to true the consent details in the footer of the App will be opened by default

Callbacks that are available in the configuration object in detail:

Callbacks Functionality
onLoad() will be called when the XS2A App will be loaded.
onReady() will be called when the XS2A App is ready for user interaction.
onAbort() will be called when the user has aborted the XS2A App.
onError(error) will be called when the XS2A App encounters an error which it cannot handle itself. This likely means that the flow and the session is in an unrecoverable error state.
onFinished() will be called when the initialized flow has finished without any error.
onClose() will be called when the XS2A App has closed. Will be called after onAbort, onError and onFinished.

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.

results matching ""

    No results matching ""