Domestic AP payments workflow
The BILL v3 API gives you access to the same infrastructure that powers the BILL Accounts Payable (AP), Accounts Receivable (AR), and Spend & Expense (S&E) products. In addition, you can receive real-time event notifications with webhooks.
In this recipe
In this recipe, you create AP payments to domestic vendors with the API.
AP payments is the final and most crucial step of the AP workflow. With AP payments, you settle vendor debts and unpaid vendor bills. Whether you are paying a single vendor or clearing dozens of bills at once, the BILL v3 API enables you to securely handle payments at scale.
What you'll build
In this recipe, you create an integration with the BILL API in the sandbox environment.
- Pay a domestic vendor (US vendor) that accepts check payments.
- Pay a domestic vendor that accepts ACH payments.
What you need before you begin
| Prerequisite | Description |
|---|---|
| API basics | A basic understanding of working with API endpoints. |
| Credentials | Your credentials are required for you to build with the BILL AP & AR API. If you have not set up your credentials, sign up to create your sandbox BILL account. When you sign up, you create a test BILL organization, and you generate your username, password, organization ID, and developer key. See Sandbox API sign up for detailed steps. |
| MFA setup | Your MFA setup must be complete. BILL requires MFA for creating payments with the API. MFA at BILL requires a one-time setup. When you sign up with the BILL web app to generate your credentials, you complete 2-step verification/MFA with a valid phone number. |
| Test bank account | A test bank account added in your BILL organization. You use this test bank account to create a test payment in this recipe. See Sandbox API bank account setup for detailed steps. |
Chapter 1: API login
In this chapter, you login to your BILL account with the API.
To begin, enter your API login credentials in the fields below. See the What you need before you begin section in this recipe if you have not set up your credentials.
https://gateway.stage.bill.com/connecthttps://gateway.prod.bill.com/connectComplete your API login with the required credentials. Simply click Send to get a 200 OK response.
In the response, a new sessionId is available. You use this sessionId and your devKey in all subsequent BILL API requests. A 200 OK response confirms that you are a signed-in user. The sessionId expires after 35 minutes of inactivity. At that point, you are automatically signed out, and you must sign in again with the API login endpoint and generate a new sessionId.
Note that the trusted field in the response is set as false. When the API login session is MFA-trusted, the trusted field is set as true. We enable MFA in this API session in Chapter 2.
Chapter 2: MFA
In this chapter, you step up your current API session as MFA-trusted. BILL requires MFA for creating payments with the API. In the next set of steps, you first generate an MFA challenge, validate the MFA challenge, and then step-up the API login session as MFA-trusted.
Step 1: Generate MFA challenge
Generate an MFA challenge ID with POST /v3/mfa/challenge. Click Send. You receive a 6-digit token sent to your phone number.
In the response, a challengeId is available. You use this value in Step 2.
Step 2: Validate MFA challenge
Validate the MFA challenge with POST /v3/mfa/challenge/validate. In the request, set the required fields, and then click Send.
- Set
tokenas the 6-digit token sent to your phone number. - Set
deviceandmachineNameas a test device name. For example,test-device. Device name is required in the next step.
In the response, a rememberMeId is available. You use this value in Step 3.
Step 3: Step-up API session as MFA-trusted
Step-up your API session as MFA-trusted with POST /v3/mfa/step-up. In the request, set device as the device name used in Step 2, and then click Send. Your current API session is now MFA-trusted.
In the response, trusted is set as true. Your API session is now MFA-trusted.
Chapter 3: Check vendors
In this chapter, you create a new vendor record in your BILL organization. This vendor accepts check payments.
A check vendor is a vendor that accepts check payments. To set up a check vendor record in BILL, the required vendor information is vendor mailing address and payeeName. A check payment is when BILL generates a check for the payment, and sends the check to the vendor mailing address.
In the next set of steps, you first create a check vendor record, and then you create a bill for the vendor.
Step 1: Create a check vendor
When you create a vendor with POST /v3/vendors, you add a new check vendor record to your BILL organization.
Click Body below to view an example body for the Create a vendor API request. In the request, test vendor mailing address and payeeName is set to enable check payments to the vendor. Click Send to create a check vendor.
In the response, a BILL-generated vendor id is available. In addition, payByType is set as CHECK to state the vendor payment method. You can sign in to the BILL web app to view this check vendor record in your BILL organization. In Step 2, you use the vendor id to create a bill for the check vendor.
Step 2: Create a bill
When you create a bill with POST /v3/bills, you create a new bill record for the test check vendor from Step 1.
Click Body below to view an example body for the Create a bill API request. Click Send to create a new bill for the check vendor.
In the response, a BILL-generated bill id is available. You can sign in to the BILL web app to view this bill in your BILL organization. The vendor id is displayed to show that the bill is created for the check vendor.
Chapter 4: Check payments
When you create a payment with the API, a payment record is created in your BILL organization. In the next set of steps, you first get details about your test bank account, and then you pay the check vendor for the bill you created in Chapter 3.
Step 1: Get details about your test bank account
BILL requires information about your BILL organization bank account before you can create a payment. Click Send to get the list of test bank accounts in your BILL organization with GET /v3/funding-accounts/banks.
In the request, you add a filters query parameter to get a verified test bank account ("status": "VERIFIED"). If you do not have a test bank account in your sandbox BILL account, see Sandbox API bank account setup for detailed steps.
In the response, you get the test bank account id for each test bank account in your BILL organization. In Step 2, you use the id of a verified test bank account ("status": "VERIFIED").
Step 2: Pay the check vendor
When you create a payment with POST /v3/payments, a payment record is created in your BILL organization.
Click Body below to view an example body for the Create a payment API request. In the request, vendorId and billId are set as the id values of the check vendor and bill (from Chapter 3), respectively. In addition, the funding account id is set as the id of a verified test bank account (from Step 1).
Click Send to create a new payment.
While you have added a bill to this POST /v3/payments API request, you can pay this vendor without the need for a bill. BILL auto-generates a bill when the payment API request is submitted. In addition, if processDate is not set in the request, BILL automatically sets this field as the next US business day.
You just paid a domestic check vendor. In the response, a BILL-generated payment id is available for the paid bill.
The disbursementType is set as CHECK (or VIRTUAL_CARD which is a BILL disbursement method where BILL sends the vendor a single-use, 16-digit Mastercard or Visa number).
When BILL starts processing this payment, an additional disbursementInfo object is also available in the response. Finally, singleStatus provides updates at different stages in a BILL payment lifecycle. The values are based on payment status and disbursementStatus. See Single status payment values for the complete list of status values.
You can sign in to the BILL web app to view this payment in your BILL organization. An email is also sent to your email address about the scheduled payment to the check vendor.
Chapter 5: ACH vendors
In this chapter, you create a new vendor record in your BILL organization. This vendor accepts ACH payments. An ACH vendor is a vendor that accepts electronic fund transfers directly into their bank account. To set up an ACH vendor record in BILL, the required vendor information is vendor mailing address, payeeName, and bankAccount.
When you create a vendor with POST /v3/vendors, you add a new ACH vendor record to your BILL organization.
Click Body below to view an example body for the Create a vendor API request. In the request, test vendor mailing address, payeeName, and bankAccount is set to enable ACH payments to the vendor. Click Send to create an ACH vendor.
In the response, a BILL-generated vendor id is available. In addition, payByType is set as ACH to state the vendor payment method. You can sign in to the BILL web app to view this ACH vendor record in your BILL organization. In Chapter 6, you use this vendor id to create a payment for the ACH vendor.
Chapter 6: ACH payments
When you create a payment with POST /v3/payments, a payment record is created in your BILL organization.
Click Body below to view an example body for the Create an ACH payment API request. In the request, vendorId is set as the id of the ACH vendor (from Chapter 5). In addition, the funding account id is set as the id of a verified test bank account (from Chapter 4). Finally, createBill is set as true and a billId value is not set. With this configuration, you are telling BILL to auto-generate a bill when the payment API request is submitted.
Click Send to create a new payment.
If processDate is not set in the request, BILL automatically sets this field as the next US business day.
You just paid a domestic ACH vendor. In the response, a BILL-generated payment id is available for the paid bill.
The disbursementType is set as ACH. When BILL starts processing this payment, an additional disbursementInfo object is also available in the response. Finally, singleStatus provides updates at different stages in a BILL payment lifecycle. The values are based on payment status and disbursementStatus. See Single status payment values for the complete list of status values.
You can sign in to the BILL web app to view this payment in your BILL organization. An email is also sent to your email address about the scheduled payment to the ACH vendor.
Chapter 7: Bulk payments
In this chapter, you experience the power of bulk operations with the BILL v3 API. To this point, you have paid a vendor by check and with ACH. In both cases, you paid the vendor for one bill. When your business scales, clicking Pay one by one is time consuming.
In the next set of steps, you first create multiple bills with one API request, and then you pay multiple bills with one API request.
Step 1: Create multiple bills
When you create multiple bills with POST /v3/bills/bulk, you add new bill records to your BILL organization for the ACH vendor (from Chapter 5). You can create multiple bills for one vendor or for multiple vendors with one POST /v3/bills/bulk API request.
Click Body below to view an example body for the Create multiple bills API request. Click Send to create two bills with one API request.
In the response, a BILL-generated bill id is available for each bill created. You can sign in to the BILL web app to view these bills in your BILL organization.
Step 2: Create a bulk payment
When you create a bulk payment with POST /v3/payments/bulk, a payment record is created in your BILL organization for each bill being paid. You can pay up to 50 bills with one POST /v3/payments/bulk request. See Create a bulk payment to learn about the complete set of rules.
Click Body below to view an example body for the Create a bulk payment API request. In the request, the billId values are set as the id values of the bills created in Step 1. In addition, the funding account id is set as the id of a verified test bank account.
Click Send to create a new bulk payment.
You can pay multiple bills that belong to multiple vendors with one POST /v3/payments/bulk API request. If processDate is not set in the request, BILL automatically sets this field as the next US business day.
You just paid multiple bills with one API request. In the response, a BILL-generated payment id is available for the payment made to the vendor.
IMPORTANT: The bills in this API request belong to the same vendor. In the response, a single BILL-generated payment id is available with the billPayments listed. If you pay multiple bills that belong to multiple vendors, a BILL-generated payment id is available for each vendor that you want to pay.
The disbursementType is set as ACH. When BILL starts processing this payment, an additional disbursementInfo object is also available in the response. Finally, singleStatus provides updates at different stages in a BILL payment lifecycle. The values are based on payment status and disbursementStatus. See Single status payment values for the complete list of status values.
You can sign in to the BILL web app to view these payments in your BILL organization. An email is also sent to your email address about the scheduled payments to the ACH vendor.
What you learned in this recipe
You just created AP payments for domestic vendors with the BILL v3 API. You learned a lot along the way.
- Create an API session and perform MFA step-up.
- Create a check vendor record.
- Create a bill record for the vendor.
- Pay the check vendor.
- Pay a vendor without a bill.
- Create multiple bulk bills with one API request.
- Pay multiple bills with one API request.
Updated 4 days ago