---
title: "Create a mass payment"
method: POST
path: "/v3/payments/mass"
tags: ["payments"]
---

# Create a mass payment

`POST /v3/payments/mass`

## Request

- Base URL: `https://gateway.stage.bill.com/connect`
- URL: `https://gateway.stage.bill.com/connect/v3/payments/mass`
- Auth: none declared

Create a mass payment request for up to 2000 bills. BILL processes each payment in the mass payment request asynchronously.

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

**Note**: Creating a mass payment requires an MFA-trusted API session. See [MFA setup](https://developer.bill.com/reference/setup) for information about the BILL MFA process.

## Headers

- `sessionId` string, nullable: API session ID generated with `/v3/login`
- `devKey` string, nullable: Developer key generated with your BILL developer account

## Request body

- MassPaymentRequestDto: Create a bulk payment
  - `vendorId` string: BILL-generated ID of the vendor to be paid. The value begins with `009`. * If `vendorId` is set, it must match each bill’s vendor ID. * Do not set `vendorId` when you are paying multiple vendors with one request.
  - `description` string: Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.
  - `processDate` string, date: Payment process date in the `yyyy-MM-dd` format. On this date, BILL starts processing the payment and starts withdrawing funds from the sender's funding account. When the vendor bill currency is not `USD` (For example, `EUR`), the payment `processDate` for this vendor must be the next US business day. If the funding account `type` is set as `WALLET` or `AP_CARD`, `processDate` is required. For other funding account types, if `processDate` is not set, the date is automatically set as the next US business day. **Note**: When you add a vendor bank account in the production environment, 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 2 business days from the current date.
  - `exchangeRateBatchId` integer: Exchange rate batch ID. This field is required for paying international vendors when the vendor bill currency is not `USD`. Get the current BILL exchange rate and exchange rate batch ID with `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate` (for multiple international vendors).
  - `fundingAccount` object, required: Payment funding information
    - `type` 'BANK_ACCOUNT' | 'CARD_ACCOUNT' | 'WALLET' | 'AP_CARD', required: Payment funding type. * `BANK_ACCOUNT`: Bank account * `CARD_ACCOUNT`: Credit card or debit card * `WALLET`: BILL balance * `AP_CARD`: AP Card See the BILL Help FAQ sections for [BILL balance](https://help.bill.com/direct/s/article/4409933681677) and [AP Card](https://help.bill.com/direct/s/article/000003348) for more information.
    - `id` string: BILL-generated ID of the selected payment funding type. For the `WALLET` type, the `id` is not required.
  - `payments` BillPay[]
    - `billId` string, required: BILL-generated ID of the bill to be paid. The value begins with `00n`.
    - `amount` number, required: Payment amount
    - `vendorCredits` PaymentVendorCreditRequestDto[]: Vendor credits applied to the bill payment
      - `id` string, required: BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`.
      - `amount` number, required: Credit amount
  - `processingOptions` object: Payment processing options
    - `requestPayFaster` boolean: Set as `true` to use BILL Pay Faster. This field is required if `requestCheckDeliveryType` is set. See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for information about BILL Pay Faster payments.
    - `requestCheckDeliveryType` 'STANDARD' | 'UPS_1DAY' | 'UPS_2DAY' | 'UPS_3DAY' | 'RTP_DELIVERY': BILL Pay Faster payment delivery type. The `RTP_DELIVERY` option is not available for vendor payments by check.
  - `transactionNumber` string: Payment transaction reference used as an external identifier. You can set this field as a unique alphanumeric value for your system to track the payment transaction. The value must be 50 characters or fewer. If you do not set `transactionNumber`, BILL sets this field as a unique alphanumeric payment identification value.
  - `cardFundingPurpose` string: Card funding purpose. This field is required for the `CARD_ACCOUNT` funding account `type` if BILL cannot identify the vendor industry. See [Get card funding purpose](https://developer.bill.com/reference/listcardfundingpurposes) for more information.

## Response `201`

Create a mass payment response

- MassPaymentResponseDto: Mass payment response DTO.
  - `paymentBatchId` string: BILL-generated ID of the mass payment batch. The value begins with `bbq`.

## Other responses

- `4XX`: List of errors.
- `5XX`: List of errors.

## Changes

- **2026-11-03** `54edddceb0a5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bill/apis/bill-v3-api/changes/v3/payments/mass/post.md)

---

[API](https://skmtc.dev/bill/apis/bill-v3-api.md) - [All operations](https://skmtc.dev/bill/apis/bill-v3-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bill/apis/bill-v3-api/revisions/54edddceb0a5?raw)