Connecting with a BILL network vendor

Search for and send an invitation to connect with a vendor in the BILL network. In this example workflow, your BILL organization is a customer that is sending an invitation to the vendor Happy Music Supplies in the BILL network.

❗️

IMPORTANT

Complete the BILL network sandbox setup before proceeding with searching for and connecting with a BILL network vendor.

Creating a vendor

Create a vendor with the BILL web app or with POST /v3/vendors with the minimum required information. This is how you want to identify the vendor in your BILL organization.

In this cURL example, a vendor called Happy is created. This is how the vendor appears in your BILL organization.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/vendors' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "name": "Happy", 
  "accountType": "BUSINESS",
  "email": "[email protected]", 
  "phone": "9876543210",
  "address": {
    "line1": "123 Main Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "billCurrency": "USD"
}'

Network connection status

You can get the network connection status of a vendor when you create a vendor (POST/v3/vendors) or get vendor details (GET /v3/vendors or GET /v3/vendors/{vendorId}).

In the API response, networkStatus is available for providing information about the BILL network connection status. This field can have one of four status values.

📘

NOTE

You can get the network connection status of a vendor when you create a vendor (POST/v3/vendors) or get vendor details (GET /v3/vendors or GET /v3/vendors/{vendorId}).

In the next set of steps, after you connect with a vendor called Happy Music Supplies in the BILL network, BILL updates the created vendor called Happy with the network vendor payment information.

Searching for the vendor

In this cURL example, a search request is sent for a vendor called Happy Music Supplies in the BILL network.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/network?name=Happy%20Music%20Supplies&scope=BILL' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

In the response, the search result displays the Payment Network ID (PNI id) and address details of the vendor. Use the PNI id to send an invitation to the vendor in the BILL network.

Sending an invitation

In this cURL example, an invitation is sent to connect with the vendor in the BILL network. In the request, vendorId is set as the BILL-generated ID of the vendor called Happy you created in your BILL organization. Retrieve the vendorId with GET /v3/vendors.

In addition, networkId is set as the PNI id of the selected vendor from the network search results.

📘

NOTE

There are additional required fields for sending a connection request to a verified national vendor. See Send vendor invitation in the API reference for more information. The Pay a verified national vendor recipe also provides an example flow.

Since verified national vendors are verified by BILL, there is no additional step for accepting an invitation before paying these vendors.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/network/invitation/vendor/{vendorId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "networkId": "{PNI_id}",
  "networkType": "BILL"
}'

When the invited vendor accepts the invitation, BILL enables payments between the connections. In this connection workflow, your organization is the customer and Happy Music Supplies is the vendor.