Create a mass payment

post

https://gateway.stage.bill.com/connect/v3/payments/mass

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.

Body Params

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

length ≤ 70

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

processDate

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

int32

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

payments

array of objects

payments

processingOptions

object

Payment processing options

transactionNumber

string

length ≤ 50

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

Headers

sessionId

string | null

API session ID generated with /v3/login

devKey

string | null

Developer key generated with your BILL developer account

Responses

201Create a mass payment response

4XXList of errors.

5XXList of errors.