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
orGET /v3/vendors/{vendorId}
).
Value | Description |
---|---|
NOT_CONNECTED | Not connected with a vendor in the BILL network |
PENDING | Invitation is sent to the vendor in the BILL network |
CONNECTED | The vendor in the BILL network has accepted the invitation. You are connected with the vendor. |
CONNECTED_RPPS | Connected with a verified national vendor |
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.
Updated 3 months ago