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.
{
"id": "stp01ZZRCUFIQWHP6ldb",
"vendorId": "{vendor_id}",
"vendorName": "{vendor_name}",
"billId": "{bill_id}",
"billPayments": [
{
"id": "{bill_payment_id}",
"billId": "{bill_id}",
"amount": 228.99
}
],
"description": "Inv #20241231",
"processDate": "2024-12-31",
"fundingAccount": {
"type": "BANK_ACCOUNT",
"id": "bac01123ABC456DEF789"
},
"amount": 228.99,
"processingOptions": {
"requestPayFaster": true,
"createBill": false,
"requestCheckDeliveryType": "STANDARD"
},
"transactionNumber": "EPKZLNTSTYSEUWVALISV",
"confirmationNumber": "P24123101 - 0411839",
"status": "SCHEDULED",
"onlinePayment": true,
"disbursementType": "ACH",
"createdTime": "2024-12-30T23:56:52.127+00:00",
"updatedTime": "2024-12-30T23:56:52.127+00:00",
"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 setvendorId
in your request. - You can only pay existing bills: When you create a single payment with
POST /v3/payments
, you can setcreateBill
astrue
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.
Bulk payment for multiple vendors
In this cURL example, a bulk payment is created for two bills that belong to different vendors. The billId
is associated with each payment. Funding account details are added to provide a bank account source for the payment.
IMPORTANT
Your
POST /v3/payments/bulk
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/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
}
]
}'
Sample response
In this successful response, a different BILL-generated payment id
is available for each payment made to each vendor. Each id
value begin with stp
.
The billPayments
object shows that the payment amount
is applied to each bill. The bill payment is identified by a bill payment id
. This value begins with blp
. In addition, disbursement information is available based on the type of payment.
{
"payments": [
{
"id": "stp02TAXHUYITPCGf3b5",
"vendorId": "{vendor_id01}",
"billId": "{bill_id01}",
"billPayments": [
{
"id": "{bill_payment_id01}",
"billId": "{bill_id01}",
"amount": 228.99
}
],
"description": "Inv #1216202402",
"processDate": "2024-12-16",
"fundingAccount": {
"type": "BANK_ACCOUNT",
"id": "bac02MECARDNIAFL35wz"
},
"amount": 228.99,
"processingOptions": {
"requestPayFaster": false,
"requestCheckDeliveryType": "STANDARD"
},
"transactionNumber": "EHHXAICWPQDUEIBOEAER",
"confirmationNumber": "P24121502 - 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": []
},
{
"id": "stp02TAXHUYITPCGf3b6",
"vendorId": "{vendor_id02}",
"billId": "{bill_id02}",
"billPayments": [
{
"id": "{bill_payment_id01}",
"billId": "{bill_id02}",
"amount": 142.00
}
],
"description": "Inv #1216202401",
"processDate": "2024-12-16",
"fundingAccount": {
"type": "BANK_ACCOUNT",
"id": "bac02MECARDNIAFL35wz"
},
"amount": 142.00,
"processingOptions": {
"requestPayFaster": false,
"requestCheckDeliveryType": "STANDARD"
},
"transactionNumber": "EHHXAICWPQDUEIBOEAES",
"confirmationNumber": "P24121502 - 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 the above POST /v3/payments/bulk
request, consider an example where the payment amount
for the first bill is greater than the $228.99
bill amount. This will result in an error response.
In this error response, there are details about the error at the individual bill level. The entire request fails and none of the bills in the request are paid.
[
{
"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": "{bill_id01}: Cannot overpay a bill."
}
]
Bulk payment for a single vendor
In the above cURL example, consider that the two bills belong to the same vendor that has combinePayments
set as true
.
In this successful response, one BILL-generated payment id
is available for the bulk payment made to the same vendor. This value begin with stp
. The bulk payment amount
is combined and sent to the vendor.
IMPORTANT
If the vendor does not have
combinePayments
set astrue
, thePOST /v3/payments/bulk
response includes a different paymentid
for each payment made to the vendor. The response looks just like a bulk payments response made to multiple vendors.
The billPayments
object shows that the payment amount
is applied to each bill. The bill payment is identified by a bill payment id
. This value begins with blp
. In addition, disbursement information is available based on the type of payment.
{
"payments": [
{
"id": "stp02TAXHUYITPCGf3b5",
"vendorId": "{vendor_id}",
"billPayments": [
{
"id": "{bill_payment_id01}",
"billId": "{bill_id01}",
"amount": 228.99
},
{
"id": "{bill_payment_id02}",
"billId": "{bill_id02}",
"amount": 142.00
}
],
"description": "Multiple inv. (details on stub)",
"processDate": "2024-12-16",
"fundingAccount": {
"type": "BANK_ACCOUNT",
"id": "bac01123ABC456DEF789"
},
"amount": 370.99,
"processingOptions": {
"requestPayFaster": false,
"requestCheckDeliveryType": "STANDARD"
},
"transactionNumber": "EHHXAICWPQDUEIBOEAER",
"confirmationNumber": "P24121502 - 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": []
}
]
}
See the /v3/payments/bulk API for more information.
Updated 3 months ago