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 MFA setup 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 POST /v3/payments/mass API for the complete list of available operations.

Create a mass payment

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

Field	Description
`processDate`	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.
`fundingAccount`	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.
`billId`	BILL-generated ID of the bill to be paid. The value begins with `00n`.
`amount`	Payment amount

See the POST /v3/payments/mass 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 --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}.

{
    "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.

Mass payment batch status	Description
`scheduled`	For each payment in the list, BILL has not started generating a `paymentId` value and API response.
`completed`	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`.
`failed`	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.

Mass payment batch status

Description

scheduled

For each payment in the list, BILL has not started generating a paymentId value and API response.

completed

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.

failed

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.

{
    "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 POST /v3/payments/mass API for more information.