PayBills

About PayBills

Use this API to make Bill.com payments (one or more bills and one or more bill credits) to a designated Vendor. These are paid from a specified bank account.

MFA

This is a Multi Factor Authentication (MFA) trusted endpoint. For more information, see the Multi Factor Authentication Workflow in order to establish an MFA trusted session prior to using this endpoint.

Note: Developers who joined the Developer Program and used this endpoint prior to March 31st, 2017 will not require an MFA Trusted Session to use this endpoint.

User role profile

The user that calls this API needs to be assigned the Administrator, Payer, or customized User Role Profile with the pay bills permission enabled. If not, an error is returned when the user tries to pay a bill.

Flow for processing payments

Bill.com follows a specific flow for processing payments:

• If a process date is not specified, the payment is sent on the next bank work day.
• The earliest available process date is the next business day, not including holidays
• Payments will not process on weekends or bank holidays
• The process date for a payment cannot be changed/edited once a payment is scheduled
• If vendor is setup for ePayment, funds are transferred by ACH. If ePayment has not been setup, a check is sent (via UPS) to the vendor's mailing address.
• Any memo information entered in the description field is included on the check or in a bank descriptor for ePayment
• You can pay a maximum of 200 bills in one PayBills request
• You can specify your bank account with the bankAccountId parameter

Example

Note: The nested billPays array must include billId and amount applied to the specified bill. If you are applying bill credits to a bill, billId, vendorCreditId and amount are required parameters in the billCredits array.

In this example:

• A bill payment of 100.00 is made for the 00n01ZWAMLTSFBS5ao2z bill
• A bill payment of 100.00 (99.00 amount + 1.00 bill credit) is made for the 00n01FSFJWBRPEQ5ao4q bill

Request

<API_URL_EndPoint>/PayBills.json

data={
 "vendorId" : "00901AYXJFMTDDO4xat5",
 "processDate" : "2021-01-19",
 "billPays" : [ {
   "billId" : "00n01ZWAMLTSFBS5ao2z",
   "amount" : 100.00
 }, { 
   "billId" : "00n01FSFJWBRPEQ5ao4q",
   "amount" : 99.00
} ],
 "billCredits" : [ {
   "billId" : "00n01FSFJWBRPEQ5ao4q",
   "vendorCreditId" : "vcr01HPCWEVWUAR1d9bv",
   "amount" : 1.00
 } ]
}

Response

{
 "response_status" : 0,
 "response_message" : "Success",
 "response_data" : {
 "sentPays" : [ {
 "entity" : "SentPay",
 "id" : "stp01WJWSEQDTWFuxzud",
 "processDate" : "2021-01-19",
 "amount" : 166.00,
 "status" : "1",
 "description" : "Acct #12198649-Multiple inv. (details on stub)",
 "txnNumber" : "VNGJHAWGCMQCBBFCVNWF",
 "name" : "P17011801 - 5611696",
 "vendorId" : "00901AYXJFMTDDO4xat5",
 "isOnline" : true,
 "paymentType" : "0",
 "chartOfAccountId" : "0ca01JSZETHAFXE62xr3",
 "syncReference" : null,
 "toPrintCheck" : false,
 "createdTime" : "2021-01-18T18:44:12.000+0000",
 "updatedTime" : "2021-01-18T18:44:12.000+0000",
 "bankAccountId" : "bac01PKPPVUUEPZGdj0y",
 "billPays" : [ {
   "entity" : "BillPay",
     "id" : "blp01GPBBKBKIF1qvmhz",
     "billId" : "00n01ZWAMLTSFBS5ao2z",
     "name" : "P17011801 - 5611696",
     "paymentStatus" : "1",
     "amount" : 100.00,
     "description" : "Acct #12198649-Multiple inv. (details on stub)",
     "processDate" : "2021-01-19",
     "createdTime" : "2021-01-18T18:44:12.000+0000",
     "updatedTime" : "2021-01-18T18:44:12.000+0000",
     "paymentType" : "0",
     "syncReference" : null,
     "toPrintCheck" : false,
     "chartOfAccountId" : "0ca01JSZETHAFXE62xr3"
   }, {
   "entity" : "BillPay",
     "id" : "blp01JWKRENZIS1qvmi0",
     "billId" : "00n01FSFJWBRPEQ5ao4q",
     "name" : "P17011801 - 5611696",
     "paymentStatus" : "1",
     "amount" : 66.00,
     "description" : "Acct #12198649-Multiple inv. (details on stub)",
     "processDate" : "2021-01-19",
     "createdTime" : "2021-01-18T18:44:12.000+0000",
     "updatedTime" : "2021-01-18T18:44:12.000+0000",
     "paymentType" : "0",
     "syncReference" : null,
     "toPrintCheck" : false,
     "chartOfAccountId" : "0ca01JSZETHAFXE62xr3"
 } ],
 "billCredits" : [ {
   "entity" : "BillCredit",
   "id" : "bcr01IMMIHDAECJ10t7u",
   "isActive" : "1",
   "billId" : "00n01FSFJWBRPEQ5ao4q",
   "sentPayId" : "stp01WJWSEQDTWFuxzud",
   "vendorCreditId" : "vcr01HPCWEVWUAR1d9bv",
   "amount" : 0.90,
   "createdTime" : "2021-01-18T18:44:12.000+0000",
   "updatedTime" : "2021-01-18T18:44:12.000+0000"
 } ],
 "voidRequests" : [ ]
 } ]
 }
}

International ePayments

Since the Bill.com foreign exchange rate changes periodically, a current exchange rate batchId is an additional required parameter while making bill payments to international vendors via international ePayments.

See GetDynamicExchangeRateQuote for information about retrieving batchId.

In your Bill.com payment request with PayBills.json, set batchId as the retrieved value and amount as the bill amount to be paid in the foreign currency.

In this example, if the retrieved batchId is for Canadian Dollar, the payment amount in <API_URL_EndPoint>/PayBills.json is also in Canadian Dollar.

Request

<API_URL_EndPoint>/PayBills.json

data={
 "vendorId" : "00901PUSPHXRWUMQ6su1",
 "batchId": 908,
 "processDate" : "2021-01-19",
 "billPays" : [ {
   "billId" : "00n01TRVCIPCRVSZ96vh",
   "amount" : 5.00
 } ],
 "billCredits" : [ {
   "billId" : "00n01TRVCIPCRVSZ96vh",
   "vendorCreditId" : "vcr01HPCWEVWUAR1d9bv",
   "amount" : 1.00
}

Resources

• Authentication Workflow
• Payment Management
• BillPay
• SentPay
• VendCredit

Parameters