Payment notification payloads
IMPORTANT
At this time, the payment webhook notifications are available only for select BILL partners. We will provide more information for when payment webhook notifications will be available to all BILL v3 API users.
When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl
. See /v3/payments in the API reference for more information about the request and response fields.
Sample payment.updated
payloads
payment.updated
payloadsIn this sample unescaped JSON payload, the details of a payment are available. The notification provides a set of payment
fields.
You get
payment.updated
notifications when thestatus
changesWhen you create a payment, BILL sends you
payment.updated
notifications with the paymentstatus
value changes.
Field | Description |
---|---|
id | BILL-generated ID of the payment. The value begins with stp . |
billIds | List of bills that are paid |
transactionNumber | Payment transaction reference used as an external identifier. See /v3/payments in the API reference for more information. |
status | Payment status. See Single status payment values for the complete list of payment status values. |
createdBy | BILL-generated ID of the user that created the payment. The value begins with 006 . |
createdTime | Created date and time |
updatedTime | Updated date and time. This value updates for each payment status update. |
processDate | Payment process date |
funding | Payment funding information. The fields are based on the type .- BANK_ACCOUNT : id , type , name , and accountNumber - CARD_ACCOUNT : id , type , name , and last4 - WALLET : type - AP_CARD : id and type |
disbursement | Payment disbursement information. The disbursement object includes additional information when BILL starts processing a payment. See /v3/payments in the API reference for more information about the different disbursement type values. |
vendor | Vendor information. This includes vendor id and name . |
billingType | A payment object is created for each payment. billingType is the source of the payment object creation.- BDC : Payment made with the BILL web app or BILL API- BILL_AUTOPAY : Payment made with the BILL autopay feature- NET_SYNC_FROM_ONLINE_PAYMENT : Payment made outside BILL with the sync feature to a BILL customer- NET_SYNC_FROM_OFFLINE_PAYMENT : Payment made outside BILL with the sync feature to a customer outside BILL- RECURRING_PAYMENT : Payment made for a recurring bill |
Before money movement
Before BILL starts processing a payment, the disbursement
object includes arrivesByDate
, and the disbursementAccount
object is empty. All other fields are included in the payment.updated
payload.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "payment.updated",
"version": "1"
},
"payment": {
"id": "{payment_id}",
"billIds": [
"{bill_id}"
],
"transactionNumber": "{transaction_id}",
"status": "SCHEDULED",
"createdBy": "{user_id}",
"createdTime": "2025-12-16T23:56:52.127+00:00",
"updatedTime": "2025-12-17T23:56:52.127+00:00",
"processDate": "2025-12-17",
"funding": {
"amount": 228.99,
"currency": "USD",
"fundingAccount": {
"id": "bac01123ABC456DEF789",
"type": "BANK_ACCOUNT",
"name": "Noodle Soupsmith",
"accountNumber": "************1111"
}
},
"disbursement": {
"arrivesByDate": "2025-12-20",
"disbursementAccount": {}
},
"vendor": {
"id": "{vendor_id}",
"name": "Happy Music Supplies"
},
"billingType": "BILL_AUTOPAY"
}
}
When money movement begins
When BILL starts processing a payment, there is additional disbursement
information available in the payload. All other fields are included in the payment.updated
payload.
- The
disbursement
object includesamount
,currency
, andarrivesByDate
. - The
disbursementAccount
object includestype
andaccountNumber
.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "payment.updated",
"version": "1"
},
"payment": {
"id": "{payment_id}",
"billIds": [
"{bill_id}"
],
"transactionNumber": "{transaction_id}",
"status": "PROCESSED",
"createdBy": "{user_id}",
"createdTime": "2025-12-16T23:56:52.127+00:00",
"updatedTime": "2025-12-17T23:56:52.127+00:00",
"processDate": "2025-12-17",
"funding": {
"amount": 228.99,
"currency": "USD",
"fundingAccount": {
"id": "bac01123ABC456DEF789",
"type": "BANK_ACCOUNT",
"name": "Noodle Soupsmith",
"accountNumber": "************1111"
}
},
"disbursement": {
"amount": 228.99,
"currency": "USD",
"arrivesByDate": "2025-12-20",
"disbursementAccount": {
"type": "ACH",
"accountNumber": "******333"
}
},
"vendor": {
"id": "{vendor_id}",
"name": "Happy Music Supplies"
},
"billingType": "BILL_AUTOPAY"
}
}
Sample payment.failed
payload
payment.failed
payloadWhen your Create a payment (with POST /v3/payments
) or Create a bulk payment (with POST /v3/payments/bulk
) request fails, BILL sends you a notification with information to identify your payment request and with error messages to help you debug.
In this sample unescaped JSON payload, the details of a payment failure notification are available. The notification provides a set of payment
fields.
Field | Description |
---|---|
bills | List of bills and payment amounts that were listed in the payment request |
transactionNumber | Payment transaction reference used as an external identifier. See /v3/payments in the API reference for more information. |
createdBy | BILL-generated ID of the user that created the payment. The value begins with 006 . |
fundingAccount | Payment funding information |
vendor | Vendor information. This includes vendor id and name . |
errors | Payment failed reason. - code : Error code- message : Error message |
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "payment.failed",
"version": "1"
},
"payment": {
"bills": [
{
"id": "{bill_id01}",
"amount": 28.99
},
{
"id": "{bill_id02}",
"amount": 200
}
],
"transactionNumber": "{transaction_id}",
"createdBy": "{user_id}",
"fundingAccount": {
"id": "bac01123ABC456DEF789",
"type": "BANK_ACCOUNT"
},
"vendor": {
"id": "{vendor_id}",
"name": "Happy Music Supplies"
}
},
"errors": [
{
"code": "{error_code}",
"message": "Bank account is inactive."
},
{
"code": "{error_code}",
"message": "Bill ID not found."
}
]
}
Common error cases
Payment requests can fail for various reasons. This list highlights some of the more common error cases.
Common error cases |
---|
Bill ID not found. |
Vendor ID not found. |
Cannot overpay a bill. |
Invalid process date. |
Bank account is inactive. |
Card account is inactive. |
Updated 1 day ago