Skip to main content

Embeddables

Widgets allow partners to render First Dollar components within their own application.

Overview​

We have the following widgets available:

  • Deposit (Contributions)
    • Initiate an ACH from a linked bank account into a Health Savings Account
    • Launch a letter for requesting contributions from an employer
  • Reimbursement (Withdrawals):
    • Initiate an ACH from a Health Savings Account into a linked bank account

Prerequisites​

SSO Integration​

In order to use any First Dollar widgets, a partner must already have an SSO integration with us. See the Single Sign-On guide for more information.

Content Security Policy Update​

First Dollar widgets are served within an iframe. Your site will need to set the First Dollar domain (https://my.firstdollar.com) as an allowed frame-src in your Content Security Policy directives.

Include a Script Tag​

First Dollar will provide a URL of an externally accessible JS file for a given widget. Partners add a script tag to their HTML for each widget.

When loaded, this script will expose an object globally on the window, ex:

window.fdDepositWidget / window.fdReimbursementWidget

Initialize the Widget​

const initializeWidget = async () => {
  const { status } = await window.fdDepositWidget.initialize({
    auth: () => Promise.resolve(`${SAML}`),
    htmlTarget: 'test',
  });
  if (status === 'SUCCESS') {
   /**
    * Widget initialization was successful!
    * If showOnInitialize (see below) is not true,
    * you'll likely want to call show() here:
    */
    window.fdDepositWidget.show();
  } else if (status === 'ERROR') {
    console.error('error'!)
  }
};

Call the initialize method on the widget object This method requires an object as an argument with the following properties:

auth (Function) - required

A callback that returns a Promise that resolves with the signed SAML XML

htmlTarget (String) - required

A string that is the id of the HTML element to render the widget into

  • The string must be just the string without the id selector (e.g. 'widget-container' instead of '#widget-container')

options (Object) optional

  • language (String)
    • Optional language option to pass to the initialization method so the widget will render with the correct language
  • showOnInitialize (Boolean)
    • Optional boolean to pass to the initialization method. If true, the widget will render as soon as the initialization is successful. Otherwise, show will need to be called manually
  • base64Encode (Boolean)
    • Optional boolean to pass to the initialization method. If true, this signifies that the saml passed to the auth method is encoded

If the initialization call is successful, it will return a status object of: { status: 'SUCCESS' } If the initialization call fails, it will return a status object of: { status: 'ERROR', error: 'Error initializing widget' }

Render the Widget​

window.fdDepositWidget.show();

If the initialization call returned a success status, call the show method on the widget object.

This method will render the widget component into the container specified by the htmlTarget property.

This method accepts no arguments.

If the call to show is successful, it will return a status object of:

{
  status: 'SUCCESS';
}

If the call fails, it will return a status object of:

{ status: 'ERROR', errorMessage: 'Target element could not be found' OR 'No token provided' }

The call will fail if the token is not provided or the target element cannot be found.

Unmount the Widget​

window.fdDepositWidget.close();

Call the close method on the widget object.

This method will unmount the widget component from the DOM.

Call this whenever a user takes an action that should close the widget.

This method accepts no arguments.

If the call to hide is successful, it will return a status object of:

{
  status: 'SUCCESS';
}

If the call fails, it will return a status object of:

{ status: 'ERROR', errorMessage: 'Target element could not be found' }

The call will fail if the target element cannot be found.