---
updatedAt: 2026-06-26T22:00:26.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Mass payments

Use `POST /v3/payments/mass` to pay up to 2000 bills with one API request. BILL processes each payment in the mass payment request asynchronously.

> 👍 Creating a mass payment is an MFA-trusted operation
>
> Creating a mass 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.

When you create a mass payment, a BILL-generated payment batch ID is available in the response. You can track the current status of each payment in a mass payment batch with `GET /v3/payments/mass/{paymentBatchId}`.

See the <Anchor label="POST /v3/payments/mass" target="_blank" href="ref:createmasspayment">POST /v3/payments/mass</Anchor> API for the complete list of available operations.

## Create a mass payment

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

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

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

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

        **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.
      </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>
        `billId`
      </td>

      <td>
        BILL-generated ID of the bill to be paid. The value begins with **`00n`**.
      </td>
    </tr>

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

      <td>
        Payment amount
      </td>
    </tr>
  </tbody>
</Table>

See the <Anchor label="POST /v3/payments/mass" target="_blank" href="ref:createmasspayment">POST /v3/payments/mass</Anchor> API for more information about the other mass payment fields you can set.

### Sample request

In this cURL example, a mass payment is created with 5 bills. A `billId` is associated with each payment. Funding account details are added to provide a bank account source for the payment. Since `processDate` is not set in the request, BILL automatically sets the date as the next available payment date.

> 👍 You can pay a single vendor or multiple vendors
>
> Your `POST /v3/payments/mass` request can be the same regardless of whether you are paying a single vendor or multiple vendors.

```curl
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/mass' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
    "fundingAccount": {
    	"type": "BANK_ACCOUNT",
    	"id": "{org_bank_account_id}"
  	},
  	"payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    },
    {
      "billId": "{bill_id03}",
      "amount": 100.00
    },
    {
      "billId": "{bill_id04}",
      "amount": 399.99
    },
    {
      "billId": "{bill_id05}",
      "amount": 59.00
    }
  ]
}'
```

### Sample response

BILL processes each payment in the mass payment request asynchronously. In the response, a `paymentBatchId` is available. The value begins with `bbq`. Track the current status of each payment in the mass payment batch with `GET /v3/payments/mass/{paymentBatchId}`.

```json
{
    "paymentBatchId": "{mass_payment_batch_id}"
}
```

## Get mass payment batch status

With `GET /v3/payments/mass/{paymentBatchId}`, you can track the current status or each payment in a mass payment batch.

### Sample response

In the response, `count` is the total number of bills in the payment batch. In addition, the `scheduled`, `completed`, and `failed` arrays list the current payment status of each bill in the mass payment API request.

This is an example response of a mass payment batch of 5 payments.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Mass payment batch status
      </th>

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

  <tbody>
    <tr>
      <td>
        `scheduled`
      </td>

      <td>
        For each payment in the list, BILL has not started generating a `paymentId` value and API response.
      </td>
    </tr>

    <tr>
      <td>
        `completed`
      </td>

      <td>
        For each payment in the list, BILL has successfully generated a `paymentId` value and API response. In the response, if the `paymentId` is the same for multiple bills, the vendor has `combinePayments` set as `true`.

        **Note**: From the list of `completed` payments, BILL begins processing payments based on the payment `processDate`.
      </td>
    </tr>

    <tr>
      <td>
        `failed`
      </td>

      <td>
        An error response is available for each failed payment.

        **Note**: If the vendor has `combinePayments` set as `true` and if a single bill payment fails, the entire list of bill payments made to that vendor will fail.
      </td>
    </tr>
  </tbody>
</Table>

```json
{
    "count": 5,
    "scheduled": [
        {
            "billId": "{bill_id01}"
        },
        {
            "billId": "{bill_id02}"
        }
    ],
    "completed": [
        {
            "billId": "{bill_id03}",
            "paymentId": "{payment_id01}"
        },
        {
            "billId": "{bill_id04}",
            "paymentId": "{payment_id02}"
        }
    ],
    "failed": [
        {
            "billId": "{bill_id05}",
            "errorCode": "BDC_1159",
            "errorMessage": "Cannot overpay a bill."
        }
    ]
}
```

See the <Anchor label="POST /v3/payments/mass" target="_blank" href="ref:createmasspayment">POST /v3/payments/mass</Anchor> API for more information.

<br />