Payments

Use POST /v3/payments to pay a vendor bill. If you make a vendor payment without creating a bill, a new bill is auto-generated at the time of payment. You can also use POST /v3/payments/bulk to pay multiple bills with one request. See the /v3/payments API for the complete list of available operations.

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 International payments to learn about paying international vendors. See Payables payment timing in the BILL Help Center to learn about the standard BILL payment process and timing.

👍

Creating a payment is an MFA-trusted operation

Creating a payment requires an MFA-trusted API session. See MFA setup in the API reference for information about the BILL MFA process.

Tutorial: Automate domestic AP payments with BILL v3 API

Create a payment

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

See the POST /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 to link the payment with the bill line items and amount. Funding account details are added to provide a bank account source for the payment.

You can retrieve the bank account id with GET /v3/funding-accounts/banks. See Get list of bank accounts in the API reference for more information.

curl --request POST \
--url 'https://gateway.stage.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": "2026-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": false
  }
}'

In the above request, set createBill as true if you want to create a new bill for the vendor payment. Do not set billId in your payment request.

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. The singleStatus field provides a complete view of your payment based on status and disbursementStatus at different stages of your payment lifecycle. See Single status payment values for more information.

{
  "id": "stp01ZZRCUFIQWHP6ldb",
  "vendorId": "{vendor_id}",
  "vendorName": "{vendor_name}",
  "billId": "{bill_id}",
  "billPayments": [
    {
      "id": "{bill_payment_id}",
      "billId": "{bill_id}",
      "amount": 228.99
    }
  ],
  "description": "Inv #20261231",
  "processDate": "2026-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": false,
    "requestCheckDeliveryType": "STANDARD"
  },
  "transactionNumber": "EPKZLNTSTYSEUWVALISV",
  "confirmationNumber": "P24123101 - 0411839",
  "status": "SCHEDULED",
  "onlinePayment": true,
  "disbursementType": "ACH",
  "createdTime": "2026-12-30T23:56:52.127+00:00",
  "updatedTime": "2026-12-30T23:56:52.127+00:00",
  "createdBy": "{user_id}",
  "voidInfo": [],
  "cancelRequestSubmitted": false,
  "singleStatus": "SCHEDULED"
}

Create payments with BILL Pay Faster

You can pay vendors with faster check and ePayment options with BILL Pay Faster and BILL Instant Payment. To use BILL Pay Faster, set processDate and processingOptions in your API request based on the disbursement method accepted by the vendor (only CHECK or ACH).

If you do not set processDate in your API request, the date is automatically set as the next available payment date.

Rules for payments with BILL Pay Faster

Configure processingOptions in your API request based on your BILL Pay Faster method. We use the example of a payment created on Monday, November 30, 2026 (2026-11-30) at 9 AM PT / 12 PM ET.

👍

BILL Instant Payment (RTP_DELIVERY) method is available only for Verified National Vendors

You can set requestCheckDeliveryType as RTP_DELIVERY only for paying Verified National Vendors in the BILL Network.

See Pay Faster and other expedited payment methods in the BILL Help Center for information about BILL Pay Faster payment limits. See BILL plans and pricing for information about BILL Pay Faster pricing (Under Payor - Transaction Fees).

Sample request: Pay Faster ACH

In this cURL example, a vendor payment of $228.99 is created on Monday, November 30, 2026 at 9 AM PT / 12 PM ET. For the Pay Faster ACH payment, processDate is set as 2026-11-30. The required processingOptions field is set.

curl --request POST \
--url 'https://gateway.stage.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}",
  "description": "Inv #20261130",
  "processDate": "2026-11-30",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true
  }
}'

👍

10 AM PT onwards, processDate is the next US business day

When you are paying with Pay Faster ACH 10 AM PT onwards, the payment processDate must be the next US business day. You cannot set processDate as another date in the future for Pay Faster ACH.

If you do not set processDate, the date is automatically set as the next available payment date.

Response

In the response, a BILL-generated payment id is available. The value begins with stp. In addition, the processDate and processingOptions information confirms that a Pay Faster ACH payment has been created.

{
    "id": "stp02TSDTDYOEJX936sf",
    "vendorId": "{vendor_id}",
    "billId": "{bill_id}",
    "billPayments": [
        {
            "id": "{bill_payment_id}",
            "billId": "{bill_id}",
            "amount": 228.99
        }
    ],
    "description": "Inv #20261130",
    "processDate": "2026-11-30",
    "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
    },
    "amount": 228.99,
    "processingOptions": {
        "requestPayFaster": true,
        "createBill": false
    },
    "transactionNumber": "POMMJRZIIVWFSCYVVCFV",
    "confirmationNumber": "P25042502 - 0716978",
    "status": "SCHEDULED",
    "onlinePayment": true,
    "disbursementType": "ACH",
    "createdTime": "2026-11-30T17:00:00.000+00:00",
    "updatedTime": "2026-11-30T17:00:00.000+00:00",
    "createdBy": "{user_id}",
    "voidInfo": [],
    "cancelRequestSubmitted": false,
    "singleStatus": "SCHEDULED"
}

Common error cases

Payment requests can fail for various reasons. This list highlights some of the more common error cases.