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

# Create a bulk payment

`POST /v3/payments/bulk`

Create a request for paying multiple bills. You can pay up to 50 bills with one `POST /v3/payments/bulk` request.

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.
* **Vendors with `"combinePayments": true`**: When you create a bulk payment for a vendor that has `"combinePayments": true`, BILL combines payments for up to 35 bills in one `payments` response object, and then combines payments for the remaining bills in a second `payments` response object.

See [Get list of vendor payment options](https://developer.bill.com/reference/listpaymentoptions) to get details about vendor payment options and payment process dates.

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

See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for more information, sample requests, and responses.

## Headers

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

## Request body

- BulkPaymentRequestDto — 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 bulk payment response

- BulkPaymentResponseDto — Bulk payments response.
  - `payments` PaymentResponseDto[] — List of payments
    - `id` string — BILL-generated ID of the payment. The value begins with `stp`.
    - `vendorId` string — BILL-generated ID of the vendor to be paid. The value begins with `009`.
    - `vendorName` string — Vendor name
    - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
    - `billPayments` BillPayment[] — List of bill payments. When a payment is applied to a bill, the bill payment is identified by a bill payment `id`. The value begins with `blp`.
      - `id` string — BILL-generated ID of the bill payment. The value begins with `blp`.
      - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
      - `amount` number — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
      - `vendorCredits` PaymentVendorCreditResponseDto[] — Vendor credits applied to the bill payment
        - `id` string — BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`.
        - `amount` number — Credit amount
    - `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.
    - `fundingAccount` object — Payment funding information
      - `type` 'BANK_ACCOUNT' | 'CARD_ACCOUNT' | 'WALLET' | 'AP_CARD' | 'UNDEFINED', 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.
    - `amount` number, required — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
    - `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.
      - `createBill` boolean — * Set as `false` to create a vendor payment for an existing bill. * Set as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.
      - `requestCheckDeliveryType` 'STANDARD' | 'UPS_1DAY' | 'UPS_2DAY' | 'UPS_3DAY' | 'RTP_DELIVERY' | 'UNDEFINED' — 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.
    - `confirmationNumber` string — BILL-generated bill payment confirmation value
    - `status` 'APPROVING' | 'SCHEDULED' | 'PAID' | 'CANCELLED' | 'VOID' | 'ESCHEATED' | 'UNDEFINED' — Payment status.
    - `exchangeRate` number — Exchange rate for the payment in an international currency (not USD)
    - `fundingAmount` number — Payment amount in USD
    - `onlinePayment` boolean — Payment source. * `true`: Payment is made with BILL (online) * `false`: Payment is made outside BILL and then recorded in BILL (offline)
    - `disbursementType` 'CHECK' | 'ACH' | 'RPPS' | 'PAYPAL' | 'OFFLINE' | 'INTERNATIONAL_E_PAYMENT' | 'AMEX' | 'VIRTUAL_CARD' | 'WALLET' | 'CREDIT_CARD' | 'UNDEFINED' — Disbursement type. This value is set when you create a payment. See `disbursementInfo` for information about the disbursement method used when BILL processes your payment.
    - `remittanceEmail` string — Remittance email address set for the vendor
    - `createdTime` string, date-time — Payment created date and time
    - `updatedTime` string, date-time — Payment updated date and time
    - `createdBy` string — BILL-generated ID of the user that created the payment. The value begins with `006`.
    - `voidInfo` VoidInfo[] — Void request information
      - `id` string — BILL-generated ID of the void payment request. The value begins with `vrq`.
      - `requestedBy` string — BILL-generated ID of the user that requested a void payment. The value begins with `006`.
      - `type` 'VOID_AND_CREDIT' | 'VOID_AND_REISSUE' | 'VOID_ONLY' | 'VOID_AND_REISSUE_VCARD' — Void payment request type.
      - `status` 'TO_BE_PROCESSED' | 'ACCEPTED' | 'REJECTED' | 'NO_OP' | 'ARCHIVED' — Void payment request status.
      - `reason` string — Void payment request reason
      - `createdTime` string, date-time — Void payment request created date and time
      - `updatedTime` string, date-time — Void payment request updated date and time
    - `disbursementStatus` 'SCHEDULE' | 'DONE' | 'FAILED' | 'VOID' | 'HOLD' | 'FXHOLD' | 'ESCHEATED' | 'UNDEFINED' — Payment disbursement status
    - `disbursementInfo` object — Payment disbursement information. This information is based on the disbursement method used when BILL processes your payment. For example, when BILL processes an ACH payment, `disbursementInfo` includes the `sentDate` and `arrivesByDate` fields.
      - `isVoidable` boolean — Set as `true` if the payment disbursement type can be voided
      - `checkDisbursement` object — Check payment disbursement information
        - `sentDate` string, date — Check payment sent date
        - `arrivesByDate` string, date — Check payment arrives by date
        - `checkNumber` integer — Check number
        - `trackingInformation` string — UPS tracking number for the check. You get a tracking number only for a BILL Pay Faster check payment.
      - `achDisbursement` object — ACH payment disbursement information
        - `sentDate` string, date — ACH payment sent date
        - `arrivesByDate` string, date — ACH payment arrives by date
      - `rppsDisbursement` object — ACH payment to verified national vendor disbursement information
        - `sentDate` string, date — ACH payment to verified national vendor sent date
        - `arrivesByDate` string, date — ACH payment to verified national vendor arrives by date
        - `traceNumber` integer — Payment trace number. This value is used to uniquely identify a payment in a batch.
        - `batchNumber` integer — Payment batch number
      - `internationalDisbursement` object — International ePayment disbursement information
        - `sentDate` string, date — International ePayment sent date
        - `arrivesByDate` string, date — International ePayment arrives by date
        - `amount` number — Disbursement amount
        - `disbursementSubType` 'NONE' | 'WIRE' | 'IACH' | 'LOCAL' | 'MULTIPLE' | 'ACH' | 'UNDEFINED' — Payment delivery method for making the International ePayment
      - `vcardDisbursement` object — Virtual card payment disbursement information
        - `arrivesByDate` string, date — Virtual card payment arrives by date
        - `validUntil` string, date — Date until when the card is valid
        - `last4CardNumber` string — Masked number for virtual card
      - `walletDisbursement` object — Instant Transfer (wallet) payment disbursement information
        - `arrivesByDate` string, date — Instant Transfer (wallet) payment arrives by date
    - `paymentPurpose` object — Payment purpose information
      - `text` string — Payment purpose text
      - `code` object — Payment purpose code
        - `name` string — Name
        - `value` string — Value
    - `cardFundingPurpose` string — Card funding purpose
    - `cancelRequestSubmitted` boolean — This field is set as `true` if a cancel payment request is submitted. **Note**: If the payment is cancelled, the payment `status` is set as `CANCELLED`.
    - `singleStatus` 'DISBURSEMENT_FAILED_ACTION_NEEDED' | 'DISBURSEMENT_FAILED_VENDOR_BANK_REJECTED' | 'FUNDING_FAILED_ACTION_NEEDED' | 'EXPIRING' | 'FUNDS_ESCHEATED' | 'CANCELED' | 'FUNDING_FAILED_VOIDED' | 'VOIDED' | 'CLEARED' | 'DELIVERED' | 'DISBURSEMENT_ON_HOLD' | 'VOID_PENDING' | 'SENT' | 'DISBURSEMENT_ON_HOLD_PAYER_IN_REVIEW' | 'PROCESSED' | 'FUNDING_STARTED' | 'FUNDING_ON_HOLD' | 'WAITING_ON_APPROVAL' | 'SCHEDULED' | 'READY_TO_FUND' | 'CANCELLATION_IN_PROGRESS' | 'UNDEFINED' | 'PARTIALLY_CLAIMED' | 'PAID_OFFLINE' — Unified payment status. This field provides BILL payment lifecycle updates based on the `status` and `disbursementStatus` values in the response. See [Single status payment values](https://developer.bill.com/docs/single-status-payment-values) in the Guides section for the list of available values.

## Other responses

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

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)