Payment notification payloads
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 getpayment.updated
notifications when thestatus
changesWhen you create a payment, BILL sends you
payment.updated
notifications with the paymentstatus
value changes.
Field | Description |
---|---|
| BILL-generated ID of the payment. The value begins with |
| List of bills that are paid |
| Payment transaction reference used as an external identifier. See /v3/payments in the API reference for more information. |
| Payment status. See Single status payment values for the complete list of payment |
| BILL-generated ID of the user that created the payment. The value begins with |
| Created date and time |
| Updated date and time. This value updates for each payment |
| Payment process date |
| Payment funding information. The fields are based on the
|
| Payment disbursement information. The |
| Vendor information. This includes vendor |
| A payment object is created for each payment.
|
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 |
---|---|
| List of bills and payment amounts that were listed in the payment request |
| Payment transaction reference used as an external identifier. See /v3/payments in the API reference for more information. |
| BILL-generated ID of the user that created the payment. The value begins with |
| Payment created date and time |
| Payment updated date and time |
| Payment funding information |
| Vendor information. This includes vendor |
| Payment failed reason.
|
{
"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}",
"createdTime": "2025-12-16T23:56:52.127+00:00",
"updatedTime": "2025-12-16T23:56:52.127+00:00",
"fundingAccount": {
"id": "bac01123ABC456DEF789",
"type": "BANK_ACCOUNT"
},
"vendor": {
"id": "{vendor_id}",
"name": "Happy Music Supplies"
}
},
"errors": [
{
"code": "{error_code}",
"message": "Bank account is inactive.",
"timestamp": "2025-12-16T23:56:52.127+00:00"
},
{
"code": "{error_code}",
"message": "Bill ID not found.",
"timestamp": "2025-12-16T23:56:52.127+00:00"
}
]
}
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 about 22 hours ago