React Native SDK (v3 and earlier)

Introduction

This React Native SDK provides an interface to load Aerosync-UI in React Native 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.

📘

React Native Package Versioning

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

1. Install and Link Aerosync React Native SDK

Install the aerosync-react-native-sdk library along with its required peer dependency, react-native-webview:

npm install aerosync-react-native-sdk react-native-webview

Note: react-native-webview is a required peer dependency for aerosync-react-native-sdk.

iOS Setup

  1. Navigate to the ios directory and install CocoaPods dependencies:
    cd ios
    pod install
    
  2. Ensure your iOS deployment target is 11.0 or higher.

Android Setup

  1. Make sure the following permission is added to your AndroidManifest.xml, if required:
    <uses-permission android:name="android.permission.INTERNET" />
    
  2. Autolinking should handle the native module setup automatically—no manual changes needed.

2. Minimal example to implement Aerosync React Native Sdk

👍

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.

AddBank.js

import { 
  AeroSyncWidget, 
  SuccessEventType, 
  WidgetEventType, 
} from "aerosync-react-native-sdk";

import { SafeAreaView, ScrollView, StyleSheet, Text, View } from "react-native";
import { useState } from "react";
import Toast from "react-native-toast-message";
import Modal from 'react-native-modal';
import { useStore } from "../context/StoreContext";
import { useThemeContext } from "../context/ThemeContext";
import { Button } from "react-native-paper";

export default function PaymentScreen() {
  const { widgetConfig } = useStore();
  const { isDarkTheme } = useThemeContext();
  
  // State to control whether the widge is shown
  const [isWidgetEnabled, setIsWidgetEnabled] = useState(false);
  
  // Determine widget theme based on app theme
  const currentTheme = isDarkTheme ? 'dark' : 'light';

  // Deeplink scheme used for routing back from external services
  const DEEP_LINK = 'syncroVibeReactCli://';

  // --- Callback: Widget loaded successfully
  const onWidgetLoad = () => {
    console.log('Widget loaded');
  };

  // --- Callback: Widget was closed (either manually or automatically)
  const onWidgetClose = () => {
    console.log('Widget closed');
    setIsWidgetEnabled(false);  // Hide widget modal
  };

  // --- Callback: User successfully linked their bank and widget closed
  const onWidgetSuccess = (event: SuccessEventType) => {
    console.log('Bank linking successful', event);
    setIsWidgetEnabled(false);  // Hide widget modal

    // Show a toast to inform the user of success(optional)
    Toast.show({
      type: 'success',
      text1: 'Bank linked successfully!',
    });
  };

  // --- Callback: Fired on every widget event
  const onWidgetEvent = (event: WidgetEventType) => {
    console.log('Widget event:', event);
  };

  // --- Callback: Widget encountered an error
  const onWidgetError = (event: string) => {
    console.log('Widget error:', event);
  };

  const showWidget = () =>  {
    setIsWidgetEnabled(true)
  }

  return (
    <SafeAreaView style={{ flex: 1 }}>
      
      {/* 
  			Full-screen modal to display the AeroSync widget to link a bank.
  			This modal is optional — you can customize or replace it with your own 
        layout/styling as needed.
			*/}
      <Modal
        style={styles.modal}
        isVisible={isWidgetEnabled}
        propagateSwipe
        animationIn="slideInUp"
        animationOut="slideOutDown"
        animationInTiming={600}
        animationOutTiming={600}
      >
        {/* AeroSync Widget: bank linking process */}
        <AeroSyncWidget 
          onLoad={onWidgetLoad}
          onError={onWidgetError}
          onClose={onWidgetClose}
          onEvent={onWidgetEvent}
          onSuccess={onWidgetSuccess}
          token={widgetConfig?.token!}
          deeplink={DEEP_LINK}
          theme={currentTheme}
          consumerId={widgetConfig?.configurationId}
          environment={widgetConfig?.environment!}
          customWebViewProps={{
            style: { marginTop: 30, backgroundColor: isDarkTheme ? '#000000' : '#FFFFFF' }
          }}
        />
      </Modal>

      {/* Main content area */}
      <ScrollView>
        <View style={styles.container}>
          <Text style={styles.title}>Select a payment method</Text>
          <Button mode="contained"  style={styles.linkButton} onPress={showWidget}>
                Link new bank
          </Button>
        </View>
      </ScrollView>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    justifyContent: 'flex-start',
    backgroundColor: '#fff',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 20,
    textAlign: 'center',
  },
  linkButton: {
    marginBottom: 20,
    justifyContent: 'center', 
    alignItems: 'center',
    width: '100%',
    height: 60,
    backgroundColor: '#80bfff'    
  },
  modal: {
    justifyContent: 'flex-end',
    margin: 0,
  },
});

Note: The onClose and onSuccess event in the example above should be updated with respect to the navigation. For onClose event, navigate back to the same screen where the AeroSync widget can be launched again. Since the user closed the widget manually they can retry if needed. For onSuccess event, navigate to the next screen where the user will continue after the bank is linked successfully.

3. Aerosync Sdk configuration

ParameterTypeRequiredDescription
tokenstringYesRequest AeroSync Token using GET /aggregatorCredentials endpoint.
Reference:
https://api-aeropay.readme.io/reference/aggregatorcredentials
https://developer.aeropay.com/api/aeropay/doc/
environmentstringYesPermitted values are [sandbox, production]
deeplinkstringYesAerosync will redirect to this link on mobile app after authentication to resume the workflow. For more guidance refer to our article here
consumerIdstringNoUnique ID that represents the client to apply the customization.
onSuccessfunction(response)YesThis event will be triggered when bank is added successfully in the final page of AeroSync-UI. See section 5 for more information.
onCloseonLoadYesThis event will be triggered if the user closes the AeroSync-UI window. See section 5 for more information.
onEventfunction(response)NoAeroSync-UI will trigger event on each page load. See section 5 for more information.
onErrorfunction(error)NoThe method is called if AeroSync-UI dispatches any error events. See section 5 for more information.
onLoadfunction(response)NoAeroSync-UI will trigger this event when the widget is loaded.
stateCodestringNostateCode is required in embedded flow when user clicks on a bank.

4. Aerosync-UI Response:

aerosync-react-native-sdk will send response for below events:

4.1 onSuccess event

This event will be triggered when a bank is added successfully and the user clicks on "continue" button in the final AeroSync-UI page. Example of response is shown below:

 {  
    "ClientName": "client3",  
    "FILoginAcctId": "{\"u_guid\":\"USR-701a457e-5b93-4598-b7a1-b968c495ee3f\", \"m_guid\": \"MBR-d699c457-90f7-4b96-96c1-c50a445eabec\", \"a_guid\": \"ACT-9f5549d6-e402-43f4-8351-cd4018de7a80\"}",  
    "user_id": "a2c7f64f-3df9-4090-b3bd-ad6fc3003c90",  
    "user_password": "735e33b9-78ec-4887-99d7-a3056997ceb9"  
  }

4.2 onClose event

This event will be triggered when the user closes the AeroSync-UI window. If the user closes the AeroSync-UI window by tapping the 'X' button on any page, the callback function will be called which can be used to navigate the user to the previous page on parent component.

4.3 onEvent event

AeroSync-UI will trigger event on each page load. The response will contain the follow attributes:

{
  "pageTitle": "Verify Your Identity",
  "onLoadApi": "/token",
 }

4.4 onError event

This event will be triggered if the WebView or AeroSync-UI fails to load. The response will be string describing the error.

4.5 onLoad event

This event will be triggered when the Aerosync widget is loaded for the first time.

5. Common Issues:

5.1 If you're getting Invariant Violation: Native component for "RNCWebView does not exist", it means react native autolinking did not work. Try linking it manually using below resources:

Android (link edits 3 files):
Resource: https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b

IOS (link manually)
Explicitly install in the Root project:
npm i react-native-webview cd ios; pod install