📘

[ACTION REQUIRED] Origin URL Whitelisting

In order to bolster security on our platform, Aeropay will need to whitelist any origin URLs using the Aerosync CDN in production.

Prior to go-live, please share your origin URLs with your Aeropay representative to be whitelisted.

Introduction

This CDN-hosted JavaScript package allows you to easily integrate a secure bank account linking experience into any web application without requiring a build process. With a simple script tag, you can embed a fast, tokenized, and secure flow that connects users to their bank through their official online banking portal. The integration ensures that user credentials are never stored, shared, or exposed — maintaining strict privacy and security standards.

1. Installation

Add the CDN Script Tag

Add the following script tag to your HTML to include the widget:

<script src="https://cdn.sync.aero.inc/2.1.5/aerosync-widget.js"></script>

Content Security Policy (CSP)

If your application uses CSP headers, ensure the following directive is included to allow loading the widget from our CDN:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.sync.com;
  connect-src 'self' https://api.aerosync.com;
  frame-src https://cdn.sync.com;

📋

If you are using the sandbox environment, update theconnect-src directive as follows::

connect-src 'self' https://api.sandbox.aerosync.com;

2. Set Up HTML Elements for the Aerosync Widget

Add a button to launch the widget and a container element where the widget iframe will be rendered.

<!-- Button to launch the AeroSync widget -->
<!-- 'id' is optional but useful for CSS/JS targeting -->
<!-- Vue syntax, replace with onclick="openAerosyncWidget()" if using plain JS -->
<button
  id="openBank"
  @click="openAerosyncWidget()"
>
  Connect Bank
</button>

<!-- This div is where the AeroSync widget iframe will be embedded -->
<!-- Make sure the 'id' here matches the 'elementId' passed during initialization -->
<div id="widgetId"></div>

3. Import and Configure the AeroSync Widget

3.1 Creating a AeroPass User

The Web+Aeronetwork workflow require a user identifier, aeroPassUserUuid, to be passed to the widget on launch. Follow the guide here to create a new user and access the user's aeroPassUserUuid.

3.2 Load AeroSync Widget

👍

Fetch SDK token GET /aggregatorCredentials

The token for the Aerosync SDK will be returned in the response to GET /aggregatorCredentials. Read the Aerosync guide for details.

To initialize the AeroSync widget in your app, create a reference to the widget and load the configuration parameters. Below is an example of how to integrate and launch the widget.

// Function to initialize and open the AeroSync widget
function openAerosyncWidget() {

  // Initialize the widget using the global aerosync object
  const widgetControls = window?.aerosync?.initWidget({
    elementId: 'widgetId', // ID of the DOM element where the widget will be attached
    iframeTitle: 'Connect', // Title for the iframe
    environment: 'production', // Widget environment (e.g., 'sandbox' or 'production')
    token: 'XXXX', //  AeroSync token (Important: Do not use an AeroPay token)
		aeroPassUserUuid: "XXXX", // Aeropass user id
    configurationId: 'XXXX', // Aeorsync configuration ID (optional)

    // Event callback for various widget lifecycle events
    onEvent: function(event) {
      console.log('onEvent', JSON.stringify(event))
    },

    // Called when the widget is fully loaded
    onLoad: function() {
      toast.info('Sync onload')
    },

    // Called on successful sync completion
    onSuccess: function(event) {
      console.log('onSuccess', JSON.stringify(event))
    },

    // Called when the widget is closed
    onClose: function() {
      console.log('Sync onclose')
    },

    // Called when an error occurs
    onError: function(error) {
      console.log('onError', error)
    }
  })

  // Launch the widget UI
  if (widgetControls) {
    widgetControls.launch()
  }
}

4. Handle OAuth Bank Authentication

Aerosync launches the OAuth URL in the external system browser by default. If you want to manually handle the OAuth URL within the Capacitor in-app browser, you can capture the event as shown below:

4.1 Enable Manual OAuth Handling

Set handleOAuthManually to true in the widget configuration of the Web SDK to prevent Aerosync from automatically launching the OAuth window. This gives you control to trigger the OAuth flow manually when needed.

4.2 Launch OAuth Manually via URL

Listen for the onEvent callback to receive the OAuth URL. Then open it using an in-app browser or system browser, based on your app’s flow.

// 📦 Event listener
async onEvent(event) {
  try {
    // Check if the app is running on a native platform (iOS or Android)
    if (Capacitor.isNativePlatform()) {
      // Verify that the event payload exists, pageTitle equals "launchExternalWindow",
      // and onLoadApi URL is present
      if (
        event?.payload?.pageTitle === "launchExternalWindow" &&
        event?.payload?.onLoadApi
      ) {
        // Open the URL in Capacitor's in-app browser
        await Browser.open({ url: event.payload.onLoadApi });
      }
    }
  } catch (error) {
    console.error("Failed to open URL in Capacitor Browser:", error);
  }
}

5. Widget configuration

The AeroSync widget accepts a set of configuration parameters that control its behavior, appearance, and integration flow. The table below outlines each parameter, its type, requirement level, and purpose. Use this as a reference when initializing the widget in your application.

6. Define postMessage events

6.1 WidgetEventSuccessType

6.2 WidgetEventType

6.3 WidgetEventPayloadType