Vendor setup: Implementation

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

Pre-conditions

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

Setup

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

Required credentials

The Vendor setup 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 Vendor setup 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 vendorSetupApp for the Vendor setup Element. If a vendorId input is available in the Vendor setup Element, the user is directed to the vendor flow in which they can update the vendor record. 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: 'vendorSetupApp',
      inputs: {
        vendorId: "{vendor_id}"
      }
    });
    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.

`vendorSetupReady`

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

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

Success events

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

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

Error handling

`error`

The error event is emitted when an error occurs during the use of the Vendor setup 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 the following scenarios: For US vendors The vendor's payment method is set to ACH The vendor is connected to the BILL Network The vendor has a pending invitation to join the BILL Network For International vendors The vendor is located in an unsupported country The vendor has an associated bill object
`WIDGET_INTERNAL_ERROR`	HTTP 500 internal server error

Event value

Description

WIDGET_INPUT_INELIGIBLE

Invalid input.
This event occurs in the following scenarios:

For US vendors
- The vendor's payment method is set to ACH
- The vendor is connected to the BILL Network
- The vendor has a pending invitation to join the BILL Network
For International vendors
- The vendor is located in an unsupported country
- The vendor has an associated bill object

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.