Web NPM SDK (v1 and earlier)

πŸ‘

[ACTION REQUIRED] Origin URL Whitelisting

In order to bolster security on our platform, Aeropay will need to whitelisting any origin URLs using the Aerosync Web NPM SDK in production.

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

Introduction

This NPM package provides an interface to load Aerosync-UI in Javascript/typescript application. Securely link your bank account through your bank’s website. Log in with a fast, secure, and tokenized connection. Your information is never shared or sold.

πŸ“˜

NPM Package Versioning

For all new Aeropay integrations, please use v1.0. Versions 2.0 and later are still in beta and may be unstable.

1. Install Aerosync Web NPM SDK

2. Create the necessary HTML elements to trigger and host the AeroSync widget

<!-- 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"
  class="button"
  role="button"
  @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="widget"></div>

3. Import and Configure the 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 Aerosync in your app, create a widgetRef object as show below :

/**
 * Step-by-step integration of AeroSync AddBank widget
 */
import type {
  AerosyncWidget,
  WidgetEventSuccessType,
  WidgetEventType,
} from "aerosync-web-sdk";
import { initAeroSyncWidget } from "aerosync-web-sdk";

function openAerosyncWidget() {
  // Initialize the widget with configuration options
  let widgetControls = initAeroSyncWidget({
    elementId: "widget", // πŸ‘ˆ ID of the target div in your HTML
    iframeTitle: "Connect", // πŸ”’ Used for accessibility
    environment: "production", // 🌍 Set to 'sandbox' for testing, 'production' for live
    token: "xxxx", // πŸ”‘ Your secure AeroSync token
    theme: "light", // 🎨 Choose between 'light' or 'dark' theme

    // πŸ“¦ Event listener for all widget events
    onEvent(event: WidgetEventType) {
      console.log("event", event);
    },

    // πŸš€ Fires when the widget is fully loaded
    onLoad() {
      console.log("onload");
    },

    // βœ… Called after the user successfully connects a bank and closes the widget
    onSuccess(event: WidgetEventSuccessType) {
      console.log("onSuccess", event);
      // ...
      // Handle success (e.g., update UI, send data to backend, etc.)
    },

    // ❌ Fires when the widget is closed manually by the user
    onClose() {
      console.log("widget closed");
    },

    // ⚠️ Catch and handle widget errors
    onError(event: string) {
      console.log("onError", event);
    },
  });

  // 🧭 Launch the widget
  widgetControls.launch();
}

4. Widget configuration

Configure your environment for sandbox (https://www.sandbox.aerosync.com) or production (https://www.aerosync.com). Additionally configure an id, iframeTitle, width, and height of the window.

ParameterTypeRequiredDescription
tokenstringYesRequest AeroSync Token using GET /aggregatorCredentials endpoint.
Reference:
https://api-aeropay.readme.io/reference/aggregatorcredentials
https://developer.aeropay.com/api/aeropay/doc/
elementIdstringYesSpecifies a unique id for an HTML element. The default value is "widget".
iframeTitlestringYesAdds title text to the iframe.
widthstringYesSpecifies the width of the iframe in pixels.
heightstringYesSpecifies the height of the iframe in pixels.
environmentstringYesPermitted values are [sandbox, production]
deeplinkstringConditionalAerosync will redirect to this link on mobile app after authentication to resume the workflow for OAuth bank experiences
Required for mobile applications.
Not required for web applications. You can send the deeplink as empty string. Eg: let deeplink:string = ""
For more guidance refer to our article here
targetDocumentShadowRootNoThe widget will be rendered inside the shadow dom instead of root document
consumerIdstringNoUnique ID assigned to you to apply widget customizations.
zIndexstringNoTo override the stacking order of the widget elements provide the appropriate value. The default value is 1.
manualLinkOnlybooleanNoUser will only be able to link their bank manually.
embeddedBankViewobject (embeddedBankViewType)NoEnables embedding the bank view directly inside a custom container. Requires an elementId. Optional properties include width, height, and a callback onEmbedded() that is triggered when the embedded view is ready. Example:
{
elementId: 'embeddedId',
width: '572px',
height: '348px',
onEmbedded: () => { //onEmbedded ready} }

For more information, click here: https://dev.aero.inc/docs/embedded-view
styleobjectNoAllows you to customize the widget’s appearance. You can set width, height, bgColor, and opacity.
Example: { width: '375px', height: '688px', bgColor: '#000000', opacity: 0.7 }

5. Define postMessage events

ParameterTypeRequiredDescription
onLoadfunction(response)NoCall JavaScript function after the contents of a webpage have been loaded.
onSuccessfunction(response)YesThis method will be triggered when a bank is added successfully and the user clicks on "continue" button in the final AeroSync-UI page.
onErrorfunction(response)YesThe method is called if AeroSync-UI dispatches any error events.
onClosefunction()YesThis event will be triggered if the user closes the AeroSync-UI window.
onEventfunction(response)NoAeroSync-UI will trigger event on each page load.