Bank Account Module

This guide provides all the necessary steps to integrate and configure the Bank Account Module, allowing you to easily add or update user bank account information within your application.

Getting Started

Follow the three steps below for a basic implementation of the module. This setup will render the UI for adding a new bank account.

Step 1: Add the HTML Container

First, place an empty div element with the ID i-payoutUI in your HTML file where you want the UI to appear.

<div id="i-payoutUI"></div>

Step 2: Install the Script

Next, include the bankAccountModule.bundle.js script in your HTML page. The defer attribute is recommended to ensure the HTML is parsed before the script executes.

<script defer src="bankAccountModule.bundle.js"></script>

📘
Dynamic Script Loading
If the static script tag causes issues, you can load the script dynamically using JavaScript. This method programmatically creates a script tag and appends it to the document's body.
let bankAccountModuleScript = document.createElement('script');

// Set the path to the bundle file
bankAccountModuleScript.src = 'bankAccountModule.bundle.js';
bankAccountModuleScript.defer = true;
// Append the script to the body
document.body.appendChild(bankAccountModuleScript);

Step 3: Configure the Module

Finally, create a <script> tag before the bundle script and define the global configuration object window.bankAccountModuleConfig. You must provide the required properties to initialize the module.

Putting it all together, a minimal HTML page would look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-t" />
    <title>i-payout Drop-in UI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <div id="i-payoutUI"></div>

    <script>
      window.bankAccountModuleConfig = {
        authToken: 'YOUR_JWT_AUTH_TOKEN',
        beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
        merchantId: 'YOUR_MERCHANT_ID'
      };
    </script>

    <script defer src="bankAccountModule.bundle.js"></script>
  </body>
</html>

Configuration (`bankAccountModuleConfig`)

The window.bankAccountModuleConfig object is used to control the behavior and appearance of the module. It consists of required and optional properties.

Required Properties

These properties are mandatory for the module to function correctly.

Property	Type	Description
`authToken`	`string`	A JSON Web Token (JWT) used for authenticating API requests.
`beneficiaryToken`	`string`	The unique identifier for the user (beneficiary).
`merchantId`	`string`	The unique identifier for your merchant account.

Optional Properties

These properties allow you to enable different modes, handle events, and customize the UI.

Property	Type	Description
`bankAccountToken`	`string`	The token for an existing bank account. Providing this token switches the module to update mode.
`lang`	`string`	Sets the display language. Defaults to `"EN"`.
`events`	`object`	An object containing callback functions to handle module events. See Event Handling.
`labels`	`object`	An object to override default UI text like titles and button labels. See UI Customization.
`styles`	`object`	An object to customize the look and feel using inline CSS or CSS classes. See UI Customization.

Module Modes

The module can operate in two modes: adding a new account or updating an existing one.

Mode 1: Add a New Bank Account

To add a new bank account, provide only the three required properties. After a successful submission, the API response will contain a token for the newly created bank account. You'll need to capture this token using an event callback to perform future updates.

window.bankAccountModuleConfig = {
  authToken: 'YOUR_JWT_AUTH_TOKEN',
  beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
  merchantId: 'YOUR_MERCHANT_ID'
};

Mode 2: Update an Existing Bank Account

To fetch and update an existing bank account, include the optional bankAccountToken property. This token is the unique identifier for the bank account you wish to modify.

window.bankAccountModuleConfig = {
  authToken: 'YOUR_JWT_AUTH_TOKEN',
  beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
  merchantId: 'YOUR_MERCHANT_ID',
  bankAccountToken: 'EXISTING_BANK_ACCOUNT_TOKEN' // <-- Add this to update
};

Event Handling & Callbacks

Callbacks allow you to capture the result of the user's submission and execute custom code, such as storing the new bankAccountToken. Events are passed within an events object in the main configuration.

Available Events

Event	Description	Parameters
`onComplete`	Fired when the "add" or "update" operation completes, either successfully or with an error.	`(error, response)`

The onComplete callback receives two arguments,error and response:

If the operation is successful, error will be null and response will contain the API data.
If the operation fails, error will contain the error details and response will be null.

Example: Capturing the `bankAccountToken`

The following code shows how to define and assign a callback function to retrieve the token after a new bank account is added.

<script>
  // 1. Define the callback function
  const handleBankAccountCompletion = (error, response) => {
    if (error) {
      // Handle the error
      console.error('Operation failed:', error.message);
      alert(`Error ${error.statusCode}: ${error.message}`);
      return;
    }
    
    // 2. On success, process the response
    console.log('Operation successful!', response);
    
    // 3. Extract and store the new bank account token
    const newBankAccountToken = response.data.token;
    console.log('New Bank Account Token:', newBankAccountToken);
    // e.g., saveTokenToYourDatabase(newBankAccountToken);
  };

  // 4. Assign the function to the onComplete event in the config
  window.bankAccountModuleConfig = {
    authToken: 'YOUR_JWT_AUTH_TOKEN',
    beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
    merchantId: 'YOUR_MERCHANT_ID',
    events: {
      onComplete: handleBankAccountCompletion
    }
  };
</script>

API Responses

The onComplete callback returns a standardized JSON object. When isSuccess is true, the data object contains the bank account details:

{
  "data": {
    "token": "c329023e-4a55-46fa-b5e9-039602ab2eb8",
    "isDocumentVerificationRequired": false,
    "lstErrMessagesReqFields": [],
    "code": 0,
    "desc": "",
    "msgType": 0,
    "expire_in_seconds": 0
  },
  "isSuccess": true,
  "message": "Bank account added successfully.",
  "statusCode": 0,
  "logIdentifier": "062759676e2e4814a7b9126c6dfa539f"
}

The response for an update is nearly identical, with a different success message.

{
  "data": {
    "token": "c329023e-4a55-46fa-b5e9-039602ab2eb8",
    // ... other properties
  },
  "isSuccess": true,
  "message": "Bank account updated successfully.",
  "statusCode": 0,
  "logIdentifier": "062759676e2e4814a7b9126c6dfa539g"
}

UI Customization (Optional)

You can customize the text and appearance of the UI using the optional labels and styles properties.

`labels`

Override default text content like titles, button labels, and step indicators.

Property	Type	Default Value	Description
`widgetHeaderTitle`	`string`	`'Bank Account'`	The main title at the top of the widget.
`nextButton`	`string`	`'Next'`	Text for the "Next" button in multi-step forms.
`prevButton`	`string`	`'Prev'`	Text for the "Previous" button in multi-step forms.
`submitButton`	`string`	`'Submit'`	Text for the final submission button.
`stepOptions`	`string[]`	`['Account Info', 'Bank Info']`	An array of strings to override step labels.

`styles`

Customize the look and feel by providing CSS properties or class names. Each style property accepts an object containing a style object (for inline CSS) and/or a cssClass string (for external classes).

Property	Target Element
`widgetContainer`	The main wrapper of the entire UI component.
`widgetHeader`	The header section containing the title.
`widgetHeaderTitle`	The title text.
`formContainer`	The container wrapping the form fields.
`formStepContainer`	The wrapper for the multi-step icons and labels.
`formStepLabel`	The text label for each step.
`formControlsContainer`	The container wrapping the form input controls.
`sectionListMessageContainer`	The container for informational section messages.
`sectionTitle`	The title for a section of fields (e.g., "Account Information").
`sectionListMessage`	The text of an informational note within a section.
`formControlLabel`	The label for an individual input or dropdown.
`input`	All text input fields.
`dropdown`	All dropdown/select fields.
`validationMessage`	The text that appears for validation errors.
`prevButton`	The "Previous" button.
`nextButton`	The "Next" button.

Customization Example

This example changes the header title, button text, step labels, and applies custom styles.

window.bankAccountModuleConfig = {
  // ... required properties
  
  // Custom labels
  labels: {
    widgetHeaderTitle: 'Enter Your Bank Details',
    submitButton: "Save Account",
    stepOptions: ['Step 1: Personal', 'Step 2: Banking']
  },

  // Custom styles
  styles: {
    widgetContainer: {
      style: {
        'border': '2px solid #007bff',
        'border-radius': '8px',
        'padding': '20px',
        'box-shadow': '0 4px 8px rgba(0,0,0,0.1)'
      }
    },
    widgetHeaderTitle: {
        style: {
            'color': '#007bff'
        }
    },
    input: {
      // Apply a pre-existing CSS class from your stylesheet
      cssClass: "form-control my-custom-input"
    },
    validationMessage: {
      style: {
        'color': '#dc3545',
        'font-style': 'italic'
      }
    }
  }
};