Javascript-Widget

Seamlessly embedded in the browser or as webview solution in your app

We recommend this method because it is the most efficient way to integrate the highly complex flow of providing a seamless interaction between the customer and the bank.

Overview

The JavaScript-Widget (JS-Widget) is a complete implementation of the user-facing process during an XS2A transaction. The user-facing process consists of multiple steps that occur in various orders:

Selecting the bank
Providing credentials for the login to the bank
Selecting the TAN procedure and medium if required
Redirecting the user to the bank if required

The exact process varies from bank to bank and from user to user.

The Javascript-Widget encapsulates these steps into a single, encapsulated, and highly customizable piece of software that can be seamlessly integrated into any webpage.

Embedding is done with very few lines of code.

How to use

To use our Javascript-Widget the first thing to do is to include the Javascript and base CSS files into your integration.

Include xs2a.js in your page:

<!doctype html>

<html lang="en">
  <head>
    <meta charset="utf-8">

    <title>XS2A Example</title>
    <meta name="description" content="The XS2A Example">
    <meta name="author" content="Tink Germany">

    <script src="https://api.xs2a.com/xs2a.js"></script>
  </head>

  <body>

  </body>
</html>

<script src="https://api.xs2a.com/xs2a.js"></script>

The Widget will render all needed steps in the process itself. It needs a container in the DOM where this should be done.

You need a wizard session key to initialize the widget. This key holds the configuration for the session you want to display to the user.

Please read one of the following guides to get a wizard session key:

Payment Platform (XS2A.pay)Analytics Platform (XS2A.risk)Open Banking Platform (XS2A.api)

After you received a wizard session key from our API you can initialize the widget.

<!doctype html>

<html lang="en">
  <head>
    <meta charset="utf-8">

    <title>XS2A Example</title>
    <meta name="description" content="The XS2A Example">
    <meta name="author" content="Tink Germany">

    <script src="https://api.xs2a.com/xs2a.js"></script>
    <link rel="stylesheet" href="https://api.xs2a.com/xs2a.css">
  </head>

  <body>
    <noscript>
      <h2>Your browser does not support JavaScript.</h2>
      Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
    </noscript>
    <div id="XS2A-Form" data-xs2a="your-wizard-session-key-here"></div>
  </body>
</html>

You need to replace your-wizard-session-key-here with your real key received by our API.

The Widget is now able to start, to do so we need to initialize it. There are two mandatory callbacks to register finish() and abort().

For more information about the initialization, the callbacks or configuration of the widget please read our technical API documentation.

API documentation

<!doctype html>

<html lang="en">
  <head>
    <meta charset="utf-8">

    <title>XS2A Example</title>
    <meta name="description" content="The XS2A Example">
    <meta name="author" content="Tink Germany">

    <script src="https://api.xs2a.com/xs2a.js"></script>
    <link rel="stylesheet" href="https://api.xs2a.com/xs2a.css">
    <link rel="stylesheet" href="https://api.xs2a.com/xs2a-responsive.css">
  </head>

  <body>
    <noscript>
      <h2>Your browser does not support JavaScript.</h2>
      Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
    </noscript>
    <div id="XS2A-Form" data-xs2a="your-wizard-session-key-here"></div>
    <script>
      // Loads the xs2a_base.css file.
      xs2a.useBaseStyles();

      xs2a.finish(() => {
        // Called when the session is finished
        document.location.href = 'your-success-link';
      });

      xs2a.abort(() => {
        // Called when the session is aborted
        document.location.href = 'your-abort-link';
      });

      // Start the wizard
      xs2a.init();
    </script>
  </body>
</html>

// Loads the xs2a_base.css file.
xs2a.useBaseStyles();

xs2a.finish(() => {
  // Called when the session is finished
  document.location.href = 'your-success-link';
});

xs2a.abort(() => {
  // Called when the session is aborted
  document.location.href = 'your-abort-link';
});

// Start the wizard
xs2a.init();

Receiving errors

It is important to register the error callback as well as the mandatory ones. In this callback, you will receive information about occurring errors during the session. You can store these errors in your system or react to them with special behavior.

Be sure you register this callback before the init call.

xs2a.error((errorCode, messages, recoverable) => {
  console.error(errorCode, messages, recoverable);
});

Result

The Widget will now initialize and generates the needed steps itself.

Styling

The widget generates HTML DOM Elements that can be styled with normal CSS rules. You can look into our default xs2a_base.css file for all variables as a reference or generate a set of rules fully based on your needs.

:root {
  --xs2a-primary: blue;
  --xs2a-error: red;
  --xs2a-warning: yellow;
  /* other overwrites, see top of xs2a_base.css file for all variables */
}

As long as there are no legal problems due to hiding our logo or similar everything can be styled to match the look of the page the widget is embedded to.

In case you run into CSP-related issues or the like with xs2a.useBaseStyles(), you can manually include the xs2a_base.css:

<!-- Optional, in case of issues with xs2a.useBaseStyles() -->
<link rel="stylesheet" href="https://api.xs2a.com/xs2a_base.css">

PreviousIntegration Variants NextWebview App Integration

Last updated 2 years ago

Was this helpful?

Javascript-Widget

Overview

How to use

Including the Widget into your integration

Include a container for the Widget

Start the Widget

Receiving errors

Result

Styling

Overview

How to use

Including the Widget into your integration

Include a container for the Widget

Start the Widget

Receiving errors

Result

Styling