Payments

Use POST /v3/payments to pay a vendor bill. If you make a vendor payment without creating a bill, a new bill is auto-generated at the time of payment. You can also use POST /v3/payments/bulk to pay multiple bills with one request.

When you pay a vendor, BILL sends a payment check to the vendor. To enable electronic payments, vendor bank account information and additional vendor details are required. See Vendors for more information.

See Payables payment timing in the BILL Help Center to learn about the standard BILL payment process and timing.

Creating a payment

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

Field	Description
`billId`	BILL-generated ID of the bill to be paid. This value begins with `00n`. If `createBill` is `true`, do not set `billId` in your payment request.
`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.
`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.
`amount`	Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.
`processingOptions`	Payment processing options. - Set `createBill` as `false` to create a vendor payment for an existing bill. - Set `createBill` as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.

See the /v3/payments API for more information about the other payment fields you can set.

Sample request

In this cURL example, a vendor payment of $228.99 is created for the vendor (vendorId).

The billId is associated with the payment to link the payment with the bill line items and bill amount. Funding account details are added to provide a bank account source for the payment. In the example, the bank account id is retrieved with GET /v3/bankaccounts. See Get list of bank accounts in the API reference for more information.

The requestPayFaster option is set to specify that the payment is eligible for Pay Faster. See Pay bills using Pay Faster in the BILL Help Center for more information.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "billId": "{bill_id}",
  "processDate": "2024-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "bac01123ABC456DEF789"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true,
    "createBill": false
  }
}'

In the above request, set createBill as true if you want to create a new bill for the vendor payment. do not set billId in your payment request.

Response

In the response, a BILL-generated payment id is available. The value begins with stp. In addition, disbursement information is available based on the type of payment.

{
  "vendorId": "{vendor_id}",
  "billId": "{bill_id}",
  "description": "Inv #202401",
  "processDate": "2024-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "bac01123ABC456DEF789"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": true,
    "createBill": false,
    "requestCheckDeliveryType": "STANDARD"
  },
  "id": "stp01ZZRCUFIQWHP6ldb",
  "transactionNumber": "EPKZLNTSTYSEUWVALISV",
  "confirmationNumber": "P23070501 - 0411839",
  "status": "SCHEDULED",
  "onlinePayment": true,
  "disbursementType": "ACH",
  "createdTime": "2024-12-30T23:56:52.524Z",
  "updatedTime": "2024-12-30T23:56:52.000Z",
  "createdBy": "{user_id}",
  "voidInfo": []
}

If the payment is created in an international currency (not USD), there are three payment amount-related fields to note.

Field	Description
`amount`	Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.
`fundingAmount`	Payment amount in USD
`exchangeRate`	Exchange rate for the payment in an international currency (not USD)

You can use the payment id for other payment operations. See the /v3/payments API for more information.

Creating a bulk payment

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.

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

Field	Description
`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. This value begins with `00n`.
`amount`	Payment amount

See the /v3/payments/bulk API for more information about the other bulk payment fields you can set.

Sample request

In this cURL example, a bulk payment request is created for two bills.

The billId is associated with each payment. Funding account details are added to provide a bank account source for the payment.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "bac01123ABC456DEF789"
  },
  "payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Successful response

In this successful response, a BILL-generated payment id is available for each bill in the bulk payment. The value begins with stp. In addition, disbursement information is available based on the type of payment.

{
  "payments": [
    {
      "vendorId": "{vendor_id}",
      "description": "Inv #invoice-e9c84dbc-f22d-4ced-9a9b-405f92004fb4",
      "processDate": "2024-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "bac01123ABC456DEF789"
      },
      "amount": 228.99,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "id": "stp02TAXHUYITPCGf3b5",
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24041502 - 1389127",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2024-12-15T20:59:39.816+00:00",
      "updatedTime": "2024-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": []
    },
    {
      "vendorId": "{vendor_id}",
      "description": "Inv #invoice-6938e207-9168-45c4-898f-1eaceb834a76",
      "processDate": "2024-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "bac01123ABC456DEF789"
      },
      "amount": 142.00,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "id": "stp02YGCIPECNPDDE9hv",
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24041502 - 1389129",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2024-12-15T20:59:39.816+00:00",
      "updatedTime": "2024-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": []
    }
  ]
}

Error response

In this error response for the above POST /v3/payments/bulk sample request, since there is an error with creating the first payment, the entire request fails and none of the payments in the request are created. In this example, the amount for the first bill in the request was greater than the expected $228.99 amount.

[
    {
        "timestamp": "2024-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Cannot overpay a bill."
    },
    {
        "timestamp": "2024-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "00n02OCUSRUMYUQ82xkk : Cannot overpay a bill."
    },
    {
        "timestamp": "2024-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "00n02HAJPXXNUHJ82xkl : Cannot overpay a bill."
    }
]

See the /v3/payments/bulk API for more information.