Manage funding: Implementation

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

Pre-conditions

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

Setup

Ensure that your setup is complete before working with the Manage funding 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 Manage funding Element. MFA setup is also available with the MFA Element. See MFA Element for more information.
User verification	Before the user can use a funding payment method, the user may be required to undergo BILL risk verification. Users that are flagged by the BILL risk model are set as `NOMINATED`on their bank account status to complete user verification. If user verification is required, the user is prompted to complete the verification process in the Manage funding Element. User verification is also available with the User verification Element, Add funding Element, Schedule payment Element, and Onboarding Element. Without verification, the user cannot use a funding payment method for payments.

Required credentials

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

Email notifications

BILL sends a set of email notifications for different triggers with the Manage funding Element.

Name	Trigger	Description
Verify funding method	Bank account added with manual setup	Inform the user to verify the bank account by entering the test payment amount before the user can use the bank account for payments.
Reminder to verify funding method	Bank account added with manual setup is unverified	Remind the user to verify the bank account by entering the test payment amount before the user can use the bank account for payments.
Test payment cancelled	Bank account verification cancelled. The user did not verify the bank account within 10 days.	Inform the user that the bank account is removed since the user did not verify the bank account by entering the test payment amount within 10 days.
Bank account changed	Bank account changed	Inform that user that the bank account is updated.
User verification required	User verification is required for the user to use the funding payment method	Inform the user that they must complete one-time BILL risk verification before the user can use a funding payment method for payments.
Bank account deleted	Bank account deleted	Inform the user that the bank account is deleted and can no longer be used.
Funding account unblocked	Funding payment method unblocked	Inform the user that BILL has reviewed and unblocked the funding method.

Initialization

In the <body> tag of your web page, complete the Element initialization script in your <script> tag. Set name as funding for the Manage funding 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: 'funding'
    });
    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.

`fundingListReady`

The fundingListReady event is emitted when the funding list view is rendered successfully.

// Empty payload
{
  "name": "fundingListReady",
  "payload": {}
}

`fundingDetailsReady`

The fundingDetailsReady event is emitted when the funding account details view is rendered successfully.

// Empty payload
{
  "name": "fundingDetailsReady",
  "payload": {}
}

`fundingVerifyReady`

The fundingVerifyReady event is emitted when the verify bank account view is rendered successfully.

// Empty payload
{
  "name": "fundingVerifyReady",
  "payload": {}
}

`fundingDeleteReady`

The fundingDeleteReady event is emitted when the funding account delete view is rendered successfully.

// Empty payload
{
  "name": "fundingDeleteReady",
  "payload": {}
}

`fundingSetAsDefaultReady`

The fundingSetAsDefaultReady event is emitted when the default payment method view is rendered successfully.

// Empty payload
{
  "name": "fundingSetAsDefaultReady",
  "payload": {}
}

`fundingAddReady`

The fundingAddReady event is emitted when the Element is rendered successfully.

// Empty payload
{
  "name": "fundingAddReady",
  "payload": {}
}

`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;
}

`userVerificationReady`

The userVerificationReady event is emitted when the Element is rendered successfully. If user verification is required, the returned required value is true.

{
  required: boolean;
}

Success events

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

`fundingVerifySuccess`

The fundingVerifySuccess event is emitted when the user completes the verify bank account flow by entering the test payment amount. The flow results in either verification success or failure.

If the user is successful in verifying the bank account with the test payment amount, the returned depositVerificationSuccess value is true. The user is not successful, the returned depositVerificationSuccess value is false. In addition, you receive bankData with information about the bank account.

{
    "bankData": {
      "defaultPayables": false,
      "archived": false,
      "status": "VERIFIED",
      "accountNumber": "*******0044",
      "depositVerificationSuccess": true,
      "id": "bac02XBRQNMUVWNAt71e",
      "nameOnAccount": "Stage1new"
    }

`fundingDeleteSuccess`

The fundingDeleteSuccess event is emitted when a funding account is deleted successfully. You receive bankData or cardData with information about the deleted funding account.

fundingDeleteSuccess: BankDeleteSuccess | CardDeleteSuccess;

fundingDeleteSuccess is a union type that returns either BankDeleteSuccess or CardDeleteSuccess.

interface BankDeleteSuccess{
  bankData: {
    status: string;
    accountNumber: string;
    userVerificationRequired: boolean;
    id: string;
    nameOnAccount: string;
    defaultBilling?: boolean;
  }
} | interface CardDeleteSuccess{
  cardData: {
    status: string;
    last4: string;
    userVerificationRequired: boolean;
    id: string;
    nameOnAccount: string;
    defaultBilling?: string;
  }
}

`fundingSetAsDefaultSuccess`

The fundingSetAsDefaultSuccess event is emitted when the user successfully sets a new default payment method. In addition, you receive bankData with information about the bank account.

{
bankData: {
defaultPayables: boolean;
archived: boolean;
status: AccountStatus;
accountNumber: string;
}

`fundingAddSuccess`

The fundingAddSuccess event is emitted when the user successfully adds a new funding payment method. You receive bankData or cardData with information about the added funding account.

❗️
If the user adds multiple accounts simultaneously via Plaid, the returned values are formatted as comma-separated strings, not arrays. For example, "id": "bac02OBEIEBXNSFHt71i,bac02BRBIUIJBEBXt71j"

{
  bankData: {
    status: string;
    accountNumber: string;
    userVerificationRequired: boolean;
    id: string;
    nameOnAccount: string;
    defaultBilling?: boolean;
  }
} | {
  cardData: {
    status: string;
    last4: string;
    userVerificationRequired: boolean;
    id: string;
    nameOnAccount: string;
    defaultBilling?: string;
  }
}

`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;
}

`userVerificationSuccess`

The userVerificationSuccess event is emitted when the user completes the verification flow with the User verification Element. When this event is fired, this is a signal for the event listener that the user has completed the flow in the Element, and it is safe to route the user.

Verification result	Description
`Approved`	User verification is complete and the user is approved
`In_Review`	User verification is in review

{
  userId: string;
  verificationResult: 'Approved' | 'In_Review' | 'Not_Applicable';
}

Error handling

`error`

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

Event	Description
`WIDGET_REQUIRES_KYCB`	The organization KYC/KYB is not complete
`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.