MFA: Implementation

In this section, we list the implementation details for the MFA Element. This includes pre-conditions, custom events, and error handling.

Pre-conditions

BILL has a set of pre-conditions for working with the MFA Element.

Setup

Ensure that your setup is complete before working with the MFA Element.

Setup	Description
Set up organizations and users	You must set up your organizations and users with the BILL v3 API. See Organizations for BILL partners and Users for BILL partners for more information.
Onboard the organization	The organization onboarding must be complete with the Onboarding Element.
MFA	MFA is required for the user to schedule a payment. When the signed-in user session is not MFA-trusted, the user is prompted to complete MFA and create a trusted session in the MFA Element.

Required credentials

The Add funding Element requires a set of credentials.

Credential	Description
`devKey`	Developer key generated with your BILL developer account
`sessionId`	API session ID generated with `POST /v3/partner/login`. See API partner login in the API reference to learn about signing in and generating a partner-level `sessionId`.
`userId`	BILL-generated ID of the signed-in user. The value begins with `006`.
`orgId`	Organization ID associated with the signed-in user

Initialization

In the <body> tag of your web page, complete the Element initialization script in your <script> tag. Set name as mfa for the MFA Element. See Initialize the Element experience for more information.

    // Initialize & mount the Element on the web page
    const bootloader = init(billBootConfig);
    bootloader.register({
      id: 'element1',
      name: 'mfa'
    });
    await bootloader.render('element1', '#your-div');

Events

BILL provides a set of custom Element properties that you can set. You can use window.addEventListener or an onEvent callback for listening to and handling events.

Ready events

The Ready events fire when the Element renders successfully.

`mfaReady`

The mfaReady event is emitted when the Element is rendered successfully. When the signed-in user session is MFA-trusted, the returned setup value is true. When the session is not MFA-trusted, the returned required value is true.

{
  setup: boolean;
  required: boolean;
}

Success events

The Success events fire when the user-initiated action completes successfully.

`mfaSuccess`

The mfaSuccess event is emitted when the MFA setup or MFA challenge is submitted successfully. Note that rememberMeId is available in the payload only when MFA rememberMe is set as true for the user.

{
  setup: boolean;
  required: boolean;
  rememberMe?: boolean;
  rememberMeId: string;
  deviceId: string;
}

Maintain user MFA status

When the user completes their one-time MFA setup with the MFA Element and sets the Remember this device for 180 days option, the emitted mfaSuccess event payload has the generated rememberMeId and deviceId values.

There are two ways in which you can maintain the MFA status for the user.

With the MFA Element

At user sign-in, complete the required set of steps.

Generate a new sessionId with POST /v3/partner/login-as-user. In your request, set the userId and organizationId values. The API session is not MFA-trusted.
Check the MFA status for the API session with GET /v3/login/session. In the response, mfaStatus is set as CHALLENGE.
Load the MFA Element. At this point, BILL completes the MFA step-up operation for the API session with POST /v3/mfa/step-up. The API session is now MFA-trusted.

When you check the MFA status again for the API session with GET /v3/login/session, mfaStatus in the response is set as COMPLETE.

With `rememberMeId` and `device`

At user sign-in, generate a new sessionId with POST /v3/partner/login-as-user. In your API request, set the userId, organizationId, rememberMeId and device values. The generated API session is MFA-trusted.

Error handling

`error`

The error event is emitted when an error occurs during the use of the MFA Element. For this Element, there is 1 possible error event. In all other error cases, error message banners are displayed in the Element.

Event	Description
`WIDGET_INTERNAL_ERROR`	HTTP 500 internal server error

BILL follows a pattern for all errors.

Pattern
BILL emits a standardized and singular `error` event for all Elements. All the error payloads follow a consistent and predictable shape.
BILL emits error events only when the user cannot recover from an error in the BILL experience. This should occur only when the requirements for launching an Element are not met. Errors are emitted immediately for you to respond and close the BILL experience.
If your application does not handle the BILL error events, BILL provides a fallback experience for the user. This experience does not have any interactive element that your application is required to respond to. When the user lands on the fallback experience, BILL recommends that you either navigate the user correctly or add interactive elements to enable the user to close the Element.

Pattern

BILL emits a standardized and singular error event for all Elements. All the error payloads follow a consistent and predictable shape.

BILL emits error events only when the user cannot recover from an error in the BILL experience. This should occur only when the requirements for launching an Element are not met. Errors are emitted immediately for you to respond and close the BILL experience.

If your application does not handle the BILL error events, BILL provides a fallback experience for the user. This experience does not have any interactive element that your application is required to respond to.

When the user lands on the fallback experience, BILL recommends that you either navigate the user correctly or add interactive elements to enable the user to close the Element.