Payments

Use the /v3/payments API to pay vendor bills with BILL. If you make a vendor payment without creating a bill, a new bill is auto-generated at the time of payment.

When you pay a vendor, BILL sends a payment check to the vendor. To enable electronic payments, vendor bank account information and additional vendor details are required. See Vendors for more information.

See Payables payment timing in the BILL Help Center to learn about the standard BILL payment process and timing.

Creating a payment

In your POST /v3/payments request, set the required fields.

FieldDescription
vendorIdBILL-generated ID of the vendor you want to pay. This value begins with 009.
billIdBILL-generated ID of the bill to be paid. This value begins with 00n. If createBill is true, do not set billId in your payment request.
processDateBill payment processing date in the yyyy-MM-dd format. Funds are withdrawn from the sender's funding account on this date.

If the funding account type is set as WALLET, processDate is required. For other funding account types, if processDate is not set, the date is automatically set as the next available payment date.
fundingAccountFunding account information.
- type (BANK_ACCOUNT, CARD_ACCOUNT, or WALLET (BILL balance))
- id: BILL-generated ID of the selected payment funding type. For the WALLET type, id is not required.
amountPayment amount information. For a payment in an international currency (not USD), this value is in the local currency.
processingOptionsPayment processing options.
- Set createBill as false to create a vendor payment for an existing bill.
- Set createBill as true to create a bill for a vendor payment. If createBill is true, do not set billId in your payment request.

See the /v3/payments API for more information about the other payment fields you can set.

Sample request

In this cURL example, a vendor payment of $228.99 is created for the vendor (vendorId).

The billId is associated with the payment for line item and amount details. Funding account details are added to provide a bank account source for the payment. In the example, the bank account id is retrieved with POST /v2/List/BankAccount.json. See List organization bank accounts in the BILL v2 API reference for more information.

The requestPayFaster option is set to specify that the payment is eligible for Pay Faster. See Pay bills using Pay Faster in the BILL Help Center for more information.

curl --request POST \
--url 'https://gateway.sandbox.bill.com/connect/v3/payments' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "billId": "{bill_id}",
  "processDate": "2024-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "bac01123ABC456DEF789"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true,
    "createBill": false
  }
}'

In the above request, set createBill as true in the processingOptions object if you are not associating a billId with the vendor payment.

Response

In the response, a BILL-generated payment id is available. The value begins with stp. In addition, disbursement information is available based on the type of payment.

{
  "vendorId": "{vendor_id}",
  "billId": "{bill_id}",
  "description": "Inv #202401",
  "processDate": "2024-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "bac01123ABC456DEF789"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true,
    "createBill": false,
    "requestCheckDeliveryType": "STANDARD"
  },
  "id": "stp01ZZRCUFIQWHP6ldb",
  "transactionNumber": "EPKZLNTSTYSEUWVALISV",
  "confirmationNumber": "P23070501 - 0411839",
  "status": "SCHEDULED",
  "onlinePayment": true,
  "disbursementType": "ACH",
  "createdTime": "2024-12-30T23:56:52.524Z",
  "updatedTime": "2024-12-30T23:56:52.000Z",
  "createdBy": "{user_id}"
}

If the payment is created in an international currency (not USD), there are three payment amount-related fields to note.

FieldDescription
amountPayment amount information. For a payment in an international currency (not USD), this value is in the local currency.
fundingAmountPayment amount in USD
exchangeRateExchange rate for the payment in an international currency (not USD)

You can use the payment id for other payment operations. See the /v3/payments API for more information.