Guides
System Status
Start typing to search…

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 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.

Create a payment

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

Field

Description

billId

BILL-generated ID of the bill to be paid. The value begins with 00n. If createBill is true, do not set billId in your payment request.

processDate

Bill 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.

fundingAccount

Funding 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.

amount

Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.

processingOptions

Payment 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 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/bankaccounts. 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": "2025-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 #20251231",
  "processDate": "2025-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": "2025-12-30T23:56:52.127+00:00",
  "updatedTime": "2025-12-30T23:56:52.127+00:00",
  "createdBy": "{user_id}",
  "voidInfo": [],
  "singleStatus": "SCHEDULED"
}

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.

Create a payment with Pay Faster

With BILL Pay Faster, you can pay vendors with faster check and ePayment options.

To use the Pay Faster feature, set processDate and processingOptions based on the disbursement method accepted by the vendor (only CHECK or ACH).

❗️

The RTP_DELIVERY option is not available for vendor payments by check

You can set the RTP_DELIVERY option only if the vendor accepts ACH payments or if the vendor is connected in the BILL network.

BILL Pay Faster

Rules (for a payment created on Monday, December 1, 2025 at 9 AM PT / 12 PM ET)

Estimated payment arrival date

ACH payment

  • Earliest processDate is 2025-12-01
  • Set requestPayFaster as true
  • Set requestCheckDeliveryType as RTP_DELIVERY

2025-12-01

Check payment via UPS 1-day delivery

  • Earliest processDate is 2025-12-02
  • Set requestPayFaster as true
  • Set requestCheckDeliveryType as UPS_1DAY

2025-12-03

Check payment via UPS 2-days delivery

  • Earliest processDate is 2025-12-02
  • Set requestPayFaster as true
  • Set requestCheckDeliveryType as UPS_2DAY

2025-12-04

Check payment via UPS 3-days delivery

  • Earliest processDate is 2025-12-02
  • Set requestPayFaster as true
  • Set requestCheckDeliveryType as UPS_3DAY

2025-12-05

Check payment via USPS to a PO Box or a non-serviceable vendor address

  • Earliest processDate is 2025-12-02
  • Set requestPayFaster as true
  • Set requestCheckDeliveryType as USPS_PRIORITY

2025-12-05

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 payment

In this cURL example, a vendor payment of $228.99 is created on Monday, December 1, 2025 at 9 AM PT / 12 PM ET. For the Pay Faster ACH payment, processDate is set as 2025-12-01. The required processingOptions fields are 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 #20251201",
  "processDate": "2025-12-01",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true,
    "requestCheckDeliveryType": "RTP_DELIVERY"
  }
}'

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 #20251201",
    "processDate": "2025-12-01",
    "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
    },
    "amount": 228.99,
    "processingOptions": {
        "requestPayFaster": true,
        "createBill": false,
        "requestCheckDeliveryType": "RTP_DELIVERY"
    },
    "transactionNumber": "POMMJRZIIVWFSCYVVCFV",
    "confirmationNumber": "P25042502 - 0716978",
    "status": "SCHEDULED",
    "onlinePayment": true,
    "disbursementType": "ACH",
    "createdTime": "2025-12-01T17:00:00.000+00:00",
    "updatedTime": "2025-12-01T17:00:00.000+00:00",
    "createdBy": "{user_id}",
    "voidInfo": [],
    "cancelRequestSubmitted": false,
    "singleStatus": "SCHEDULED"
}

Create a bulk payment

Bulk payments at BILL follow a set of rules.

  • Successful response: In your bulk payment request, all your bill payments must be successful for a successful response. If any bill payment is not successful, the entire request fails and none of the bills in the request are paid.
  • You can pay multiple vendors: You can pay multiple vendors with one POST /v3/payments/bulk request. In this case, make sure that you do not set vendorId in your request.
  • You can only pay existing bills: When you create a single payment with POST /v3/payments, you can set createBill as true in your request for creating a new bill for a vendor payment. In your bulk payment request, an existing billId is required for each bill to be paid.

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

Field

Description

processDate

Bill payment processing date in the yyyy-MM-dd format. Funds are withdrawn from the sender's funding account on this date.

  • Note*: When you add a vendor bank account, BILL requires 2 business days to complete a one-time verification of the bank account. To pay such a vendor, you must set a processDate that is at least 2 business days from the current date.

fundingAccount

Funding 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.

billId

BILL-generated ID of the bill to be paid. This value begins with 00n.

amount

Payment amount

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

Bulk payment to multiple vendors

In this cURL example, a bulk payment is created with two bills that belong to different vendors. The billId is associated with each payment. Funding account details are added to provide a bank account source for the payment.

👍

BILL v3 payments is powerful

Your POST /v3/payments/bulk request can be the same regardless of whether you are paying a single vendor or multiple vendors.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
    "processDate": "2025-12-16",
    "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}"
  },
  "payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Sample response

In this successful response, a different BILL-generated payment id is available for each payment made to each vendor. Each id value begin with stp.

The billPayments object shows that the payment amount is applied to each bill. The bill payment is identified by a bill payment id. This value begins with blp. 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.

{
  "payments": [
    {
      "id": "stp02TAXHUYITPCGf3b5",
      "vendorId": "{vendor_id01}",
      "billId": "{bill_id01}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id01}",
          "amount": 228.99
        }
      ],
      "description": "Inv #1216202502",
      "processDate": "2025-12-16",
      "fundingAccount": {
         "type": "BANK_ACCOUNT",
         "id": "{org_bank_account_id}"
      },
      "amount": 228.99,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24121502 - 1389127",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2025-12-15T20:59:39.816+00:00",
      "updatedTime": "2025-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    },
    {
      "id": "stp02TAXHUYITPCGf3b6",
      "vendorId": "{vendor_id02}",
      "billId": "{bill_id02}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id02}",
          "amount": 142.00
        }
      ],
      "description": "Inv #1216202501",
      "processDate": "2025-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
      },
      "amount": 142.00,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAES",
      "confirmationNumber": "P24121502 - 1389129",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2025-12-15T20:59:39.816+00:00",
      "updatedTime": "2025-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    }
  ]
}

Error response

In the above POST /v3/payments/bulk request, consider an example where the payment amount for the first bill is greater than the $228.99 bill amount. This will result in an error response.

In this error response, there are details about the error at the individual bill level. The entire request fails and none of the bills in the request are paid.

[
    {
        "timestamp": "2025-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Cannot overpay a bill."
    },
    {
        "timestamp": "2025-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "{bill_id01}: Cannot overpay a bill."
    }
]

Combine bulk payments to a single vendor

In the above cURL example, consider that the two bills belong to the same vendor that has combinePayments set as true.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
    "processDate": "2025-12-16",
    "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}",
    "vendorId": {vendor_id}
  },
  "payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Sample response

In this successful response, one BILL-generated payment id is available for the bulk payment made to the same vendor. This value begin with stp. The bulk payment amount is combined and sent to the vendor.

👍

You can pay vendors regardless of the combinePayments value

If the vendor does not have combinePayments set as true, the POST /v3/payments/bulk response includes a different payment id for each payment made to the vendor. The response looks just like a bulk payments response made to multiple vendors.

The billPayments object shows that the payment amount is applied to each bill. The bill payment is identified by a bill payment id. This value begins with blp. In addition, disbursement information is available based on the type of payment.

{
  "payments": [
    {
      "id": "stp02TAXHUYITPCGf3b5",
      "vendorId": "{vendor_id}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id01}",
          "amount": 228.99
        },
        {
          "id": "{bill_payment_id02}",
          "billId": "{bill_id02}",
          "amount": 142.00
        }
      ],
      "description": "Multiple inv. (details on stub)",
      "processDate": "2025-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
      },
      "amount": 370.99,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24121502 - 1389127",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2025-12-15T20:59:39.816+00:00",
      "updatedTime": "2025-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    }
  ]
}

See the /v3/payments/bulk API for more information.

Common error cases

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

Common error cases
Bill ID not found.
Vendor ID not found.
Cannot overpay a bill.
Invalid process date.
Bank account is inactive.
Card account is inactive.

Updated 8 days ago