---
updatedAt: 2026-06-19T20:32:34.000Z
---

Fetch the complete documentation index at: https://developer.bill.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# 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 <Anchor label="/v3/payments" target="_blank" href="ref:createpayment">/v3/payments</Anchor> 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 <Anchor label="Vendors" target="_blank" href="ap-vendors">Vendors</Anchor> for more information.

See [International payments](https://developer.bill.com/docs/ap-international-payments) to learn about paying international vendors. See <Anchor label="Payables payment timing" target="_blank" href="https://help.bill.com/hc/en-us/articles/115005322726-Payables-payment-timing-">Payables payment timing</Anchor> 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 <Anchor label="MFA setup" target="_blank" href="ref:setup">MFA setup</Anchor> in the API reference for information about the BILL MFA process.

## Tutorial: Automate domestic AP payments with BILL v3 API

<Embed typeOfEmbed="youtube" url="https://www.youtube.com/watch?v=L-GX8BwRd6g" html="%3Ciframe%20class%3D%22embedly-embed%22%20src%3D%22%2F%2Fcdn.embedly.com%2Fwidgets%2Fmedia.html%3Fsrc%3Dhttps%253A%252F%252Fwww.youtube.com%252Fembed%252FL-GX8BwRd6g%253Ffeature%253Doembed%26display_name%3DYouTube%26url%3Dhttps%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DL-GX8BwRd6g%26image%3Dhttps%253A%252F%252Fi.ytimg.com%252Fvi%252FL-GX8BwRd6g%252Fhqdefault.jpg%26type%3Dtext%252Fhtml%26schema%3Dyoutube%22%20width%3D%22854%22%20height%3D%22480%22%20scrolling%3D%22no%22%20title%3D%22YouTube%20embed%22%20frameborder%3D%220%22%20allow%3D%22autoplay%3B%20fullscreen%3B%20encrypted-media%3B%20picture-in-picture%3B%22%20allowfullscreen%3D%22true%22%3E%3C%2Fiframe%3E" href="https://www.youtube.com/watch?v=L-GX8BwRd6g" providerUrl="https://www.youtube.com/" providerName="YouTube" />

## Create a payment

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

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `billId`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `processDate`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `fundingAccount`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `amount`
      </td>

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

    <tr>
      <td>
        `processingOptions`
      </td>

      <td>
        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.
      </td>
    </tr>
  </tbody>
</Table>

See the <Anchor label="POST /v3/payments" target="_blank" href="ref:createpayment">POST /v3/payments</Anchor> 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 <Anchor label="Get list of bank accounts" target="_blank" href="ref:listbankaccounts">Get list of bank accounts</Anchor> in the API reference for more information.

```curl
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 <Anchor label="Single status payment values" target="_blank" href="doc:single-status-payment-values">Single status payment values</Anchor> for more information.

```json
{
  "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**.

<Accordion title="Pay Faster ACH">
  * **Request**: Set `requestPayFaster` as `true`.
  * **Response**: `processDate` is set as `2026-11-30`. If the payment is created 10 AM PT onwards, `processDate` is set as the next US business day.
  * **Estimated payment arrival date**: `2026-11-30`. If the payment is created 10 AM PT onwards, the estimated arrival date is the next US business day after the `processDate`.
</Accordion>

<Accordion title="Pay Faster Check (UPS 1-day)">
  * **Request**:
    * Set `requestPayFaster` as `true`.
    * Set `requestCheckDeliveryType` as `UPS_1DAY`.
  * **Response**: `processDate` is set as `2026-12-01`.
  * **Estimated payment arrival date**: `2026-12-02`.
</Accordion>

<Accordion title="Pay Faster Check (UPS 2-days)">
  * **Request**:
    * Set `requestPayFaster` as `true`.
    * Set `requestCheckDeliveryType` as `UPS_2DAY`.
  * **Response**: `processDate` is set as `2026-12-01`.
  * **Estimated payment arrival date**: `2026-12-03`.
</Accordion>

<Accordion title="Pay Faster Check (UPS 3-days)">
  * **Request**:
    * Set `requestPayFaster` as `true`.
    * Set `requestCheckDeliveryType` as `UPS_3DAY`.
  * **Response**: `processDate` is set as `2026-12-01`.
  * **Estimated payment arrival date**: `2026-12-04`.
</Accordion>

<Accordion title="Instant Payment">
  * **Request**:
    * Set `requestPayFaster` as `true`.
    * Set `requestCheckDeliveryType` as `RTP_DELIVERY`.
  * **Response**: `processDate` is set as `2026-11-30`.
  * **Estimated payment arrival date**: `2026-11-30`.
</Accordion>

> 👍 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 <Anchor label="Pay Faster and other expedited payment methods" target="_blank" href="https://help.bill.com/hc/en-us/articles/115005467886-Pay-bills-using-Pay-Faster">Pay Faster and other expedited payment methods</Anchor> in the BILL Help Center for information about BILL Pay Faster payment limits. See <Anchor label="BILL plans and pricing" target="_blank" href="https://www.bill.com/product/pricing">BILL plans and pricing</Anchor> 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
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.

```json
{
    "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"
}
```

## Vendors that accept virtual card payments

In addition to check and ACH, virtual card is another payment disbursement method available at BILL. When you pay a vendor with virtual card, BILL sends the vendor a single-use, 16-digit Mastercard or Visa number for the payment amount.

See <Anchor label="AP payment disbursement methods" target="_blank" href="https://developer.bill.com/docs/ap-payment-disbursement-methods#virtual-card">AP payment disbursement methods</Anchor> for more information about virtual cards.

```python Check whether a vendor accepts virtual card payments
# Install Python 3 & the requests library (pip install requests)
import requests, json

# Set your session ID with POST /v3/login
session_id = "set_your_session_id"
developer_key = "set_your_developer_key"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "sessionId": session_id,
    "devKey": developer_key
}

# Get list of vendors with GET /v3/vendors
vendor_id = "set_vendor_id"

# Production URL https://gateway.prod.bill.com/connect
getvcardstatus_url = "https://gateway.stage.bill.com/connect/v3/vendors/" + vendor_id
getvcardstatus_response = requests.get(getvcardstatus_url, headers=headers)

# Retrieve virtual card enrollment status
vcardstatus = json.loads(getvcardstatus_response.text)['paymentInformation']['virtualCard']['status']

if vcardstatus == "ENROLLED":
    print("Vendor is enrolled to receive virtual card payments.")
else:
    print("Vendor is NOT enrolled to receive virtual card payments.")
```

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