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 steps for a basic implementation. This will render the 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 component will be rendered inside this tag.

<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.

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

📘
Dynamic Script Loading
If you encounter issues, you can load the script dynamically by creating a <script> element in JavaScript and appending it to your document.
let eWalletUiScript = document.createElement('script');
// eWalletUI.bundle.js src File path
eWalletUiScript.src = 'eWalletUI.bundle.js';
eWalletUiScript.defer = true;
// Container you want to append the script to.
let container = document.body;
container.appendChild(eWalletUiScript);

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.

When combined, a minimal HTML page will look like this:

<!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

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

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

Component 1: Beneficiary Form Page

This is the first page a user typically interacts with. 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. Changes to `'Update Beneficiary'` if the user exists.
`legend`	`string`	`'Please Fill...'`	The instructional text below the main title.
`pleaseChooseAnAddress`	`string`	`'Please choose...'`	Text shown above a list of suggested addresses.
`enteredAddress`	`string`	`'Entered Address'`	The title for the address the user originally typed.
`suggestedAddress`	`string`	`'Suggested Address'`	The title for the list of suggested, corrected addresses.
`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.
`widgetHeader`	The header section containing the title.
`widgetHeaderTitle`	The main title text.
`fieldset`	The wrapper around the main form content.
`legend`	The instructional text below the title.
`formContainer`	The container for all form fields.
`formControlsContainer`	The container for a group of form controls.
`fieldSectionTitle`	Section titles like "Personal Details".
`formControlLabel`	The label for an individual input field.
`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 event will fire with a response payload containing the crucial beneficiaryToken.

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

Component 2: Payment Methods Page

After a beneficiary is created or updated, they see this page to manage their payment methods. Customize it by passing a paymentMethodsPage object in your main config.

`labels` for Payment Methods

Use the labels object to override default text content.

Property	Type	Description
`widgetHeaderTitle`	`string`	The main title of the page (e.g., `'Payment Methods'`).
`backButton`	`string`	Text for the button to return to the payment methods list from a form.
`newBankAccountButton`	`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`	Customizes accordion titles (`bankAccountLabel`, `wireProfileLabel`, `creditCardLabel`).
`noRecordsFound`	`string`	The message displayed when no payment methods exist.
`sorryYouAreNotAllowedToAddAPaymentMethod`	`string`	Message shown if adding payment methods is disabled.

`styles` for Payment Methods

Use the styles object to 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 page.
`tilesContainer`	The container for a single payment method card.
`tilesBody`	The main body of a payment method card.
`tilesContentWrapper`	The wrapper for the details within a card.
`accountTypeRibbon`	The "Business" or "Personal" account ribbon.
`accountTypeWrapper`	The container for the ribbon text.
`bankNameValue`	The bank name text.
`endingWithLabel`	The "Ending With:" text.
`accountNumberValue`	The masked account/card number text.
`beneficiaryNameValue`	The beneficiary name text.
`currencyValue`	The currency text.
`editButtonContainer`	The container for the "Edit" button.
`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 properties for each module, please see their individual documentation pages.

Full Example

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

1. Define All Callback Functions

It's best practice to define your callback functions first so they are available when the configuration is read.

<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>

2. Full HTML and Configuration

The final HTML page integrates the container, callback definitions, the full configuration object, and the bundle script.

<!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>