Beneficiary Onboarding Module

This guide provides a comprehensive overview of how to integrate and configure the Beneficiary Onboarding Module, which allows your users to create a profile and manage their payment methods (bank accounts, wire profiles, and credit cards) all in one place.

Getting Started

Follow these three simple steps for a basic implementation. This will render the eWallet UI, starting with the beneficiary creation/update form.

Step 1: Add the HTML Container

First, place an empty div element with the ID eWalletUI in your HTML file. The entire eWallet component will be rendered inside this tag, as shown below:

<div id="eWalletUI"></div>

Step 2: Install the Script

Next, include the eWalletUI.bundle.js script in your HTML page. We recommend using the defer attribute, as shown in the following script tag:

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

📘
Note
If you encounter issues, you can load the script dynamically by creating a <script> element in JavaScript and appending it to your document.

Step 3: Configure the Module

Finally, you must define the global configuration object window.eWalletConfig in a <script> tag placed before the bundle script. The minimal configuration requires an auth token, merchant ID, and a username, as detailed in the snippet below:

<script>
  window.eWalletConfig = {
    authToken: 'YOUR_JWT_AUTH_TOKEN',
    merchantId: 'YOUR_MERCHANT_ID',
    username: 'a_unique_user_name',
    lang: "EN" // Optional
  };
</script>

When combined, a minimal HTML page will look like the sample code below:

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

    <script>
      window.eWalletConfig = {
        authToken: 'YOUR_JWT_AUTH_TOKEN',
        merchantId: 'YOUR_MERCHANT_ID',
        username: 'a_unique_user_name'
      };
    </script>

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

Core Configuration (`eWalletConfig`)

The window.eWalletConfig object is the single source of truth for the entire bundle. It controls authentication, user identification, and the customization of its child components.

Required Properties

The following properties are mandatory for the module to function:

Property	Type	Description
`authToken`	`string`	A JSON Web Token (JWT) used for authenticating all API requests.
`merchantId`	`string`	The unique identifier for your merchant account.
`username`	`string`	Crucial for logic. If the username exists, the UI will load the user's data in "update" mode. If it doesn't exist, the UI will start in "create new beneficiary" mode.

Optional Top-Level Properties

You can include these optional objects in the main eWalletConfig to customize the different pages within the bundle.

Property	Type	Description
`lang`	`string`	Sets the display language. Defaults to `'EN'`.
`beneficiaryFormPage`	`object`	An object containing customizations for the "Create/Update Beneficiary" page. Detailed in the next section.
`paymentMethodsPage`	`object`	An object containing customizations for the "Payment Methods" page. Detailed below.

Component 1: Beneficiary Form Page

This is the first page a user typically interacts with to create or update their personal and address information. You can customize it by passing a beneficiaryFormPage object in your main config.

`labels` for Beneficiary Form

Property	Type	Default Value	Description
`widgetHeaderTitle`	`string`	`'Create Beneficiary'`	The main title at the top of the widget. Changes to `'Update Beneficiary'` if the user exists.
`legend`	`string`	`'Please Fill...'`	The instructional text below the main title.
`createButton`	`string`	`'Create Beneficiary'`	Text for the "Create" button.
`updateButton`	`string`	`'Update Beneficiary'`	Text for the "Update" button.

`styles` for Beneficiary Form

Property	Target Element
`widgetContainer`	The main wrapper of the entire page.
`widgetHeaderTitle`	The main title text.
`fieldSectionTitle`	Section titles like "Personal Details".
`input`	All text input fields.
`dropdown`	All dropdown/select fields.
`validationMessage`	The red text for validation errors.

`events` for Beneficiary Form

Event	Description
`onBeneficiaryCreated`	Fired after a new beneficiary is successfully created. Returns the API response.
`onBeneficiaryUpdated`	Fired after an existing beneficiary is successfully updated. Returns the API response.

Beneficiary API Response

After a successful creation or update, the onBeneficiaryCreated or onBeneficiaryUpdated event will fire with a response payload. Your callback function should capture the beneficiaryToken from this response, as shown in the JSON structure below:

{
    "data": {
        "beneficiaryToken": "930c928d-48e6-4356-a965-8a278e378b09"
    },
    "isSuccess": true,
    "message": "Beneficiary updated successfully",
    "statusCode": "NO_ERROR",
    "logIdentifier": "6280767b86fd4ebebe5531a6add544a7"
}

Example: Configuring the Beneficiary Form

Here's an example of how you would structure the beneficiaryFormPage object within the main eWalletConfig:

window.eWalletConfig = {
    // ...required properties
    beneficiaryFormPage: {
        labels: {
            widgetHeaderTitle: 'Your Profile Information'
        },
        styles: {
            validationMessage: {
                style: {
                    color: 'red',
                    'font-weight': 'bold'
                }
            }
        },
        events: {
            onBeneficiaryCreated: handleBeneficiaryResponse, // Assumes this function is defined elsewhere
            onBeneficiaryUpdated: handleBeneficiaryResponse
        }
    }
};

Component 2: Payment Methods Page

After a beneficiary is created, they are typically shown this page to manage their payment methods. You can customize it by passing a paymentMethodsPage object in your main config.

`labels` for Payment Methods

Property	Type	Description
`widgetHeaderTitle`	`string`	The main title of the page (e.g., `'Payment Methods'`).
`newBankAcccountButton`	`string`	Text for the button to add a new bank account.
`newWireProfileButton`	`string`	Text for the button to add a new wire profile.
`newCreditCardButton`	`string`	Text for the button to add a new credit card.
`accordionLabels`	`object`	An object to customize the accordion titles (`bankAccountLabel`, `wireProfileLabel`, `creditCardLabel`).
`noRecordsFound`	`string`	The message displayed when no payment methods exist.

`styles` for Payment Methods

Property	Target Element
`widgetContainer`	The main wrapper of the page.
`tilesContainer`	The container for a single payment method card.
`accountTypeRibbon`	The "Business" or "Personal" account ribbon.
`editButton`	The "Edit" button on a payment method card.
`noRecordsFound`	The style for the "No records found" text.

Nested Module Configuration

To configure the pop-up forms for adding/editing bank accounts, wires, or credit cards, you pass their respective configuration objects inside the paymentMethodsPage object. These nested objects accept the same properties as their standalone counterparts.

bankAccountModuleConfig
wireProfileModuleConfig
creditCardModuleConfig

For a full list of available properties for each module, please see their individual documentation pages.

Example: Configuring the Payment Methods Page

The following code shows how to structure the paymentMethodsPage object, including a nested configuration for the Bank Account module:

window.eWalletConfig = {
    // ...required properties
    paymentMethodsPage: {
        labels: {
            widgetHeaderTitle: 'Manage Your Payout Methods',
            newBankAcccountButton: 'Add New Bank Account'
        },
        styles: {
            editButton: {
                cssClass: 'my-custom-edit-button-class'
            }
        },
        // Nested config for the Bank Account module form
        bankAccountModuleConfig: {
            labels: {
                widgetHeaderTitle: 'Enter Your Bank Details'
            },
            events: {
                onComplete: handleBankAccountResponse // Assumes this function is defined elsewhere
            }
        },
        // You can also add wireProfileModuleConfig and creditCardModuleConfig here
    }
};

Full Example

This final example demonstrates a complete and functional implementation, including configuration for both pages and definitions for all callback functions.

Define All Callback Functions

First, it's best practice to define all your callback functions in a single script block so they are available when the configuration is read. The example below shows how to set this up:

<script>
    // Callback for when beneficiary is created OR updated
    const handleBeneficiaryResponse = (err, response) => {
        if (err) return alert(err.message);
        console.log('Beneficiary operation successful:', response);
        // You might want to store the beneficiaryToken from response.data.beneficiaryToken
    };

    // Callback for when a Bank Account operation is complete
    const handleBankAccountResponse = (err, response) => {
        if (err) return alert(err.message);
        console.log('Bank Account operation successful:', response);
    };

    // Callback for when a Wire Profile operation is complete
    const handleWireProfileResponse = (err, response) => {
        if (err) return alert(err.message);
        console.log('Wire Profile operation successful:', response);
    };

    // Callback for when a Credit Card operation is complete
    const handleCreditCardResponse = (err, response) => {
        if (err) return alert(err.message);
        console.log('Credit Card operation successful:', response);
    };
</script>

Full HTML and Configuration

The final HTML page integrates the container, callback definitions, the full configuration object, and the bundle script. See the complete code below:

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

    <script>
        const handleBeneficiaryResponse = (err, res) => console.log('Beneficiary:', { err, res });
        const handleBankAccountResponse = (err, res) => console.log('Bank:', { err, res });
        const handleWireProfileResponse = (err, res) => console.log('Wire:', { err, res });
        const handleCreditCardResponse = (err, res) => console.log('Card:', { err, res });
    </script>

    <script>
        window.eWalletConfig = {
            authToken: 'YOUR_JWT_AUTH_TOKEN',
            merchantId: 'YOUR_MERCHANT_ID',
            username: 'a_unique_user_name',
            lang: 'en',

            // --- Beneficiary Page Configuration ---
            beneficiaryFormPage: {
                labels: { widgetHeaderTitle: 'Your Profile' },
                events: {
                    onBeneficiaryCreated: handleBeneficiaryResponse,
                    onBeneficiaryUpdated: handleBeneficiaryResponse
                }
            },

            // --- Payment Methods Page Configuration ---
            paymentMethodsPage: {
                labels: { widgetHeaderTitle: 'Manage Payouts' },
                
                // Nested module configs
                bankAccountModuleConfig: {
                    events: { onComplete: handleBankAccountResponse }
                },
                wireProfileModuleConfig: {
                    events: { onComplete: handleWireProfileResponse }
                },
                creditCardModuleConfig: {
                    events: { onComplete: handleCreditCardResponse }
                }
            }
        };
    </script>

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

Getting Started

Step 1: Add the HTML Container

Step 2: Install the Script

📘Note

Step 3: Configure the Module

Core Configuration (eWalletConfig)

Required Properties

Optional Top-Level Properties

Component 1: Beneficiary Form Page

labels for Beneficiary Form

styles for Beneficiary Form

events for Beneficiary Form

Beneficiary API Response

Example: Configuring the Beneficiary Form

Component 2: Payment Methods Page

labels for Payment Methods

styles for Payment Methods

Nested Module Configuration

Example: Configuring the Payment Methods Page

Full Example

Define All Callback Functions

Full HTML and Configuration

📘
Note

Core Configuration (`eWalletConfig`)

`labels` for Beneficiary Form

`styles` for Beneficiary Form

`events` for Beneficiary Form

`labels` for Payment Methods

`styles` for Payment Methods