Vendors: Implementation

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

Preconditions

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

Setup

Ensure that your setup is complete before working with the Vendors 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.

Required credentials

The Vendors 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 Vendors Element.

Name	Trigger	Description
Vendor invitation	A vendor was invited to join the BILL Network to receive ePayments	Inform the vendor that they have been invited to create a free BILL account. The account enables them to manage their contact and payment information.
Reminder to accept vendor invitation	The invited vendor did not act on the invitation to join the BILL Network to receive ePayments	Remind the vendor to accept the Network invitation. The email highlights the benefits of getting paid faster and being able to manage their contact and payment information.
Complete connection to the BILL Network	The invited vendor started the connection setup process, but did not complete all the required steps	Follow-up with the vendor and prompt them to complete the final steps. The steps include vendor email address verification, confirm the connection request from the inviting organization, and vendor bank account setup.
Vendor invitation accepted	The invited vendor successfully accepted the invitation to receive ePayments	Inform the payer organization that sent the invitation. The email confirms that the vendor is now set up to receive ePayments.
Vendor bank account added	The vendor successfully added their bank account information in their BILL account to receive ePayments	Inform the payer organization that the vendor has added their bank account information and can now receive ePayments.
Confirmation of payment information	The payer manually added the vendor bank information	Inform the vendor that the payer manually added their bank information and prompts them to confirm its accuracy.

Initialization

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

`vendorListReady`

The VendorListReady event is emitted when the vendor list is rendered successfully.

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

`vendorDetailsReady`

The vendorDetailsReady event is emitted when the vendor details view is rendered successfully.

{
  "name": "vendorDetailsReady",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorEditReady`

The vendorEditReady event is emitted when the vendor edit view is rendered successfully.

{
  "name": "vendorEditReady",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorSetupReady`

The vendorSetupReady event is emitted when the Element is initialized successfully.

{
  "name": "vendorSetupReady",
  "payload": {
    "convert": false,
    "internationalEnabled": true
  }
}

`vendorArchiveReady`

The vendorArchiveReady event is emitted when the vendor archive modal in the Element is initialized successfully.

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

`vendorSwitchPaymentMethodReady`

The vendorSwitchPaymentMethodReady event is emitted when the switch payment method modal in the Element is initialized successfully.

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

`vendorNetworkReminderReady`

The vendorNetworkReminderReady event is emitted when the network reminder modal in the Element is initialized successfully.

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

`vendorInviteToNetworkReady`

The vendorInviteToNetworkReady event is emitted when the request to connect modal in the Element is initialized successfully.

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

Selected events

The Selected events fire when the user clicks a link or an interactive element. See Initialize the Element experience for navigation details and your response options.

`vendorListVendorSetupSelected`

The vendorListVendorSetupSelected event is emitted when the user clicks Add Vendor on the Vendor List page.

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

`vendorListPayVendorSelected`

The vendorListPayVendorSelected event is emitted when the user clicks Pay on the Vendor List page.

{
  "name": "vendorListPayVendorSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorListVendorDetailsSelected`

The vendorListVendorDetailsSelected event is emitted when the user clicks Vendor Name on the Vendor List page.

{
  "name": "vendorListVendorDetailsSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorDetailsPayVendorSelected`

The vendorDetailsPayVendorSelected event is emitted when the user clicks Schedule Payment on the Vendor Details page.

{
  "name": "vendorDetailsPayVendorSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorDetailsPaymentDetailsSelected`

The vendorDetailsPaymentDetailsSelected event is emitted when the user clicks Payment Details on the Vendor Details page.

{
  "name": "vendorDetailsPaymentDetailsSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    },
    "paymentData": {
      "paymentId": "stp02XRPVHUREQI1w24a"
    }
  }
}

`vendorDetailsPaymentListSelected`

The vendorDetailsPaymentListSelected event is emitted when the user clicks View all Payments on the Vendor Details page.

{
  "name": "vendorDetailsPaymentListSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902WYEBOHSMWB1kbun"
    }
  }
}

`vendorEditSelected`

The vendorEditSelected event is emitted when the user clicks Edit Vendor on the Vendor Details page. The Element handles the subsequent navigation.

{
  "name": "vendorEditSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorDisconnectSelected`

The vendorDisconnectSelected event is emitted when the user clicks Disconnect from vendor on the Vendor Details page for a connected vendor. The Element handles the subsequent navigation.

NOTE: A vendor cannot be disconnected if there are scheduled or processing payments.

{
  "name": "vendorDisconnectSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorCancelNetworkInviteSelected`

The vendorCancelNetworkInviteSelected event is emitted when the user clicks Cancel connection request on the Vendor Details page for a pending connection vendor. The Element handles the subsequent navigation.

{
  "name": "vendorCancelNetworkInviteSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorArchiveSelected`

The vendorArchiveSelected event is emitted when the user clicks archive to archive a vendor on the Vendor Details page. The Element handles the subsequent navigation.

{
  "name": "vendorArchiveSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorRestoreSelected`

The vendorRestoreSelected event is emitted when the user clicks restore for an archived vendor on the Vendor Details page or vendor list. The Element handles the subsequent navigation.

NOTE: This is available only for vendors in an archived state.

{
  "name": "vendorRestoreSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorSwitchPaymentMethodSelected`

The vendorSwitchPaymentMethodSelected event is emitted when the user clicks Switch to electronic payments on the Vendor Details page. The Element handles the subsequent navigation.

{
  "name": "vendorSwitchPaymentMethodSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

`vendorNetworkReminderSelected`

The vendorNetworkReminderSelected event is emitted when the user clicks Send reminder on the Vendor Details page for a network invitation. The Element handles the subsequent navigation.

{
  "name": "vendorNetworkReminderSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }

`vendorInviteToNetworkSelected`

The vendorInviteToNetworkSelected event is emitted when the user clicks Request to connect on the Vendor Details page. The Element handles the subsequent navigation.

{
  "name": "vendorInviteToNetworkSelected",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
  }
}

Success events

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

`vendorEditSuccess`

The vendorEditSuccess event is emitted when the user successfully updates a vendor.

{
  "name": "vendorEditSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
    }
    "vendorModified": true
  }
}

`vendorSetupSuccess`

The vendorSetupSuccess event is emitted when a vendor is added or updated. In the payload, vendorSetupResult provides more information about the vendor connection in the BILL Network.

Value	Description
`NETWORK_INVITED`	Connection request sent to vendor in the BILL Network
`NOT_NETWORK_INVITED`	No connection request sent when setting up the vendor
`NETWORK_CONNECTION_PENDING`	Connection request sent to the vendor is in pending status
`NETWORK_AUTO_CONNECTION`	Automatically connected with vendor in the BILL Network
`RPPS_CONNECTED`	Connected with a Verified National Vendor in the BILL Network
`PORTAL_INVITED`	Connection request sent to an international vendor in a country where the BILL Network is not supported. BILL sends the vendor an invitation to a web portal where the vendor can provide their payment information.

{
  "name": "vendorSetupSuccess",
  "payload": {
    "vendorData": {
      "id": "00902REAJVUPTWJ1qnwk",
      "name": "kjhyuj",
      "accountNumber": "7787767",
      "address": {
        "line1": "8894 Knight Ave",
        "line2": "",
        "city": "Des Plaines",
        "stateOrProvince": "IL",
        "zipOrPostalCode": "60016",
        "country": "US"
      },
      "paymentInformation": {
        "payByType": "CHECK"
      }
    },
    "vendorConvert": false,
    "vendorSetupResult": "NOT_NETWORK_INVITED",
    "vendorModified": false,
    "internationalVendor": false
  }
}

`vendorArchiveDeclinedSuccess`

The vendorArchiveDeclinedSuccess event is emitted when the user declines to archive a vendor.

{
  "name": "vendorArchiveDeclinedSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
	"archived": false
    }
  }
}

`vendorArchiveSuccess`

The vendorArchiveSuccess event is emitted when the user archives a vendor successfully.

{
  "name": "vendorArchiveDeclinedSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
	"archived": true
    }
  }
}

`vendorRestoreSuccess`

The vendorRestoreSuccess event is emitted when the user restores a vendor successfully.

{
  "name": "vendorRestoreSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve"
	"archived": false
    }
  }
}

`vendorSwitchPaymentMethodSuccess`

The vendorSwitchPaymentMethodSuccess event is emitted when the user completes the flow to switch a vendor to electronic payments.

{
  "name": "vendorSwitchPaymentMethodSuccess",
"payload": {
    "vendorData": {
      "vendorId": "00902CROTAQOCHJ1kbve",
      "payByType": "Check"
    },
    "vendorModified": false,
    "vendorSetupResult": "NOT_NETWORK_INVITED"
  }
}

`vendorNetworkReminderSuccess`

The vendorNetworkReminderSuccess event is emitted when the user completes the flow to send a network connection reminder.

{
  "name": "vendorNetworkReminderSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902OKFOMQPVWK1kbup",
         }
  }
}

`vendorInviteToNetworkSuccess`

The vendorInviteToNetworkSuccess event is emitted when the user completes the flow to invite a vendor to the BILL network.

{
  "name": "vendorInviteToNetworkSuccess",
  "payload": {
    "vendorData": {
      "vendorId": "00902OKFOMQPVWK1kbup",
      "networkStatus": "NOT_CONNECTED"
    },
    "vendorModified": false
  }
}

Error handling

`error`

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

Event value	Description
`WIDGET_INPUT_INELIGIBLE`	Invalid input. This event occurs in 2 scenarios. The vendor payment method is already set as ACH, and the vendor is connected in the BILL Network. The vendor has an pending invitation to join the BILL Network.
`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.