BIbill
payments

Create a mass payment

Changed on

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 for information about the BILL MFA process.

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

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

vendorIdstring

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

Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

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

exchangeRateBatchIdinteger

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

transactionNumberstring

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.

cardFundingPurposestring

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 for more information.

Example request

{
  "processDate": "2026-12-16",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{{org_bank_account_id}}"
  },
  "payments": [
    {
      "billId": "{{bill_id01}}",
      "amount": 228.99
    },
    {
      "billId": "{{bill_id02}}",
      "amount": 142
    }
  ]
}

Response

Create a mass payment response

paymentBatchIdstring

BILL-generated ID of the mass payment batch. The value begins with bbq.

Example response

{
  "paymentBatchId": "{{mass_payment_batch_id}}"
}

Changes